كيفية إنشاء إضافة (Plugin) لـ Claude Code في 2026 (دليل عملي)

لإنشاء إضافة لـ Claude Code، ضع مهاراتك (skills) أو وكلاءك (agents) أو خطافاتك (hooks) أو إعدادات MCP في مجلد واحد يحتوي على ملف بيان .claude-plugin/plugin.json، واختبرها باستخدام claude --plugin-dir ./my-plugin، ثم وزّعها عبر متجر (marketplace) ليتمكن زملاؤك من تثبيتها. هذه هي الدورة كاملةً، ويمكنك أن تحصل على إضافة عاملة خلال خمس دقائق تقريبًا. أما الباقي فهو معرفة الأجزاء التي ينبغي تضمينها، وكيفية تجنّب خطأ المجلد الوحيد الذي يُفشل معظم المحاولات الأولى، وكيفية إصدارها ومشاركتها بعد أن تعمل.

نحن نُشغّل محرك المحتوى الخاص بـ TechRiseUps على Claude Code، وأسرع طريقة لنقل سير عمل من جهاز واحد إلى الفريق بأكمله هي حزمه كإضافة بدلًا من نسخ مجلدات .claude/ هنا وهناك. يشرح هذا الدليل بالضبط كيفية إنشاء إضافة لـ Claude Code في 2026، استنادًا إلى وثائق الإضافات الرسمية الحالية.

ما هي إضافة Claude Code؟

إضافة Claude Code هي مجلد قائم بذاته يحزم امتدادًا واحدًا أو أكثر — مهارات (skills)، أو وكلاء فرعيين (subagents)، أو خطافات (hooks)، أو خوادم MCP، أو خوادم LSP، أو مراقبات تعمل في الخلفية — خلف ملف بيان واحد. يمنح ملف البيان .claude-plugin/plugin.json الإضافةَ اسمًا ووصفًا وإصدارًا. وبمجرد التثبيت، يصبح كل ما تشحنه الإضافة مُنَطَّقًا تحت هذا الاسم (namespaced): فالمهارة المسمّاة hello داخل إضافة اسمها my-first-plugin تُستدعى عبر /my-first-plugin:hello، وهذا يمنع تعارض إضافتين تُعرّف كل منهما مهارة بالاسم نفسه. جوهر الإضافة، مقارنةً بالإعدادات المتناثرة في مجلد .claude/ الخاص بك، هو قابلية النقل: فهي تخضع للتحكم بالإصدارات كوحدة واحدة، وتُحدَّث بسلاسة، وتُثبَّت على جهاز شخص آخر بأمر واحد بدلًا من طقوس النسخ واللصق.

الإضافة مقابل الإعداد المستقل: أيهما تستخدم؟

يتيح لك Claude Code إضافة المهارات والوكلاء والخطافات بطريقتين، واختيار الطريقة الخاطئة يهدر الوقت. الإعداد المستقل في مجلد .claude/ مناسب للتعديلات الشخصية الخاصة بمشروع بعينه وللتجارب السريعة — تحصل على أسماء قصيرة مثل /deploy ودون أي عبء تغليف. أما الإضافة فهي الخيار الصحيح لحظة أن ترغب في مشاركة سير العمل، أو إعادة استخدامه عبر المشاريع، أو شحن تحديثات مُصدَّرة. والعلامة الدالة بسيطة: إن كنت أنت وحدك من سيُشغّله في مستودع واحد، فأبقِه مستقلًا؛ وإن احتاجه أي شخص آخر، فاجعله إضافة.

	مستقل (.claude/)	إضافة
اسم الاستدعاء	/hello	/my-plugin:hello
النطاق	مشروع واحد	أي مشروع، أي جهاز
المشاركة	نسخ يدوي	/plugin install من متجر
الإصدارات	لا يوجد	version صريح أو SHA لـ git
الأنسب لـ	التجارب الشخصية	التوزيع على الفريق والمجتمع

المسار المُوصى به هو أن تُنشئ نموذجًا أوليًا في .claude/ من أجل التكرار السريع، ثم تحوّله إلى إضافة عندما يستحق المشاركة.

خطوة بخطوة: أنشئ إضافتك الأولى

إليك أدنى بناء متكامل من البداية إلى النهاية. ينشئ إضافةً بمهارة واحدة ويختبرها محليًا، دون الحاجة إلى متجر.

1. أنشئ مجلد الإضافة.

mkdir my-first-plugin

2. أضِف ملف البيان في my-first-plugin/.claude-plugin/plugin.json:

{
  "name": "my-first-plugin",
  "description": "A greeting plugin to learn the basics",
  "version": "1.0.0",
  "author": { "name": "Your Name" }
}

الحقل name وحده هو المطلوب فعلًا؛ أما version وauthor فاختياريان لكن يجدر ضبطهما (مزيد عن الإصدارات أدناه).

3. أضِف مهارة. تقيم المهارات في skills/<name>/SKILL.md. أنشئ my-first-plugin/skills/hello/SKILL.md:

---
description: Greet the user with a friendly message
---

Greet the user warmly and ask how you can help them today.

4. اختبرها محليًا باستخدام الراية --plugin-dir — دون الحاجة إلى خطوة تثبيت:

claude --plugin-dir ./my-first-plugin

ثم شغّل /my-first-plugin:hello داخل الجلسة. وأثناء تحرير الملفات، شغّل /reload-plugins لالتقاط التغييرات دون إعادة تشغيل Claude Code. وإن كنت تفضّل عدم تمرير الراية في كل مرة تُطلق فيها، فإن claude plugin init my-tool يُنشئ هيكل إضافة داخل مجلد مهاراتك يُحمَّل تلقائيًا في الجلسة التالية.

هذه إضافة حقيقية عاملة. وكل ما بعد هذه النقطة هو إضافة مزيد من المكوّنات وشحنها.

ما الذي يوجد داخل الإضافة

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

المجلد / الملف	يحتوي على
.claude-plugin/plugin.json	ملف البيان (الاسم، الإصدار، البيانات الوصفية)
skills/<name>/SKILL.md	المهارات التي يستدعيها النموذج
agents/	تعريفات الوكلاء الفرعيين المخصصة
hooks/hooks.json	معالجات الأحداث (مثل الفحص عند كل تحرير)
.mcp.json	إعدادات خوادم MCP للأدوات الخارجية
.lsp.json	خوادم اللغات لذكاء الشيفرة
monitors/monitors.json	مراقبات خلفية تُنبّه Claude
bin/	ملفات تنفيذية تُضاف إلى مسار PATH في Bash أثناء التفعيل
settings.json	إعدادات افتراضية تُطبَّق عند التفعيل

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

الخطأ الذي يُفشل معظم الإضافات الأولى

إذا لم تُحمَّل مهارتك أو خطافك بصمت، فإن السبب يكاد يكون دائمًا واحدًا: وضع الملفات في المكان الخطأ. وحده plugin.json ينتمي إلى داخل .claude-plugin/. أما كل مجلد آخر — skills/ وagents/ وhooks/ وcommands/ — فيجب أن يقع عند جذر الإضافة، بمستوى واحد للأعلى. إن وضع skills/ داخل .claude-plugin/ هو أكثر أخطاء الإضافة الأولى شيوعًا، ولا يعطي Claude Code تحذيرًا صريحًا؛ إذ لا تظهر المكوّنات ببساطة.

جذر الإضافة هو مجلد الإضافة الخاص بها — المجلد الذي تمرّره إلى --plugin-dir — وليس أبدًا مجلد ~/.claude/ العام لديك. عندما لا يعمل شيء ما، صحّح الأخطاء بهذا الترتيب: تأكّد من أن بنية المجلدات عند الجذر، واختبر كل مكوّن على حِدة، وشغّل /reload-plugins، وتحقّق من ظهور الوكلاء في /context تحت Custom Agents. شغّل claude plugin validate لالتقاط مشكلات البيان والبنية قبل أن تكلّفك جلسة تصحيح كاملة.

توزيع إضافتك: المتاجر والإصدارات

--plugin-dir من أجلك أنت؛ أما المتجر (marketplace) فمن أجل الجميع سواك. المتجر ما هو إلا مستودع git يحتوي على ملف .claude-plugin/marketplace.json عند جذره يسرد إضافاتك ومن أين تُجلب كل واحدة. تدفعه إلى GitHub أو أي مضيف git، ويضيفه المستخدمون عبر /plugin marketplace add <owner/repo>، ثم يثبّتون منه الإضافات فرادى. لإبقاء إضافة داخلية، استضِف المتجر في مستودع خاص؛ وللوصول إلى جمهور أوسع، تُشغّل Anthropic كتالوجين عامّين — claude-plugins-official المُنسَّق، وclaude-community المجتمعي الذي يقبل مساهمات الأطراف الثالثة بعد المراجعة.

الإصدار هو الجزء الذي يتخطّاه الناس ثم يندمون. إن ضبطت version صريحًا في plugin.json، فلن يحصل المستخدمون على التحديثات إلا عندما ترفعه — وهو أمر متوقّع ومُوصى به لأي شيء يُشارَك. وإن أغفلته ووزّعت عبر git، فإن SHA للـ commit يصبح هو الإصدار، فيُحتسب كل commit إصدارًا جديدًا. اختر إصدارات صريحة لأي شيء يعتمد عليه فريق. وقبل أن تنشر أو تُقدّم، شغّل دائمًا claude plugin validate، وأضِف ملف README.md بملاحظات التثبيت والاستخدام، واطلب من شخص آخر أن يثبّتها من جديد — الانضباط نفسه الذي تطبّقه على تشغيل Claude Code في الأتمتة.

الأسئلة الشائعة

هل أحتاج إلى متجر لاستخدام إضافة؟

لا. الأمر claude --plugin-dir ./my-plugin يُحمّل إضافة مباشرةً من مجلد محلي لتلك الجلسة، ويمكن لـ claude plugin init أن يُنشئ هيكل واحدة تُحمَّل تلقائيًا من مجلد مهاراتك. لا تهم المتاجر إلا حين ترغب في توزيع إضافة على أشخاص أو أجهزة أخرى.

ما الفرق بين الإضافة والمهارة؟

المهارة قدرة واحدة — ملف SKILL.md يحتوي على تعليمات. أما الإضافة فهي حزمة يمكنها أن تجمع مهارات عديدة إضافةً إلى الوكلاء والخطافات وخوادم MCP خلف ملف بيان واحد مُصدَّر. لا بأس بإضافة ذات مهارة واحدة؛ بل يمكنك حتى وضع SKILL.md عند جذر الإضافة بدلًا من مجلد skills/.

لماذا لا تُحمَّل إضافتي؟

المُذنب المعتاد هو موضع المجلدات: skills/ وagents/ وhooks/ يجب أن تكون عند جذر الإضافة، ووحده plugin.json يوضع داخل .claude-plugin/. شغّل /reload-plugins، ثم claude plugin validate لإظهار أخطاء البنية والبيان.

كيف يحصل المستخدمون على تحديثات إضافتي؟

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

المصادر

• Claude Code Docs — Create plugins: البدء السريع الرسمي، وحقول البيان، وبنية المجلدات، و--plugin-dir، و/reload-plugins.
• Claude Code Docs — Create and distribute a plugin marketplace: marketplace.json، والاستضافة، والمستودعات الخاصة.
• DataCamp — How to Build Claude Code Plugins: دليل تعليمي خطوة بخطوة بأوامر claude plugin (Feb 2026).
• DEV Community — Building my first Claude Code Plugin: جولة مطوّر في إضافته الأولى (Dec 2025).