ما إضافات Claude Code وأسواقها؟ خطوات الاستخدام والإنشاء والنشر

في Claude Code، تُجمع المهارات والوكلاء الفرعيون والخطافات وإعدادات MCP في وحدة توزيع تسمى إضافة. أما الكتالوج الذي يسرد أسماء الإضافات ومصادرها فيسمى سوقًا. يتيح ذلك إعادة استخدام الإجراءات في مشاريعك الأخرى أو مشاركة مجموعة مشتركة من الامتدادات مع الفريق.

يتناول المقال تثبيت إضافة موجودة ثم إنشاء مهارة ترحيب وتوزيعها عبر كتالوج. تذكّر ثلاثة فروق: أولًا، الإضافة وكتالوج توزيعها يقعان في مستويين مختلفين. ثانيًا، تسجيل الكتالوج وتثبيت الإضافة عمليتان منفصلتان. ثالثًا، نجاح أمر التحقق لا يضمن صحة السلوك أو السلامة. تستند الخطوات إلى دليل الإنشاء الرسمي.

1. ما إضافات Claude Code؟

تجمع الإضافة امتدادات Claude Code في مجلد قابل للمشاركة وإعادة الاستخدام. ليس ضروريًا تضمين كل المكونات؛ يمكن أن تحتوي على مهارة واحدة فقط.

قد يكفي مجلد .claude/skills/ في المشروع للإجراءات الشخصية. تفيد الإضافات عندما تريد توزيع الحزمة نفسها في عدة أماكن وإدارة تحديثاتها. توجد امتدادات مثل دعم LSP والمراقبة، لكنها مشروطة بالبيئة ومسار التوزيع. البدء بمهارة صغيرة أسهل للفحص.

2. بنية الإضافة

هذه البنية القياسية لإضافة منفردة. إذا وفرت ملف تعريف، فمكانه .claude-plugin/plugin.json؛ وتوضع skills/ وagents/ وhooks/ في جذر الإضافة نفسها. كتالوج التوزيع marketplace.json منفصل؛ وفي المثال اللاحق يوضع في .claude-plugin/marketplace.json الخاص بالسوق.

my-plugin/
├── .claude-plugin/
│   └── plugin.json          # بيانات هذه الإضافة
├── skills/
│   └── code-review/SKILL.md
├── agents/
│   └── security-reviewer.md
├── hooks/hooks.json
├── .mcp.json
└── README.md

هذا مثال على plugin.json. يمكن حذف ملف التعريف تمامًا عند استخدام البنية القياسية وحدها. وإذا وفرته، فإن name مطلوب، بينما الوصف والإصدار اختياريان.

{
  "name": "my-first-plugin",
  "description": "إضافة ترحيب لتعلم الأساسيات",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

يصبح name أيضًا نطاق أسماء المهارات؛ والاستدعاء هنا هو /my-first-plugin:hello. في التوزيع الذي يُجلب من Git ويُخزّن مؤقتًا، تكون الأولوية لإصدار plugin.json ثم إصدار الإضافة في الكتالوج. إذا غاب الاثنان، يُستخدم SHA الالتزام الذي حُلّ إليه المصدر. إبقاء الإصدار الصريح كما هو يعني أن تغيير الشيفرة وحده لا يجعل الإضافة مؤهلة للتحديث. التحميل المباشر من مجلد محلي وcommand sources لهما قواعد أخرى. راجع توثيق إدارة الإصدارات.

3. استخدام /plugin والأسواق

ابدأ بـ/plugin. تفتح إدارة بتبويبات Discover وInstalled وMarketplaces وErrors. الأوامر الأساسية هي:

# إضافة سوق، أي كتالوج توزيع
/plugin marketplace add anthropics/claude-plugins-official
/plugin marketplace add ./my-marketplace              # مسار محلي
/plugin marketplace add https://example.com/marketplace.json

# اختر النطاق تفاعليًا وثبّت ثم افحص التفعيل
/plugin install plugin-name@marketplace-name
/plugin enable  plugin-name@marketplace-name
/plugin disable plugin-name@marketplace-name
/plugin uninstall plugin-name@marketplace-name

# المثبت عبر الأسواق؛ للتصفية استخدم --enabled / --disabled
/plugin list
/plugin list --enabled

# أعد تحميل التغييرات عند الحاجة وافحص النتيجة
/reload-plugins

إضافة الكتالوج وحدها لا تثبّت الإضافات. ثبّتها منفردة بعد التسجيل. يتيح الأمر التفاعلي /plugin install اختيار النطاق في شاشة التفاصيل. أما أمر الصدفة claude plugin install فيستخدم user افتراضيًا؛ حدّد --scope لتغييره.

بعد التثبيت، افحص هل النتيجة active أم بانتظار إعادة التحميل أم خطأ تحميل. قد تتأجل إعادة التحميل بسبب أثرها على ذاكرة التخزين المؤقت للموجّه. وفي الجلسات بلا طرفية، قد لا تسري تغييرات MCP الخاصة بالإضافة حتى الجلسة التالية. يعرض /plugin list التثبيت عبر الأسواق فقط، وليس كل ما يأتي عبر المزامنة أو مجلدات المهارات. راجع شروط التثبيت وإعادة التحميل؛ وإذا لم يتصل MCP، فانتقل إلى تشخيص أخطاء اتصال MCP.

4. ما السوق؟

السوق كتالوج يحتوي .claude-plugin/marketplace.json لسرد الإضافات ومصادرها، ويُقدّم عبر مستودع Git أو مسار محلي أو ملف مستضاف. توجد كتالوجات رسمية وأخرى للمجتمع.

إذا غاب الكتالوج، افحص التسجيل؛ وإذا غابت إضافة معينة، افحص اسمها ومصدرها. حتى في الكتالوج الداخلي، يجب أن يستطيع المستخدم الوصول إلى المستودع والإضافة نفسها معًا. عند توزيع JSON برابط، لا تُجلب محتويات الإضافات من المسارات النسبية لذلك الرابط.

5. إنشاء إضافتك ونشرها

ينشئ المثال مهارة ترحيب واحدة. جهّز البنية التالية: مجلد .claude-plugin الخارجي للكتالوج، والداخلي للإضافة المنفردة. نفّذ الأوامر من المجلد الأب الذي يحتوي my-marketplace.

my-marketplace/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── my-first-plugin/
        ├── .claude-plugin/
        │   └── plugin.json
        └── skills/
            └── hello/
                └── SKILL.md

(1) احفظ JSON السابق في الملف الداخلي my-marketplace/plugins/my-first-plugin/.claude-plugin/plugin.json. (2) احفظ التالي في my-marketplace/plugins/my-first-plugin/skills/hello/SKILL.md. يستخدم المثال disable-model-invocation: true لتُستعمل المهارة عند الاستدعاء الصريح فقط.

---
name: hello
description: تقديم تحية قصيرة باستخدام اسم
disable-model-invocation: true
---
رحّب بالمستخدم باختصار.
إذا وُجدت وسائط، أدرج ذلك الاسم في التحية.
الوسائط: $ARGUMENTS

(3) اكتب الكتالوج في الملف الخارجي my-marketplace/.claude-plugin/marketplace.json. تُفسَّر مسارات source النسبية انطلاقًا من جذر السوق، لا المجلد الذي يحتوي marketplace.json.

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "description": "كتالوج تدريبي لتوزيع مهارة ترحيب",
  "plugins": [
    {
      "name": "my-first-plugin",
      "source": "./plugins/my-first-plugin",
      "description": "مهارة تقدم تحية قصيرة باستخدام اسم"
    }
  ]
}

(4) تحقّق من الكتالوج والإضافة كلٍّ على حدة. يفحص الأول مخطط الكتالوج وplugin.json للعناصر المحلية، لكنه لا يقرأ كل ملف مهارة أو خطاف. يشمل الثاني أيضًا الملفات في المجلدات القياسية للإضافة المنفردة. لا يضمن أي منهما صحة التنفيذ أو السلامة.

claude plugin validate ./my-marketplace
claude plugin validate ./my-marketplace/plugins/my-first-plugin

# تحميل الإضافة المنفردة في هذه الجلسة للاختبار
claude --plugin-dir ./my-marketplace/plugins/my-first-plugin

في الجلسة التفاعلية التي تبدأ، نفّذ /my-first-plugin:hello Alex وتحقق من تحية قصيرة تتضمن Alex. الفحص الوظيفي يعني مراجعة المخرجات والآثار الجانبية غير المرغوبة، لا مجرد ظهور الأمر. إذا لم تُحمّل المهارة، افحص الاسمين في ملفي JSON ومسار source ومكان SKILL.md وترويسته.

(5) لاختبار مسار الكتالوج أيضًا، أنهِ جلسة الاختبار السابقة وابدأ Claude Code من دون --plugin-dir. الأوامر التالية تسجّل عناصر في إعداداتك، لذا جرّبها في مشروع تدريبي واختر نطاق التثبيت.

/plugin marketplace add ./my-marketplace
/plugin install my-first-plugin@my-plugins
/my-first-plugin:hello Alex

(6) للتوزيع، انشر محتويات my-marketplace بوصفها جذر مستودع Git يستطيع المستخدمون جلبه. أدرج مجلد plugins في الالتزام مع الكتالوج. يضيف المستخدمون owner/repo الحقيقي ويثبتون my-first-plugin@my-plugins نفسه. تعمل المسارات النسبية هنا مع التسجيل عبر Git أو مجلد محلي، ولا تعمل كما هي مع رابط marketplace.json منفرد. التفاصيل في إنشاء الكتالوجات وتوزيعها والتحقق منها.

لا تحتاج إلى طلب إدراج في الكتالوج الرسمي لتوزّع عبر مستودع Git الخاص بك. وإذا رغبت في قائمة المجتمع أيضًا، يمكن للمؤلف الفردي استخدام نموذج الإرسال في Console. نموذج claude.ai يتطلب مؤسسة Team/Enterprise وصلاحيات إدارية. الإرسال إلى community مختلف عن الإدراج في official الذي تختار Anthropic محتوياته.

6. نطاقات التثبيت والسلامة

النطاقات هي user لجميع مشاريعك، وproject لإعدادات المشروع المشتركة، وlocal لك وحدك في هذا المشروع. ميّز اختيار النطاق تفاعليًا عن user الافتراضي في CLI الصدفة. يتحكم المسؤول في إعدادات managed وتكون تغييرات المستخدم مقيدة.

يمكن للفريق مشاركة المصادر والتفعيل باستخدام extraKnownMarketplaces وenabledPlugins في .claude/settings.json. لكن كتابة إعدادات مشتركة تختلف عن اكتمال التثبيت على جهاز كل عضو. يحتاج كل عضو إلى تثبيت إضافات المصادر الخارجية. بعد الوثوق بالمشروع، افحص تسجيل الكتالوج وصلاحيات الوصول ونتائج التثبيت في كل بيئة.

الخلاصة

الإضافة وحدة توزيع للامتدادات، والسوق كتالوجها. يسجّل المستخدم الكتالوج ← يثبت الإضافات منفردة ← يفحص التفعيل والسلوك. أما المؤلف فيقوم بـإعداد الإضافة والكتالوج ← التحقق منهما ← استدعاء الوظيفة ← التوزيع عبر مستودع متاح. فحص النطاق وصلاحيات الوصول والإصدار المستخدم للتحديث يسهل إعادة التنفيذ في بيئات أخرى.

للتسجيل التلقائي للكتالوج الرسمي شروط، ولا تحمل الإضافات التي اجتازت المراجعة ضمانًا مطلقًا للسلوك. ابدأ بوظيفة واحدة تحتاجها، وتحقق من النتيجة قبل التوسع. آليات مرتبطة: خطافات Claude Code، وClaude Agent Skills، وMCP، وClaude Code Artifacts.

FAQ

س. ما الفرق بين الإضافة والمهارة؟
ج. المهارة إجراء يُنفّذ؛ والإضافة وحدة توزيع تجمعه مع الخطافات وإعدادات MCP ومكونات أخرى. يمكن استدعاء مهارة الإضافة صراحةً باستخدام /plugin-name:skill-name. يعتمد الاختيار التلقائي على الوصف والإعدادات.

س. لا أجد السوق الرسمي.
ج. يُسجّل claude-plugins-official تلقائيًا عند أول تشغيل تفاعلي، لكن استخدامًا غير تفاعلي سابقًا أو قيود الشبكة أو السياسات الإدارية قد تمنع ذلك. في بيئة تسمح به، جرّب /plugin marketplace add anthropics/claude-plugins-official. التسجيل وحده لا يثبت الإضافات المنفردة.

س. هل يستطيع أي شخص توزيع إضافته؟
ج. يمكن وضع الإضافة والكتالوج في مستودع Git متاح خاص بك. طلب قائمة المجتمع منفصل؛ ويستطيع المؤلف الفردي استخدام نموذج Console. مسار claude.ai له شروط مؤسسة وصلاحيات. افحص أيضًا أن source في الكتالوج يشير إلى الموقع الحقيقي للإضافة.

س. لماذا لا تتحدث الإضافة بعد تعديل الشيفرة؟
ج. في التوزيع المخزّن مؤقتًا عبر Git، تكون الأولوية لإصدار plugin.json. إبقاؤه ثابتًا وتغيير إصدار الكتالوج وحده لا يؤدي إلى التحديث. إذا غاب الإصدار عن كليهما، يُستخدم SHA التزام Git المحلول، لكن عملية التحديث وref المصدر مؤثران أيضًا. التحميل المحلي في موضعه ومصادر archive وcommand لها قواعد مختلفة.

س. هل نجاح validate يعني أن الإضافة آمنة؟
ج. لا. التحقق من البنية والإعدادات منفصل عن السلوك الفعلي والسلامة. التحقق من الكتالوج وحده لا يفحص أجسام المهارات وما شابه. تحقّق من الإضافة المنفردة واختبر الوظائف والآثار الجانبية. ولا تغني مراجعة المجتمع عن فحص الناشر والشيفرة المضمّنة.