الوحدة 12 — Plugins وmarketplaces: تعبئة أدواتك ومشاركتها

بنت الوحدات السابقة على انفراد ما يصنع قيمة Claude Code في فريق: skills، وسب-agents، وhooks، وخوادم MCP. تعيش كلّ لبنة في ركنها. وتَجمع الوحدة الختاميّة كلّ ذلك: الـplugin حزمة واحدة تُوحّد الكلّ، وتحمل نسخة، وتُثبَّت بأمر واحد، وتُوزَّع عبر marketplace. هي الصيغة المفضّلة حالما يتخطّى الفريق شخصَين.

Plugin أم تهيئة قائمة بذاتها؟

ابقَ على .claude/ قائمًا بذاته حين يكون المحتوى خاصًّا بمستودع واحد. انتقل إلى plugin حين تكون اللبنة قابلة لإعادة الاستعمال بين المشاريع، أو تحتاج نسخًا مستقلّة، أو يجب تثبيتها لدى فرق أخرى، أو تجمع عدّة مكوّنات (skill + سب-agent + hooks + خادم MCP).

يُتيح الـplugin تعبئة كلّ شيء: skills، وسب-agents، وworkflows، وhooks، وخوادم MCP، وخوادم LSP، وmonitors، وثيمات، وأنماط خرج، وملفّات تنفيذيّة. يعرض ذلك تحت namespace (kiosque-tools:deploy) يمنع التصادم.

تشريح plugin

الـplugin مجلّد يحمل manifest وحيدًا على المسار .claude-plugin/plugin.json. تعيش بقيّة المكوّنات في جذر الـplugin، لا داخل .claude-plugin/. اختلاط شائع: وضع agents/ أو hooks/ داخل .claude-plugin/ — عندئذٍ لا يجدها Claude Code.

البنية المرجعيّة:

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # manifest (اختياريّ إن كانت كلّ الأشياء في مواقعها الافتراضيّة)
├── skills/                   # <nom>/SKILL.md لكلّ skill
│   └── deploy/SKILL.md
├── commands/                 # skills بملفّات .md مسطّحة (متوافقة؛ فضِّل skills/)
├── agents/                   # سب-agents (.md مع frontmatter)
│   └── revieweur.md
├── workflows/                # سير عمل ديناميكيّ
├── hooks/
│   └── hooks.json            # hooks الـplugin
├── .mcp.json                 # خوادم MCP يُوفّرها الـplugin
├── .lsp.json                 # خوادم LSP
├── monitors/monitors.json    # monitors في الخلفيّة
├── bin/                      # ملفّات تنفيذيّة تُضاف إلى PATH حين يُفعَّل الـplugin
└── settings.json             # إعدادات افتراضيّة (تُقرأ فقط المفاتيح `agent` و`subagentStatusLine`)

يمكن لـplugin لا يعرض سوى skill واحدة أن يضع SKILL.md مباشرةً في جذر الـplugin، بلا مجلّد skills/. لكلّ ما يكبر، استخدم skills/<nom>/SKILL.md.

الـmanifest `plugin.json`

name وحده إلزاميّ، والـmanifest نفسه اختياريّ: بدونه، يكتشف Claude Code المكوّنات في مواقعها الافتراضيّة ويشتقّ الاسم من المجلّد. manifest أدنى:

{
  "name": "kiosque-tools",
  "displayName": "Kiosque Tools",
  "version": "1.0.0",
  "description": "أدوات Kiosque الداخليّة: مراجعة، اختبارات، نشر.",
  "author": { "name": "فريق Kiosque", "email": "dev@kiosque.example" }
}

مقتطف من الحقول الموثَّقة:

الحقل	الدور
`name`	معرّف kebab-case، يُستخدم namespace (`kiosque-tools:deploy`)
`displayName` / `description`	تُعرَض في `/plugin`
`version`	semver؛ يُثبِّت التثبيت
`author`، `homepage`، `repository`، `license`، `keywords`	بيانات وصفيّة للاكتشاف
`defaultEnabled`	`false` = يُثبَّت معطَّلًا (opt-in)
`skills`، `commands`، `agents`، `workflows`، `hooks`، `mcpServers`، `lspServers`	مسارات مخصّصة إلى المكوّنات
`dependencies`	plugins أخرى مطلوبة، بقيود semver
`userConfig`، `channels`	تهيئة المستخدم، قنوات المراسلة
`experimental.themes`، `experimental.monitors`	مكوّنات ذات مخطّط قابل للتطوّر

الحقول غير المعروفة في الجذر تُتَجاهَل — مفيد للتعايش مع package.json من npm.

ثلاثة متغيّرات بيئة رئيسة

${CLAUDE_PLUGIN_ROOT} — المسار المطلق لمجلّد التثبيت. للسكربتات والملفّات التنفيذيّة المُعبَّأة.
${CLAUDE_PLUGIN_DATA} — مجلّد دائم ينجو من التحديثات (~/.claude/plugins/data/{id}/). للتبعيّات المُثبَّتة عند أوّل استعمال.
${CLAUDE_PROJECT_DIR} — جذر المشروع.

الثلاثة مُصدَّرة إلى عمليّات hooks وMCP وLSP، ومُستبدَلة في محتوى skills وagents، وأوامر الـhooks/monitors، وcommand/args/env لخادم MCP stdio، وurl/headers لـHTTP.

التطوير والاختبار وإعادة التحميل

أربعة أوامر تُنظِّم التطوير.

الإطلاق الأوّل: claude plugin init <nom> يُنشئ plugin في ~/.claude/skills/<nom>/ مع manifest وSKILL.md بدائيّ، يُحمَّل في الجلسة التالية.
الاختبار المحلّيّ: claude --plugin-dir ./mon-plugin يُحمِّل الـplugin للجلسة. يقبل التراكم لعدّة plugins. إن تصادم الاسم مع plugin مُثبَّت، تسبق النسخة المحلّيّة.
إعادة التحميل: /reload-plugins يُطبِّق التغييرات (skills، وسب-agents، وhooks، وMCP، وLSP) دون إعادة تشغيل. --force يقبل إبطال ذاكرة الـprompt.
التحقّق: claude plugin validate ./mon-plugin --strict في CI.

في الجلسة، يفتح /plugin مدير الـplugins: تبويبات Installed وDiscover وErrors، ومفضّلات (زرّ f)، وترشيح بالاسم.

Marketplaces: العثور والتوزيع

نادرًا ما يُثبَّت plugin عبر --plugin-dir في الإنتاج؛ يأتي من marketplace، كتالوج plugins يُضاف مرّةً ثمّ تُثبَّت منه المُدخلات وفق الحاجة.

Marketplaces الرسميّة وإضافة المصادر

marketplaceان عامّان تديرهما Anthropic: claude-plugins-official (مسجَّل تلقائيًّا في أوّل جلسة تفاعليّة) و**claude-community** (تقديمات طرف ثالث بعد المراجعة، تُضاف بـ /plugin marketplace add anthropics/claude-plugins-community).

أربعة مصادر ممكنة للإضافة:

/plugin marketplace add owner/repo                              # GitHub
/plugin marketplace add https://gitlab.com/entreprise/plugins.git  # Git (https:// + .git)
/plugin marketplace add ./ma-marketplace                        # مسار محلّيّ
/plugin marketplace add https://exemple.com/marketplace.json    # JSON بعيد

اختصار: /plugin market. لاستهداف فرع: .../plugins.git#v1.0.0.

تثبيت plugin

/plugin install kiosque-tools@ma-marketplace

يُقتَرح ثلاثة نطاقات: User (كلّ مشاريعك)، وProject (مشترك، يُضاف إلى .claude/settings.json تحت الإدارة الإصداريّة)، وLocal (لك وحدك). منذ v2.1.221، يُفعِّل التثبيت أحيانًا الـplugin في الجلسة الحاليّة؛ وإلّا يوضّح الإشعار Run /reload-plugins to activate.

للتوزيع الداخليّ، استضِف الـmarketplace في مستودع خاصّ؛ يستخدم Claude Code اعتماداتك في Git للاستنساخ. يستطيع المديرون فرض marketplace عبر managed settings (extraKnownMarketplaces).

Kiosque: plugin `kiosque-tools` كامل

يُوحِّد فريق Kiosque ما بناه في الوحدات 9 إلى 11 في plugin واحد، منشور في marketplace خاصّة kiosque/plugins-interne.

بنية الـplugin

kiosque-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── deploy/SKILL.md
├── agents/
│   ├── revieweur.md
│   └── testeur.md
├── hooks/
│   └── hooks.json
├── .mcp.json
├── bin/
│   └── format-python.sh
└── README.md

`plugin.json`

{
  "name": "kiosque-tools",
  "displayName": "Kiosque Tools",
  "version": "1.0.0",
  "description": "أدوات Kiosque الداخليّة: مراجعة الشيفرة، اختبارات، نشر، وصول إلى GitHub وPostgres.",
  "author": {
    "name": "فريق Kiosque",
    "email": "dev@kiosque.example",
    "url": "https://kiosque.example"
  },
  "homepage": "https://kiosque.example/docs/plugin",
  "repository": "https://gitlab.kiosque.example/dev/kiosque-tools",
  "license": "UNLICENSED",
  "keywords": ["kiosque", "review", "deploy", "postgres", "github"],
  "defaultEnabled": true
}

`hooks/hooks.json`

الـhooks الثلاثة من الوحدة 9، هذه المرّة قابلة للنقل: ${CLAUDE_PLUGIN_ROOT} يحلّ محلّ ${CLAUDE_PROJECT_DIR} للسكربت المُعبَّأ، بينما تبقى سكربتات migrations/ والاختبارات مرتبطةً بالمشروع.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [
        { "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/bin/format-python.sh" }
      ]}
    ],
    "PreToolUse": [
      { "matcher": "Edit|Write", "hooks": [
        { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-paths.sh" }
      ]}
    ],
    "Stop": [
      { "hooks": [
        { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/require-green-tests.sh", "timeout": 300 }
      ]}
    ]
  }
}

ملاحظة: تنسيق Python يعيش في الـplugin (bin/format-python.sh)، مشتركًا بين جميع مشاريع Kiosque. الـhooks الخاصّة بالمستودع (حماية المسارات، الاختبارات المحلّيّة) تبقى داخل ${CLAUDE_PROJECT_DIR} — تلك هي القاعدة: ما يتغيّر حسب المشروع يبقى مشروعًا.

`.mcp.json`

يصبح خادم MCP من الوحدة 11 جزءًا من الـplugin. تظلّ الأسرار خارجًا، على شكل ${VAR}:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_MCP_TOKEN}" }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${KIOSQUE_DB_DSN}"]
    }
  }
}

سب-agents وskill

يستأنف agents/revieweur.md وagents/testeur.md تعريفات الوحدة 10، غير أنّها صارت الآن ضمن namespace kiosque-tools:revieweur وkiosque-tools:testeur. يستدعيها كريم عبر @"kiosque-tools:revieweur (agent)".

skills/deploy/SKILL.md يُدير النشر المتكرّر:

---
description: ينشر النسخة الجارية من Kiosque إلى بيئة الاختبار.
---

# /kiosque-tools:deploy

تسلسل خطوات نشر بيئة الاختبار:
1. تحقّق أنّ الفرع نظيف (`git status --porcelain`).
2. ابنِ صورة Docker موسومة بـSHA القصير.
3. ادفع الصورة إلى `registry.kiosque.example`.
4. حدِّث manifest Kubernetes وأعِد إطلاق النشر.
5. انتظر الانتقال إلى `Ready` ثمّ نفّذ مجموعة الدخان `make smoke`.

استخدم خادمَي MCP `github` و`postgres` المُعرَّفَين في هذا الـplugin
للتحقّق من مطابقة PR وصحّة قاعدة بيئة الاختبار على التوالي.

النشر والتثبيت

تُودِع نادية kiosque-tools/ في مستودع gitlab.kiosque.example/dev/plugins-interne، مع .claude-plugin/marketplace.json في الجذر يُحصي plugins الفريق. يضيف كلّ مطوّر الـmarketplace مرّةً واحدةً:

/plugin marketplace add https://gitlab.kiosque.example/dev/plugins-interne.git
/plugin install kiosque-tools@plugins-interne

يرى كريم موجزًا للتثبيت، ويختار نطاق User (يريد الـplugin في جميع مشاريع Kiosque). إن قالت الرسالة Run /reload-plugins to activate.، ينفّذ الأمر. من الجلسة الحاليّة، تعمل /kiosque-tools:deploy و@"kiosque-tools:revieweur (agent)" والـhooks.

بعد شهر، يدفع الفريق النسخة 1.1.0 مع سب-agent جديد. تُصعِّد نادية version، وتضع tag، وتدفع. يستعيد الزملاء التحديث عند الجلسة التالية، أو فورًا عبر /plugin marketplace update plugins-interne ثمّ /reload-plugins.

plugin واحد لعدّة مشاريع

الـplugin المثاليّ للفريق مستقلّ عن المشروع: ما يعمل في كلّ مكان يذهب إلى الـplugin، وما يتغيّر حسب المستودع يبقى في .claude/ للمستودع. هذا الفصل يتفادى النمط المضادّ «الـplugin الذي يعرف كلّ شيء عن Kiosque ولا يعمل في أيّ مكان آخر».

الخلاصة

Plugin يُعبِّئ skills وسب-agents وworkflows وhooks وخوادم MCP وLSP وmonitors وثيمات وملفّات تنفيذيّة تحت namespace وحيد.
البنية: .claude-plugin/plugin.json للـmanifest؛ كلّ ما تبقّى في جذر الـplugin، لا داخل .claude-plugin/.
الـmanifest الأدنى: name (kebab-case، يُستخدم namespace). حقول مفيدة: displayName وversion وdescription وdefaultEnabled وdependencies.
المتغيّرات: ${CLAUDE_PLUGIN_ROOT} (تثبيت)، و${CLAUDE_PLUGIN_DATA} (دائم)، و${CLAUDE_PROJECT_DIR} (مشروع).
التطوير: claude plugin init، و--plugin-dir للاختبار، و/reload-plugins لتطبيق التغييرات، وclaude plugin validate --strict في CI.
Marketplaces: الرسميّة (claude-plugins-official، وclaude-community)؛ مصادر مخصّصة عبر /plugin marketplace add (GitHub، ورابط Git، ومسار محلّيّ، وmarketplace.json بعيد).
التثبيت: /plugin install <plugin>@<marketplace> مع اختيار نطاق User / Project / Local. يفتح /plugin المدير الكامل.
لـKiosque، يجمع plugin واحد باسم kiosque-tools hooks قابلة للنقل، وسب-agentَي revieweur وtesteur، وخادمَي MCP GitHub وPostgres، وskill deploy — تحت إدارة إصداريّة في marketplace خاصّة بالفريق.

الوحدة التالية: سير العمل اليوميّ: الاستكشاف، والتصحيح، والاختبار، والمراجعة، والتسليم — كيف نُتابع كلّ هذه الأدوات في يوم هندسيّ نموذجيّ.

Plugin أم تهيئة قائمة بذاتها؟​

تشريح plugin​

الـmanifest plugin.json​

ثلاثة متغيّرات بيئة رئيسة​

التطوير والاختبار وإعادة التحميل​

Marketplaces: العثور والتوزيع​

Marketplaces الرسميّة وإضافة المصادر​

تثبيت plugin​

Kiosque: plugin kiosque-tools كامل​

بنية الـplugin​

plugin.json​

hooks/hooks.json​

.mcp.json​

سب-agents وskill​

النشر والتثبيت​

الخلاصة​