الـ Plugins

الـ plugins هي أعلى مستوى من آليات التوسعة في Claude Code. بتجمع skills و subagents و hooks و MCP servers وإعدادات LSP في حزمة واحدة قابلة للتثبيت. الفريق بيثبّت plugin واحد وكل حاجة بتتضبط فورًا — مفيش setup يدوي لكل مكوّن. الموديول ده بيغطي هيكل الـ plugin، صيغة الـ manifest، طرق التوزيع، وإزاي تبني واحد بنفسك.

هيكل الـ Plugin

الـ plugin هو مجلد بهيكل محدد. الملف الوحيد المطلوب هو .claude-plugin/plugin.json، الـ manifest اللي بيعرّف هوية الـ plugin. كل حاجة تانية اختيارية بس بتتبع conventions اللي Claude Code بيتعرّف عليها:

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Required manifest
├── skills/               # SKILL.md files
│   └── my-skill/
│       └── SKILL.md
├── agents/               # Subagent definitions
│   └── specialist.md
├── commands/             # Legacy command files (also work)
│   └── my-command.md
├── hooks/
│   └── hooks.json        # Plugin-scoped hooks
├── .mcp.json             # MCP server configs
├── .lsp.json             # LSP server configs
├── settings.json         # Default settings
└── bin/
    └── helper.sh

الـ manifest بيعرّف الـ plugin والـ metadata بتاعه:

{
  "name": "pr-review",
  "description": "Complete PR review workflow with security and test coverage checks",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "repository": "https://github.com/you/pr-review",
  "license": "MIT"
}

أوامر الـ plugin والـ skills اللي بيوفّرها بتكون namespaced كـ plugin-name:command-name عشان ما يحصلش تعارض مع إعدادات المشروع. شغّلها بالاسم الكامل، زي /pr-review:check-security.

ميزات الـ Manifest

الـ manifest بيدعم عدة خصائص قوية لضبط سلوك الـ plugin. خاصية userConfig بتعلن عن خيارات قابلة للتخصيص من المستخدم. الحقول المعلّمة بـ sensitive: true بتتخزّن في الـ system keychain بدل الإعدادات النصية:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "userConfig": {
    "apiKey": {
      "description": "API key for the integration",
      "sensitive": true
    },
    "region": {
      "description": "Deployment region",
      "default": "us-east-1"
    }
  }
}

الـ plugins بتاخد مجلد بيانات دائم عن طريق ${CLAUDE_PLUGIN_DATA} (من version 2.1.78). ده بيفضل موجود بين الجلسات، فمناسب للـ caches وملفات الحالة والـ databases. استخدم ${CLAUDE_PLUGIN_ROOT} عشان تشير لمسارات نسبية من مجلد تثبيت الـ plugin — ضروري للـ hooks وإعدادات الـ MCP:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/audit.js"
          }
        ]
      }
    ]
  }
}

مراقبات الـ plugins محتاجة Claude Code v2.1.105 أو أحدث. مفتاح الـ monitors في الـ manifest بيربط الـ plugin بأداة Monitor. ورّيه JSON file (أو حط الإعداد inline) وكل المراقبات اللي في الخلفية هتتفعّل تلقائي أول ما الـ plugin يتفعّل في بداية الجلسة، أو لما skill من الـ plugin يتستدعى. ده بيخلّي الـ plugin يشحن سلوك زي “راقب الـ CI وبلّغني على الفشل” أو “tail للـ dev server log” من غير ما المستخدم يضبط أي حاجة:

{
  "name": "ci-watcher",
  "version": "1.0.0",
  "monitors": "./monitors.json"
}

لما الـ manifest بيحدد مسار monitors خاص، الموقع الافتراضي monitors/monitors.json مبيتفحصش تاني — أضف الافتراضي صراحةً لو لسه عايزه يتحمّل مع ملفك المخصص.

دعم LSP بيضيف تكامل language server protocol في الوقت الفعلي. حط ملف .lsp.json في root الـ plugin عشان تضبط language servers بتوفّر تشخيصات فورية، go-to-definition، وبحث عن symbols وأنت بتشتغل:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact"
    }
  }
}

التوزيع والتطوير

جرّب الـ plugin محليًا بـ flag الـ --plugin-dir قبل ما توزّعه. ده بيحمّل الـ plugin للجلسة دي بس — بدون تثبيت:

claude --plugin-dir ./my-plugin
# Test multiple plugins simultaneously:
claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin

للـ plugins المستضافة كأرشيفات .zip، --plugin-url بيحمّلها ويثبّتها للجلسة الحالية بس من غير تثبيت دائم. كرّر الـ flag لعدة plugins:

claude --plugin-url https://example.com/my-plugin.zip
claude --plugin-url https://example.com/a.zip --plugin-url https://example.com/b.zip

استخدم --plugin-url بس مع روابط موثوقة — تحميل أرشيفات من مصادر خارجية بيشغّل كود طرف ثالث على جهازك.

استخدم /reload-plugins عشان تعمل hot-reload لملفات الـ plugin خلال التطوير من غير ما تعيد تشغيل الجلسة. ده بيعيد قراءة كل الـ manifests والـ skills والـ agents والـ hooks وإعدادات الـ MCP فورًا.

شاشات /plugin بتاعت Discover و Browse بقت بتعرض inventory كامل لكل اللي الـ plugin هيثبّته قبل ما تقرر — commands و agents و skills و hooks وأي MCP أو LSP servers بيشحنها. ده بيخلّي تقييم plugin من الـ marketplace قرار في شاشة واحدة: تقدر تتأكد إن plugin زي pr-review مش بيسجّل MCP servers أو hooks ما كنتش متوقعها، أو تشيك إن plugin للـ deploy فعلًا بيشحن الـ skill اللي جاي عشانها. Browse بيعرض المثبت عندك بنفس التفصيل؛ Discover بيعمل نفس الحاجة لكتالوج الـ marketplace. المعاينة للعلم بس — لازم تثبّت الـ plugin قبل ما أي مكون يشتغل.

توزيع الـ plugins بيتبع نموذج marketplace. الـ marketplace الرسمي من Anthropic هو claude-plugins-official. ضيف marketplaces تانية بـ /plugin marketplace add owner/repo-name. ثبّت plugins بـ /plugin install plugin-name أو claude plugin install plugin-name@marketplace:

# Install from official marketplace
/plugin install pr-review

# Install from GitHub
/plugin install github:username/my-plugin

# Install from local path (for testing)
/plugin install ./path/to/plugin

لما الـ plugin source يكون اختصار GitHub بصيغة owner/repo، Claude Code افتراضيًا بيعمل clone عن طريق SSH. ده بيتعطّل في الـ CI runners والـ containers أو أي بيئة مفيش فيها SSH key مضبوط لـ github.com. اضبط CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 عشان تجبر الـ clone يستخدم HTTPS بدالها — وباقي عملية التثبيت بتفضل زي ما هي:

# اجبر HTTPS في الـ CI لما تثبّت plugins
CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 claude plugin install owner/repo

لبيئات المؤسسات، ملف managed-mcp.json بيتحكم في أي MCP servers الـ plugins تقدر تستخدمها. إعدادات deniedPlugins وenabledPlugins وextraKnownMarketplaces وstrictKnownMarketplaces في الـ managed policy بتتحكم في أي plugins و marketplaces مسموح بيها على مستوى المؤسسة. الـ subagents بتاعة الـ plugins عندها frontmatter محدود — ما يقدروش يعرّفوا hooks أو mcpServers أو permissionMode عشان يمنعوا privilege escalation.

أوامر دورة الحياة المفيدة تشمل claude plugin list وclaude plugin enable وclaude plugin disable وclaude plugin uninstall وclaude plugin validate وclaude plugin details <name> (بيعرض مكونات الـ plugin والتكلفة المتوقعة من الـ tokens لكل جلسة) وclaude plugin tag (جديد في v2.1.121) اللي بيعمّل release git tag مع التحقق من الإصدار.

claude plugin enable وclaude plugin disable بيشغّلوا ويوقّفوا plugin مثبّت من غير ما يشيلوه. الاتنين بياخدوا <plugin> (أو <plugin>@<marketplace> لو في تعارض في الأسماء) و--scope بقيمة user أو project أو local (الافتراضي: user). التعطيل على نطاق project بيكتب الخيار في .claude/settings.json فالفريق كله يستلمه، أما user فبيخليه شخصي:

# شخصي: عطّل plugin مزعج ليك إنت بس
claude plugin disable formatter@anthropics/claude-plugins

# فريق: سيب الـ plugin في الإعدادات لكن عطّله على مستوى المشروع
claude plugin disable formatter --scope project

# فعّله تاني بعدين من غير ما تمسّ التثبيت أو الإصدار
claude plugin enable formatter --scope project

نمط الـ inline plugin (source: 'settings' من version 2.1.80) بيخلّيك تعرّف plugin مباشرة في ملف إعدادات من غير ما تحتاج repo منفصل. ده مفيد للأدوات الداخلية الصغيرة اللي ما تستاهلش repo كامل:

{
  "pluginMarketplaces": [
    {
      "name": "internal-tools",
      "source": "settings",
      "plugins": [
        {
          "name": "code-standards",
          "source": "./local-plugins/code-standards"
        }
      ]
    }
  ]
}