build claude code plugin يعني أن تجمع مهاراتك وخطافاتك وأوامرك في مجلد واحد له ملف تعريف اسمه plugin.json، فيُحمَّل المجلد كله دفعة واحدة بدل أن تنسخ كل ملف إلى مكانه في كل مشروع.
الحد الأدنى لذلك مجلد فيه .claude-plugin/plugin.json باسم لا يبدأ بكلمة claude، ومجلد skills/ فيه مهارة واحدة على الأقل داخل SKILL.md.
تجربته تبدأ بالأمر claude --plugin-dir ./my-plugin لجلسة واحدة، ويُفحص قبلها بالأمر claude plugin validate ./my-plugin.
بعد أن يعمل عندك، تقرر طريقة التوزيع: ترسل المجلد أو ملف zip مباشرة، أو تضعه في سوق خاص بفريقك، أو تقدّمه لدليل Anthropic بعد المراجعة.
ما الفرق بين المهارة والإضافة؟
المهارة مجلد فيه ملف SKILL.md يعلّم Claude طريقة عمل واحدة، وتعمل وحدها في مشروعك أو في مجلدك الشخصي. الإضافة حاوية تجمع المهارات والوكلاء الفرعيين والخطافات وخوادم MCP تحت اسم واحد، وتُنقل كوحدة واحدة إلى مشروع آخر أو إلى زميل.
الوثيقة الرسمية في Claude Code تقول الشيء نفسه بعبارة أقصر: الإضافة مجلد من المهارات والوكلاء والخطافات وخوادم MCP، مع ملف plugin.json يسمّيها. وتنصح بالبقاء على الإعداد المستقل ما دام يخدم مشروعًا واحدًا، وبالتحويل إلى إضافة حين تريد مشاركته مع الفريق، أو تثبيته في عدة مشاريع، أو إصدار نسخ محددة منه.
هناك فائدة لا تنتبه لها في البداية: كل مكوّن داخل الإضافة يأخذ اسمها بادئة. مهارة اسمها hello داخل إضافة اسمها my-plugin تُستدعى بالأمر /my-plugin:hello، فلا تتصادم مع مهارة بالاسم نفسه في إضافة أخرى. وهذا يعني أن اسم الإضافة يصبح جزءًا من كل أمر تكتبه، فاختره بعناية قبل أن يعتاد عليه الناس.
ما الذي يضعه المجلد، وأين؟
كل نوع من المكونات له مكان ثابت تحت جذر الإضافة. وجذر الإضافة هو المجلد الذي تمرره لـ --plugin-dir، لا مجلد ~/.claude/ نفسه. ولا تحتاج كل هذه المجلدات، فأضف ما تستعمله فقط.
| المكان | محتواه |
|---|---|
.claude-plugin/plugin.json | ملف التعريف، وهو الملف الوحيد المسموح داخل هذا المجلد |
skills/ | مجلد لكل مهارة، وداخل كل مجلد ملف SKILL.md |
commands/ | ملفات .md مسطحة، وهي الصيغة القديمة، والأفضل في الإضافات الجديدة استعمال skills/ |
agents/ | ملف .md لكل وكيل فرعي |
hooks/hooks.json | إعداد الخطافات، ويكون تحته مفتاح hooks في الأعلى |
.mcp.json | تعريف خوادم MCP |
وفي الإضافة مكونات أخرى هي LSP والمراقبات والثيمات، وهي للحالات المتقدمة ولا تلزم الإضافة الأولى.
أكثر ما يقع فيه الناس أن يضعوا skills/ داخل .claude-plugin/. الوثيقة واضحة هنا: ما يُحفظ داخل .claude-plugin/ غير ملف التعريف لا يُحمَّل. والمثال المقابل أن ملف .mcp.json الموضوع في ~/.claude/.mcp.json لن يُحمَّل من داخل إضافة، لأن الجذر المقصود هو مجلد الإضافة نفسه.
وهناك ملف يظن كثيرون أنه يدخل سياق Claude تلقائيًا: CLAUDE.md في جذر الإضافة لا يُحمَّل كسياق، والأداة تحذّرك منه عند الفحص. إن كانت لديك تعليمات تريد أن يتبعها Claude داخل الإضافة، ضعها في مهارة، لأن المهارة هي الصيغة التي تُحمَّل عند الحاجة.
وهناك قاعدة أخرى تنتبه لها حين يبدأ الكود بالكتابة داخل الإضافة: جذرها يتغير مع كل تحديث، فلا تكتب فيه ملفات الحالة أو المكتبات المثبتة. المتغير ${CLAUDE_PLUGIN_DATA} يشير إلى مجلد خاص بالإضافة يبقى عبر التحديثات، وتقول الوثيقة إنه يُحذف عند إلغاء تثبيت الإضافة من آخر مكان ثُبّتت فيه، إلا إذا استعملت الخيار --keep-data. أما ${CLAUDE_PLUGIN_ROOT} فيشير إلى نسخة الإضافة المثبتة، وهو ما تستعمله للسكربتات المرفقة بها.
الشجرة الأدنى تبدو هكذا:
my-plugin/
├── .claude-plugin/
│ └── plugin.json
└── skills/
└── review/
└── SKILL.mdوداخل SKILL.md يكفي أن تكتب في الأعلى ما يعرّف المهارة ثم التعليمات. وإذا أردت أن يبقى تشغيل المهارة بيدك وحدك، فأضف السطر disable-model-invocation: true في الـ frontmatter، فلن يشغّلها Claude من تلقاء نفسه. ولمحتوى SKILL.md نفسه وحقول الـ frontmatter الأخرى صفحة مرجعية مستقلة في وثائق Claude Code، أما خوادم MCP وسكربتات الخطافات فمواضيع برمجية لها أمثلتها الخاصة.
ملف plugin.json: الاسم وحده مطلوب
الملف اختياري من الناحية التقنية. بدونه يكتشف Claude Code المكونات في أماكنها الافتراضية، ويأخذ اسم الإضافة من اسم المجلد. لكنك ستريده لأنه يحمل الإصدار والوصف والمؤلف، وأي تعديل تريد أن تنقله إلى مسار غير افتراضي. هذا مثال بسيط:
{
"name": "my-plugin",
"description": "مراجعة ملفات الترجمة العربية قبل النشر",
"version": "1.0.0",
"author": {
"name": "اسمك"
}
}الحقل الوحيد المطلوب هو name، ويكون بالحروف الصغيرة والشرطات دون مسافات. أما version فله أثر عملي: حين تحدده يبقى المستخدمون على تلك النسخة حتى تغيّرها أنت.
الوصف يظهر لمن يتصفح الإضافة داخل /plugin، فاكتبه جملة يفهمها من لم يرَ الإضافة من قبل. والمؤلف يحتاج name داخله، أما email وurl فاختياريان. وأي مسار تكتبه في الملف يجب أن يبدأ بـ ./، فالمسار commands/foo.md بلا ./ يفشل في الفحص. ويجب أن يبقى المسار داخل مجلد الإضافة، فالمسار الذي يحتوي .. لا يُحمَّل، وتعرض لك صفحة /plugin في تبويب الأخطاء السبب.
الاسم له قيد لا تعرفه إلا حين تنشر. الاسم الذي يبدأ بـ claude- أو anthropic- أو anthropics- أو cc-plugin- يعطيك خطأ في الفحص. وكذلك الأسماء claude وanthropic وclaude-code وclaude-mods بالضبط، وأي اسم يضع official بجوار claude أو anthropic. ووجود كلمة claude كاملة في مكان آخر من الاسم يعطيك تحذيرًا فقط، مثل mcp-for-claude.
والمهم أن هذا القيد تفرضه أوامر الفحص والإنشاء والوسم، أما Claude Code نفسه فيحمّل الإضافة حتى لو رفضها الفحص. أي أن الاسم مشكلة نشر لا مشكلة تحميل، وستكتشفها حين تحاول التوزيع. وهذا ما تقوله الوثيقة، لكني شغّلت claude plugin validate من الإصدار 2.1.283 على الاسمين claude-helper وanthropic-tools فمرّا بـ Validation passed دون تحذير. لا تعتبر نجاح الفحص المحلي دليلًا على أن الاسم مقبول.
الاختبار قبل التوزيع
إذا لم يظهر تغيير بعد تعديل، فالوثيقة ترتّب الفحص هكذا: أولًا الفحص من الطرفية (تيرمينال)، ثم /reload-plugins داخل الجلسة، ثم تبويب /plugin الذي يعرض المكونات التي وجدها Claude Code، ثم claude plugin list. كل خطوة تخبرك بما فعله Claude Code بالإضافة، فتعرف أين تقع المشكلة.
أول خطوة هي الفحص:
claude plugin validate ./my-pluginإذا مرّ الفحص ستجد السطر Validation passed، وهو يعني أن الملف سليم من حيث البنية. وإن فشل فستجد فوق سطر النتيجة كل حقل يحتاج تصحيحًا. الخيار --strict يحوّل التحذيرات إلى أخطاء، وهو مفيد إذا شغّلت الفحص في سكربت آلي قبل كل نشر.
ثم تشغّلها في جلسة:
claude --plugin-dir ./my-pluginداخل الجلسة اكتب /my-plugin:hello أو اسم مهارتك. وبعد كل تعديل على الملفات شغّل /reload-plugins، فيطبع سطر Reloaded: مع عدد ما حُمّل. إن لم تظهر المهارة فافتح /plugin وانظر إلى تبويب الأخطاء، وهو يذكر المسار الذي لم يُعثر عليه. ولمراجعة سريعة من الطرفية (تيرمينال)، يعرض claude plugin list الإضافات مع حالة كل واحدة.
من الأخطاء التي لا تظهر لها رسالة أن تشير --plugin-dir إلى جذر مستودع فيه marketplace.json، بدل مجلد الإضافة نفسها. في هذه الحالة لا تُحمَّل الإضافات الموجودة داخل plugins/، ولن ترى أي خطأ. أشر الأمر إلى مجلد الإضافة الواحدة.
وإذا كان لديك عدة إضافات في مجلد واحد، فمرّر ذلك المجلد إلى --plugin-dir، وستُحمَّل كل مجلد فرعي فيه ملف .claude-plugin/plugin.json كإضافة مستقلة. وإذا كانت نسخة الإضافة تُبنى في خط تكامل مستمر وتُرفع كملف zip، فالخيار --plugin-url يحمّلها من رابط لجلسة واحدة. استعمله مع روابط تملكها أو تثق بها فقط، لأن الإضافة تضيف إلى جلستك ما فيها من خطافات وأوامر.
وإن أردت مساعدة في البناء بدل الكتابة من الصفر، فالوثيقة تذكر إضافة plugin-dev من السوق الرسمية claude-plugins-official. وبعد تثبيتها يكفي أن تكتب /plugin-dev:create-plugin مع وصف لما تريده، فيمشي معك في التصميم والإنشاء والفحص. وتقييم سلوك الإضافة بالأمر claude plugin eval اختبار منفصل عن الفحص والتحميل، ولا أشرحه هنا.
ماذا حدث حين شغّلت الخطوات بنفسي؟
بنيت الإضافة الدنيا من مجلد فارغ: ملف plugin.json باسم my-plugin، ومهارة واحدة في skills/hello/SKILL.md. ثم شغّلت claude plugin validate عليها وعلى ثلاث نسخ مكسورة منها، بإصدار Claude Code 2.1.283.
- الإضافة الدنيا:
Validation passed. - ملف
CLAUDE.mdفي جذر الإضافة:Validation passed with warnings، والتحذير يقول إنه لا يُحمَّل سياقًا وإن عليك وضع التعليمات في مهارة. - المسار
commands/foo.mdبلا./:Validation failedبخطأين، أحدهماPath not found. - الخيار
--strictمع تحذيرCLAUDE.md:Validation failed، وخرج الأمر بالرمز 1.
وما لم يلتقطه الفحص: وضع skills/ داخل .claude-plugin/ نجح بلا أي تحذير، مع أن الوثيقة تقول إن المهارات لا تُحمَّل من هذا المكان. فلا تكتفِ بنتيجة الفحص، وجرّب الإضافة في جلسة وافتح تبويب الأخطاء في /plugin.
ماذا لو كانت لديك مهارات داخل .claude/ من قبل؟
إن كانت مهاراتك موجودة في مجلد .claude/ داخل مشروع، فلا داعي لإعادة كتابتها. تنشئ مجلد الإضافة بجانب .claude/، وتنسخ skills/ وagents/ وcommands/ إليه كما هي، ثم تنقل إعدادات الخطافات من settings.json إلى hooks/hooks.json مع الإبقاء على الشكل نفسه.
وأهم ما تنتبه له هنا أن النسختين تبقيان محملتين معًا. المهارات والوكلاء لا يتصادمان، لأن نسخة الإضافة تحمل بادئة اسمها، فتعمل /deploy و/my-plugin:deploy معًا. أما الخطافات فليس لها بادئة، فإذا بقيت في الإعداد القديم وفي ملف الإضافة معًا تعمل مرتين في كل مرة يحدث فيها الحدث. لذلك احذف الأصل بعد أن تتأكد أن النسخة الجديدة تعمل.
وعند الاختبار تتحقق من كل مكون باسمه الجديد: المهارة التي كانت /deploy تصبح /my-plugin:deploy، والوكيل reviewer يصبح my-plugin:reviewer، والخطاف تتأكد منه بتشغيل الحدث الذي يطابقه. وإذا غاب شيء فالرجوع إلى ترتيب الاختبار الذي مرّ معك يكشف السبب بسرعة، لأن كل خطوة فيه تخص نوعًا واحدًا من المشاكل.
كيف توزّعها بعد أن تكتمل؟
للوثيقة ثلاث طرق واضحة. الأولى أن ترسل المجلد أو ملف zip إلى من تثق به دون نشر أي شيء، ولا يلزمك مستودع على GitHub لذلك. الثانية أن تضعها في سوق خاص بفريقك، فيضيفه الزملاء مرة واحدة، ويثبتون الإضافة بالاسم، ويصلهم كل تحديث تصدره. الثالثة أن تقدّمها إلى دليل Anthropic، وبعد المراجعة تظهر لمن يضيفها على claude.ai وفي Cowork، وتصل إلى Claude Code عبر حسابه. أما شروط التقديم وما تقتضيه المراجعة فلم أفتح صفحة التقديم نفسها، ولا أستطيع أن أنقلها بدقة.
ومن المهم أن تعرف أن المجلد نفسه يُثبَّت على claude.ai وفي Cowork، لكن بمجموعة فرعية من المكونات فقط. قبل أن تكتب في صفحة متجرك أن الخطافات أو الأوامر تعمل في كل مكان، راجع جدول دعم المكونات في الوثيقة، فهو يفصّل ما يعمل على كل سطح.
وقبل أن تنشر نسخة جديدة، شغّلها بـ --plugin-dir وجرّب أهم أوامرها أولًا. فمن ثبّت النسخة السابقة سيصله تغييرك حين ترفع الإصدار، والتراجع عن نسخة منشورة أصعب بكثير من تصحيحها قبل النشر.
ماذا لو لم تظهر مهارتك أو لم تعمل الإضافة على سطح آخر؟
إن كان سؤالك «وضعت مهارتي في المجلد ولا تظهر، ماذا أفعل؟» فتحقق أولًا أن المسار skills/اسم-المهارة/SKILL.md، وليس داخل .claude-plugin/. ثم شغّل /reload-plugins وافتح /plugin وانظر إلى تبويب الأخطاء.
وإن كان سؤالك «هل تعمل الإضافة نفسها على claude.ai؟» فالجواب أن المكونات التي يدعمها ذلك السطح تعمل، وليس كل ما في الإضافة. ابدأ بجدول دعم المكونات في الوثيقة قبل أن تعد أحدًا بشيء.
