دليل الملحقات: تحويل تهيئاتك ومهاراتك إلى حزم قابلة للمشاركة

📚 تنقل السلسلة: المقال السابق 37 نقاط الاستعادة والتراجع (Checkpoints) علمك كيفية استرجاع وحفظ كود ومحادثة الجلسة لحالة سابقة سليمة. وينتقل هذا المقال لشرح ميزة البناء والتوزيع - شرحنا في المقال 24 كيفية تثبيت واستخدام ملحقات المطورين الآخرين، ونشرح اليوم كيفية تصميم وبناء وتوزيع ملحقاتك الخاصة: كيفية تنظيم ملفات الملحق، ودور حقول ملف plugin.json بالتفصيل، وتضمين المهارات والوكلاء والخطافات، وإدارة التبعيات، وصياغة مستودع السوق لنشرها ومشاركتها مع فريق العمل. ويمثل هذا المقال الدليل المرجعي الكامل والمفصل للملحقات.

عند فحص تفاصيل ملحق مثبت بـ claude plugin details، تلاحظ في مخرجات المراجعة حجزاً لذاكرة السياق: يستهلك هذا الملحق قرابة 180 رمزاً (token) للجلسة، وتستهلك مهامه المدمجة (skills) قرابة 2400 و 1800 رمز عند تفعيلها.

يساعدنا هذا الفحص في فهم حقيقة الملحقات - فهي ليست صندوقاً مغلقاً مجهول التفاصيل، بل تتكون من مجموعة قطعة ومكونات برمجية محددة، تستهلك رصيداً من الذاكرة بحسب حجمها وآليات تفعيلها. وإتقان تصميم الملحقات يتطلب استيعاب بنيتها الهيكلية بدقة أولاً لتصاغ بشكل نظيف.

خضنا في المقال 24 تجارب استخدام الملحقات: إضافة الأسواق، والتثبيت، وتفعيل التحديثات بـ /reload-plugins ومراجعة الأمان. ولا نكرر تلك المهام هنا، بل نركز على معالجة الجوانب العميقة للمطورين - الهيكل البنيوي للملحق وتطويره ونشره للعام. لننتقل من مرحلة "المستخدم للملحق" إلى مرحلة "المهندس المصمم والبانى له".

يمثل هذا المقال مرجعاً تقنياً، وتتميز تفاصيله بالعمق وكثرة الحقول. تجنب حفظها دفعة واحدة، واكتفِ ببناء ملحق تجريبي بسيط ونشره، واستعن بالجداول كقاموس سريع للرجوع إليه عند الحاجة.

بعد قراءة هذا المقال، ستحصل على:

• الهيكل التنظيمي المعتمد للملفات، وقاعدة عزل مجلد .claude-plugin/ الخاصة بملف التهيئة الفردي.
• الدليل الكامل لحقول مستند plugin.json: المعرفات، والبيانات المرافقة، وتخصيص مسارات المكونات، والتبعيات.
• المكونات البرمجية المتاح تضمينها في الملحق (skill / command / agent / hook / MCP / LSP / monitor) وتحديد مواقعها وقيودها.
• أهمية توظيف متغيرات المسارات مثل ${CLAUDE_PLUGIN_ROOT} لتفادي توقف العمليات عند اختلاف الأجهزة.
• تطبيق عملي متكامل لتصميم ملحق من الصفر، وتجربته محلياً، وبناء سوق مصغر ونشره للفريق.
• تدارك مشاكل إصدارات الملحقات وإدارة التبعيات البرمجية للمشاريع المشتركة.

---

01 الهيكل التنظيمي المعتمد لملفات الملحق

تعرفنا في المقال 24 على البنية البسيطة للملحق. ولبناء ملحق حقيقي متكامل، يجب الالتزام بالبنية التنظيمية الكاملة للملفات لتفادي مشاكل التحميل:

القاعدة البرمجية ثابتة: يتكون الملحق من مجلد رئيسي يحتوي على مستند المواصفات والتهيئة، وتتوزع بقية المكونات البرمجية في مجلدات فرعية مستقلة في المجلد الرئيسي.

تشبيه: علبة ألعاب التركيب (الليغو). تحتوي الععلبة على عنصرين أساسيين - دفتر التعليمات والمواصفات الذي يوضح اسم اللعبة ومحتوياتها؛ و صناديق فرعية مقسمة لتوزيع قطع التركيب حسب نوعها (صندوق للعجلات، وصندوق للنوافذ). الملحق يتبع نفس التصميم: ملف plugin.json يمثل دفتر التعليمات، والمجلدات الفرعية مثل skills/ و agents/ و hooks/ تمثل الصناديق الفرعية المقسمة. ويُحفظ دفتر التعليمات في مكان محدد مستقل، وتنتشر صناديق القطع بجانبه - لتأسيس القاعدة التنظيمية التالية.

البنية الهيكلية الكاملة لمجلد الملحق:

my-plugin/
├── .claude-plugin/           # مجلد التهيئة الأساسي للملحق
│   └── plugin.json           # مستند التهيئة والمواصفات (يُحفظ بمفرده هنا)
├── skills/                   # مجلد المهارات المرفقة (مجلد مستقل لكل مهارة)
│   └── code-reviewer/
│       └── SKILL.md
├── commands/                 # مجلد الأوامر (النسخة الخفيفة للمهارات)
│   └── status.md
├── agents/                   # مجلد تعريف الوكلاء الفرعيين (subagents)
│   └── security-reviewer.md
├── hooks/                    # مجلد تعريف الخطافات البرمجية للمشروع
│   └── hooks.json
├── .mcp.json                 # ملف تعريف خوادم MCP الملحقة
├── .lsp.json                 # ملف تهيئة خادم بروتول اللغة LSP الملحق
├── bin/                      # الملفات التنفيذية المرفقة بمسار التشغيل PATH
├── scripts/                  # نصوص وأكواد تشغيل الخطافات والمهام
└── settings.json             # ملف الإعدادات الافتراضية للملحق

ونشدد على القاعدة التنظيمية الصارمة والمكتوبة بالخط العريض في التوثيق الرسمي:

يُخصص مجلد .claude-plugin/ لحفظ ملف plugin.json بمفرده. ويُحظر تماماً وضع بقية المجلدات المكونة للملحق (مثل skills/ أو agents/ أو hooks/) داخل مجلد .claude-plugin/ ويجب حفظها في المجلد الرئيسي للملحق مباشرة بجانبه.

يقع الكثير من المطورين في خطأ حفظ مجلد المهارات skills/ داخل مجلد .claude-plugin/ بالخطأ، مما يسبب فشل Claude Code في التعرف على المهارات برغم نجاح تحميل الملحق. تذكر دائماً: دفتر المواصفات في مجلد التهيئة الخاص به، والمكونات تنتشر بجانبه في الخارج.

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

💡 خلاصة سريعة: يتكون الملحق من ملف مواصفات أساسي (.claude-plugin/plugin.json) ومجلدات فرعية للمكونات في المجلد الرئيسي؛ والقاعدة الذهبية هي حفظ plugin.json بمفرده في مجلد .claude-plugin/ وبقاء المكونات بجانبه في الخارج.

---

02 حقول مستند التهيئة plugin.json بالتفصيل

يمثل ملف plugin.json العقل الحاكم للملحق حيث يحدد هويته ومكوناته وآلية تشغيله.

ويرجى العلم أن كتابة ملف plugin.json تعتبر اختيارية برمجياً. يوضح التوثيق: عند غياب الملف، يقوم Claude Code بالبحث التلقائي في المجلدات الفرعية الافتراضية (مثل skills/ و agents/) لتفعيل المكونات وتسمية الملحق باسم المجلد الحاضن له تلقائياً. ولكن لإضافة حقول الصلاحيات والمعلومات والمجلدات المخصصة، يتعين صياغة الملف.

المعرف الأساسي والوحيد للملحق (حقل إجباري)

عند كتابة ملف التهيئة، يتعين عليك كتابة الحقل التالي إجبارياً:

الحقل	نوع البيانات	دور الحقل والوصف
name	string	المعرف الفريد للملحق، ويُكتب بصيغة kebab-case (حروف صغيرة تفصلها شرطة دون مسافات)

أهمية حقل name: يمثل البادئة العازلة (namespace) لكافة مهارات ووكلاء الملحق. فإذا سميت الملحق plugin-dev وبداخله وكيل باسم agent-creator فإنه يستدعى في الواجهة كـ plugin-dev:agent-creator؛ وتستدعى مهاراته بـ /plugin-dev:xxx. وتضمن هذه الآلية عدم تداخل وتعارض أسماء المهارات البرمجية بين الملحقات المختلفة.

حقول البيانات الوصفية المرافقة (توصيف الملحق)

تساعد هذه الحقول المطورين في التعرف على دور وأهمية الملحق وتفاصيل نشره:

الحقل	دور الحقل والمهمة
displayName	الاسم الظاهر للمستخدم في القوائم ويدعم المسافات والحروف الكبيرة. وعند غيابه يُستخدم حقل name الافتراضي.
version	رقم الإصدار باتباع الصياغة المعيارية (semantic versioning). تفعيله يتطلب منك تعديله وتحديثه مع كل نشر جديد ليتلقى المستخدمون التحديثات (سنفصل هذه المشكلة في القسم 08).
description	سطر مبسط لشرح مهام وتأثير الملحق يُعرض للمستخدمين عند التثبيت.
author	معلومات المطور المصمم للملحق (الاسم والبريد الإلكتروني والموقع).
homepage / repository / license	رابط صفحة التوثيق / مستودع الكود / رخصة الاستخدام المعتمدة للملحق.
keywords	الكلمات الدلالية والوسوم المسهلة للعثور على الملحق في محركات البحث.

حقول تخصيص مسارات المكونات البرمجية

تستخدم هذه الحقول لتحديد مسارات ومجلدات مخصصة للمكونات في حال رغبتك في عدم استخدام المجلدات الافتراضية:

الحقل	دور الحقل والربط المعتمد
skills	إضافة وتحديد مسارات مجلدات مهارات إضافية (إضافة للمجلد الافتراضي).
commands / agents / outputStyles	تحديد مسارات مخصصة للأوامر والوكلاء والتنسيقات (إلغاء واستبدال للمسارات الافتراضية).
hooks / mcpServers / lspServers	مسارات ملفات التهيئة للخطافات وخوادم MCP و LSP، أو كتابة بيانات التهيئة الخاصة بها مباشرة.
dependencies	قائمة بالملحقات الخارجية التي يتطلبها عمل الملحق الحالي (القسم 08).

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

• إلغاء واستبدال المسارات الافتراضية: حقول commands و agents و outputStyles. عند تعيين مسار لحقل commands مثلاً، يتم إلغاء وتجاهل مجلد commands/ الافتراضي تماماً. وللإبقاء على المجلد الافتراضي مع المسار الجديد، يجب كتابتهما معاً كقائمة: "commands": ["./commands/", "./extras/"].
• الإضافة على المسار الافتراضي: حقل skills. يتم الإبقاء على تتبع وقراءة مجلد skills/ الافتراضي دوماً، وتتم قراءة وتضمين المجلدات الإضافية المكتوبة في هذا الحقل بجانبه.

تذكر هذه القاعدة لتفادي اختفاء مهارات أو وكلاء الملحق عند تغيير المسارات.

مسودة لملف تهيئة متكامل لملحق:

{
  "name": "deployment-tools",
  "displayName": "Deployment Tools",
  "version": "1.2.0",
  "description": "Deployment automation tools",
  "author": { "name": "Dev Team", "email": "dev@company.com" },
  "license": "MIT",
  "keywords": ["deployment", "ci-cd"]
}

💡 خلاصة سريعة: ملف plugin.json يحدد مواصفات الملحق， والحقل الإجباري الوحيد هو name لتأسيس البادئة العازلة؛ وانتبه لسلوك حقول المسارات لمعرفة ما يلغي المسارات الافتراضية (وكلاء وأوامر) وما يضيف عليها (مهارات).

---

03 المكونات البرمجية المتاح تضمينها في الملحق

يوضح الجدول التالي المكونات السبعة الأساسية المتاح تضمينها وربطها بالملحقات:

المكون	مجلد الحفظ	دور المكون في المشروع	آلية التفعيل والتشغيل
Skills	skills/<اسم_المهارة>/SKILL.md	مهارات برمجية مخصصة للجلسة (المقال 26)	استدعاء يدوي بـ /اسم_الملحق:اسم_المهارة أو تلقائياً من Claude
Commands	commands/*.md	النسخة الخفيفة للمهارات (يُنصح بالمهارات للملحقات الحديثة)	استدعاء يدوي بـ /اسم_الملحق:اسم_الأمر
Agents	agents/*.md	وكلاء فرعيون مخصصون لمهام البناء (المقال 23)	يظهر في قائمة /agents للتكليف اليدوي أو التلقائي
Hooks	hooks/hooks.json	خطافات برمجية ترتبط بأحداث الجلسة (المقال 33)	تعمل تلقائياً عند وقوع الأحداث المحددة للجلسة
MCP servers	.mcp.json	خوادم لربط خدمات خارجية للجلسة (المقال 22)	تُشغل وتُربط تلقائياً وتندرج أدواتها للجلسة
LSP servers	.lsp.json	خوادم بروتوكول اللغة لتسهيل تصفح الكود	تعمل تلقائياً لمساعدة Claude في التعرف على هياكل الكود
Monitors	monitors/monitors.json	مراقبة ملفات السجلات والعمليات والتنبيه	تعمل تلقائياً في الخلفية (ميزة تجريبية)

قيود وشروط حيوية للمكونات يذكرها التوثيق:

حظر وتجريد الوكلاء المرفقين بالملحقات من الصلاحيات الحساسة (Security Sandboxing):

لدواعي الأمان والحماية، يُحظر على الوكلاء الفرعيين (agents) المعرفين داخل الملحقات استخدام حقول التهيئة التالية في ملفاتهم: hooks و mcpServers و permissionMode.

تمنع هذه القاعدة الملحقات الخبيثة من تغيير صلاحيات وأمان جهاز المطور أو تشغيل خطافات خفية في الخلفية. وتقتصر حقول الوكيل المسموحة على: name و description و model و effort و maxTurns و tools و disallowedTools و skills و memory و background و isolation (حيث القيمة المسموحة لـ isolation هي "worktree" فقط).

الخطافات البرمجية وأحداث الجلسة المتعددة: تدعم الخطافات المدمجة بالملحق الاستماع لعشرات الأحداث الخاصة بدورة حياة الجلسة - بدءاً من تشغيل الجلسة SessionStart إلى ما قبل تشغيل الأدوات PreToolUse (مع صلاحية الاعتراض والمنع) وما بعد التشغيل PostToolUse وانتهاء الكتابة Stop وإغلاق الجلسة SessionEnd (تصل لثلاثين حدثاً سنفصلها في المقال 33).

تنوع آليات عمل الخطافات: لا تقتصر الخطافات على تشغيل أوامر shell (command) بل تدعم إرسال طلبات ويب (http) وتفعيل أدوات MCP (mcp_tool) وإجراء مراجعة لغوية برمجية (prompt) وتكليف وكلاء بمراجعة النتائج (agent).

ميزة مراقبة العمليات Monitors (تجريبية): تسمح للملحق بمراقبة وتتبع ملفات السجلات (log files) وتوجيه تنبيهات فورية لـ Claude ليتخذ إجراءات تصحيحية تلقائية. وتتطلب إصدار Claude Code v2.1.105 كحد أدنى وتعمل حصرياً في الواجهات التفاعلية.

ويدعم الملحق تفعيل مجلد bin/ لإدراج ملفاته التنفيذية ضمن مسار تشغيل النظام PATH للطرفية، وتعديل settings.json لتغيير الإعدادات الافتراضية (مثال: تعيين وكيل الملحق كوكيل رئيسي افتراضي للجلسة).

💡 خلاصة سريعة: يضم الملحق سبعة مكونات فرعية أساسية؛ وتذكر حظر الصلاحيات الحساسة للوكلاء الفرعيين للملحق (منع الخطافات وقواعد الصلاحيات المدمجة)، وطبيعة عمل ميزة مراقبة السجلات التجريبية.

---

04 استخدام متغيرات المسارات وتجنب الروابط المطلقة

يمثل استخدام متغيرات المسارات المبدأ الأساسي لضمان عمل الملحق بنجاح على أجهزة المطورين المختلفة وتفادي توقف العمليات.

لماذا نحتاج لهذه المتغيرات؟ إذا قمت بكتابة مسار مطلق لتشغيل نص برمجي للخطاف كالتالي /Users/username/my-plugin/scripts/format.sh، فبمجرد نقل الملحق لجهاز مطور آخر باسم مستخدم مختلف أو تحديث إصدار الملحق وتغيير مجلد التخزين، ستتوقف العملية تماماً بالخطأ لغياب المسار.

ولتفادي المشكلة، يوفر النظام ثلاثة متغيرات مسارات رئيسية يتم تعويضها ديناميكياً عند التشغيل:

متغير المسار	المسار الفعلي الذي يشير إليه	الغرض وحالات الاستخدام
${CLAUDE_PLUGIN_ROOT}	المسار المطلق لمجلد تثبيت الملحق الحالي	قراءة وتشغيل نصوص التنسيق والملفات التنفيذية والتهيئات المرفقة بالملحق.
${CLAUDE_PLUGIN_DATA}	المجلد الدائم المخصص لحفظ بيانات الملحق (لا يُحذف عند التحديث)	حفظ مكتبات تشغيل Node.js وسجلات العمليات وحالات الملحق المستمرة.
${CLAUDE_PROJECT_DIR}	المسار المطلق للمجلد الرئيسي للمشروع الحالي	قراءة إعدادات وملفات المشروع الذي يعمل عليه المطور.

تشبيه: مرجع الفهرس في الأوراق السائبة. عند كتابة إحالة في ورقة "يرجى مراجعة ملحق الورقة الحالية"، فإن انتقال الورقة لأي مكان يحفظ سلامة الإحالة لكونها نسبية لموقعها الحالي؛ بينما الإشارة لصفحة برقم محدد "راجع صفحة 87" ستفشل عند إعادة ترتيب الأوراق. متغير ${CLAUDE_PLUGIN_ROOT} يمثل الإحالة النسبية للموقع - فأينما نُقل الملحق أو عُين مجلد تشغيله، يشير المتغير للمجلد الرئيسي الحالي للملحق بنجاح.

مثال لتطبيق المتغير في تعريف خطاف برمجى (مع استخدام علامات الاقتباس لحماية المسارات التي تحوي مسافات):

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"${CLAUDE_PLUGIN_ROOT}\"/scripts/format-code.sh"
          }
        ]
      }
    ]
  }
}

uiجب مراعاة القاعدة الأمنية الهامة التي تفرضها خوارزميات التحديث:

عند تحديث إصدار الملحق، يتم إنشاء مجلد تثبيت جديد تماماً وتتغير قيمة ${CLAUDE_PLUGIN_ROOT} تبعاً له. ويتم الإبقاء على المجلد القديم لمدة 7 أيام لتسهيل النقل ثم يُحذف نهائياً. لذا يُحظر كتابة أو حفظ أي بيانات مستمرة أو ملفات إعدادات داخل مجلد الملحق الرئيسي، ويجب كتابتها في مجلد البيانات ${CLAUDE_PLUGIN_DATA} دوماً.

أما الإحالة لملفات خارج نطاق مجلد الملحق الرئيسي (ككتابة مسارات نسبية تبدأ بـ ../ للوصول لملفات خارجية) فتعتبر محظورة أمنياً ويتم إلغاؤها عند التثبيت لكون النظام ينقل ملفات المجلد الرئيسي فقط لمجلد التخزين المحمي ~/.claude/plugins/cache.

💡 خلاصة سريعة: يُمنع استخدام روابط مسارات مطلقة ويجب الاعتماد على ${CLAUDE_PLUGIN_ROOT} للملفات المرفقة و ${CLAUDE_PLUGIN_DATA} للبيانات المستمرة؛ ويُحظر تماماً الإحالة لملفات تقع خارج المجلد الرئيسي للملحق.

---

05 تطبيق عملي: تصميم وتجربة ملحق محلي

سنقوم الآن بتجربة عملية لتصميم ملحق بسيط باسم my-greeter يحتوي على مهارة ترحيب تفاعلية وتجربتها وتحديثها محلياً دون الحاجة لخطوات نشر معقدة.

الخطوة الأولى: بناء الهيكل التنظيمي للملحق

يوفر النظام أمراً مخصصاً لتوليد هيكل الملحق تلقائياً لتوفير الوقت:

claude plugin init my-greeter --with skills

تنشئ هذه العملية مجلداً للملحق باسم my-greeter يحتوي على مسودة ملف plugin.json ومجلد فرعي للمهارات في مجلد المهارات الشخصي لجهازك ~/.claude/skills/my-greeter/.

الخطوة الثانية: فحص الملفات المولدة

افحص محتويات المجلد للتحقق من بنيته التنظيمية:

ls -R ~/.claude/skills/my-greeter

النتيجة المتوقعة: ستشاهد ملف التهيئة plugin.json داخل مجلد .claude-plugin/ وتلاحظ مجلد المهارات فرعياً بجانبه في الخارج متوافقاً مع القاعدة التنظيمية التي شرحناها.

الخطوة الثالثة: كتابة وتعديل المهارة المرفقة بالملحق

افتح ملف المهارة المرفق ~/.claude/skills/my-greeter/skills/hello/SKILL.md (أو أنشئه) واكتب التوجيه التالي:

---
description: ترحيب ودي باللغة العربية باسم المستخدم الممرر
---

# Hello Skill

يرجى الترحيب بالمستخدم الذي يحمل اسم "$ARGUMENTS" باللغة العربية بأسلوب دافئ وودي، والاستفسار عن كيفية مساعدته اليوم.

نلاحظ إدراج متغير $ARGUMENTS لاستقبال اسم المستخدم الممرر عند استدعاء المهارة.

الخطوة الرابعة: تشغيل الجلسة مع تحميل الملحق المحلي

لتجربة الملحق محلياً دون تثبيته في النظام، شغل Claude Code مع خيار تمرير مجلد الملحق المخصص:

claude --plugin-dir ~/.claude/skills/my-greeter

النتيجة المتوقعة: يتم بدء تشغيل الجلسة بنجاح وقراءة الملحق. اكتب /help لتلاحظ إدراج المهارة المخصصة للترحيب ضمن القائمة باسم الملحق الفرعي.

الخطوة الخامسة: استدعاء وتجربة المهارة

استدعِ المهارة مع تمرير معلمة الاسم:

/my-greeter:hello Walter

النتيجة المتوقعة: يقوم Claude بتشغيل المهارة وعرض رسالة ترحيب ودية باللغة العربية تذكر اسم "Walter" والاستفسار عن مهام اليوم بنجاح، مما يؤكد سلامة بناء وترابط الملحق.

الخطوة السادسة: ميزة التحديث الفوري (Hot Reload)

عدل نص ملف المهارة SKILL.md بإضافة رموز تعبيرية (Emojis) واحفظ الملف. ودون إغلاق الجلسة اكتب التوجيه التالي:

/reload-plugins

وأعد كتابة أمر الترحيب مجدداً لتشاهد انعكاس التعديلات فوراً في الجلسة.

تذكر: تنعكس تعديلات ملفات المهارات SKILL.md فوراً في الجلسة، بينما تتطلب التعديلات الحاصلة على الخطافات أو خوادم MCP تشغيل أمر /reload-plugins أو إعادة بدء الجلسة لتطبيقها.

💡 خلاصة سريعة: خطوات التطبيق - تشغيل plugin init لبناء الهيكل ← كتابة المهارة في مجلد skills ← تشغيل الجلسة مع خيار --plugin-dir للتجربة ← استدعاء المهارة ببادئة الملحق /my-greeter:hello ← استخدام /reload-plugins لتحديث المكونات.

---

06 تهيئة ونشر الملحق عبر مستودع السوق (Marketplace)

بعد نجاح التجربة المحلية، لتتمكن من مشاركة الملحق مع بقية أعضاء الفريق ونشره، يتعين عليك تهيئة مستودع سوق (Marketplace) مخصص.

ونوضح الفارق الأساسي بين المفهومين لتفادي اللبس:

المفهوم التقني	طبيعته ودوره	مكان وأداة التهيئة
مصدر السوق (Marketplace Source)	ملف الفهرس العام الذي يضم أسماء الملحقات المتاحة وأماكن تحميلها.	ملف marketplace.json في المستودع العام.
مصدر الملحق (Plugin Source)	الملفات والمجلدات الفعلية الخاصة بكود الملحق الذي سيتم تحميله.	الحقل source المكتوب لكل ملحق داخل ملف الفهرس.

تشبيه: المتجر العام وموردو البضائع. يمثل "مصدر السوق" المتجر الذي يعرض كتالوج السلع المتوفرة وأسعارها؛ ويمثل "مصدر الملحق" المورد أو المصنع الفعلي الذي يتم شحن السلعة منه عند طلب الزبون. ويمكن أن يقع المتجر في خادم A، وتُشحن الملحقات من مستودعات GitHub مختلفة B و C مباشرة.

الملف الحاكم للسوق هو .claude-plugin/marketplace.json ويُحفظ في المجلد الرئيسي لمستودع السوق. الهيكل المبسط للملف:

{
  "name": "my-plugins",
  "owner": { "name": "Your Name" },
  "plugins": [
    {
      "name": "my-greeter",
      "source": "./plugins/my-greeter",
      "description": "A friendly greeting plugin"
    }
  ]
}

يجب توفير حقل name وحقل source لكل ملحق في القائمة. ويدعم حقل source خيارات النشر التالية:

• روابط نسبية: "./plugins/my-greeter" عند حفظ كود الملحق داخل نفس مستودع السوق (الخيار الأسهل).
• مستودع GitHub مستقل: { "source": "github", "repo": "owner/repo" } لشحن الملحق من مستودع خارجي مستقل.
• مجلد فرعي لمستودع git: بتحديد رابط المستودع ومسار المجلد الفرعي لتسهيل العمل في المشاريع الموحدة (monorepos) وتوفير حجم التحميل.
• حزم npm: { "source": "npm", "package": "@org/plugin" } للملحقات التي تُنشر كحزم مكتبية عامة.

خطوات بناء وتجربة سوق محلي: بافتراض تهيئة المجلد الرئيسي للسوق my-marketplace وبداخله ملف .claude-plugin/marketplace.json ومجلد الملحق ./plugins/my-greeter/، يمكنك تسجيل وتثبيت الملحق في Claude Code كالتالي:

/plugin marketplace add ./my-marketplace
/plugin install my-greeter@my-plugins

يقوم الأمر الأول بتسجيل السوق محلياً، ويقوم الأمر الثاني بتثبيت الملحق من السوق وتفعيله للجلسة لتتمكن من استدعاء مهاراته مباشرة باتباع نفس المسار المعتاد.

ولضمان خلو ملفات الملحق والسوق من الأخطاء الهيكلية قبل الرفع، شغل أداة الفحص الرسمية:

claude plugin validate ./my-marketplace

وتقوم الأداة بفحص تركيبة ملف marketplace.json والتحقق من صحة المسارات وخلوها من الروابط المحظورة وتوافق الإصدارات. ولتفحص كود الملحق الداخلي وصياغة مهاراته، وجه أداة الفحص لمجلد الملحق مباشرة (claude plugin validate ./my-marketplace/plugins/my-greeter).

وبعد التأكد من سلامة الفحص، ارفع المستودع لـ GitHub ليتمكن بقية الزملاء من تسجيل السوق وتثبيت ملحقاتك بكتابة أمر تسجيل السوق لعنوان المستودع العام /plugin marketplace add owner/repo.

💡 خلاصة سريعة: يتم نشر الملحقات بصياغة مستودع سوق يحتوي على ملف الفهرس .claude-plugin/marketplace.json؛ وتحدد خيارات source قنوات التحميل (روابط نسبية أو GitHub أو npm)؛ واستخدم claude plugin validate للفحص قبل النشر.

---

07 مقارنة بين مسارات توزيع الملحقات للمطور

يوضح الجدول التالي متى يُنصح باعتماد كل مسار لتوزيع وتجربة الملحقات:

مسار التوزيع	كيفية التشغيل والربط	الفئة المستهدفة والسيناريو	الخصائص والسرعة
مجلد المهارات الشخصي	حفظ المجلد في مسار ~/.claude/skills/	تجربة شخصية سريعة للمطور لحفظ تهيئاته الذاتية.	تحميل تلقائي للجلسات دون حاجة للتثبيت، وسرعة تحديث المهارات.
التشغيل المباشر للطرفية	استخدام خيار تشغيل --plugin-dir	اختبار أولي سريع لكود الملحق أثناء التطوير البرمجي.	تشغيل مؤقت يزول بنهاية الجلسة، ممتاز للتجارب النظيفة وتفادي تراكم الملفات.
مستودع السوق العام	إعداد ملف الفهرس وتثبيته بـ /plugin install	نشر الملحقات المعتمدة للفريق والمستودعات العامة للمشروع.	دعم كامل للإصدارات، والتحديثات التلقائية، والمشاركة البسيطة للمطورين.

نصيحة هامة لمرحلة التطوير: تجنب تضييع الوقت في تعديل ملفات السوق وإعادة التثبيت مع كل تعديل بسيط لكود الملحق. واعتمد على خيار --plugin-dir أو مجلد المهارات الشخصي لتطوير الملحق وتثبيته، وبمجرد وصولك لإصدار مستقر ونهائي، قم بنقله لمستودع السوق العام ونشره.

وننبه مستخدمي مجلد المهارات الشخصي والمحلي لخاصية تتبع المجلدات: عند حفظ مهارة في مجلد مهارات المشروع المحلي، يتم قراءتها حصرياً عند تشغيل Claude Code من المجلد الرئيسي للمشروع مباشرة، وبدء التشغيل من مجلدات فرعية قد يسبب تجاهل تحميلها. لذا يُفضل تشغيل /reload-plugins أو بدء الجلسة من مجلد المشروع الرئيسي دوماً.

💡 خلاصة سريعة: ثلاثة مسارات للعمل - الحفظ الشخصي للتفضيلات الذاتية (~/.claude/skills/)، والخيار المباشر للطرفية للتطوير الفوري (--plugin-dir)، ومستودع السوق للنشر والمشاركة المعتمدة للمطورين.

---

08 تحديات النشر: إدارة الإصدارات والتبعيات البرمجية

نختم بشرح نقطتين هامتين لضمان استقرار وتحديث الملحقات المنشورة للعام دون مشاكل.

أولاً: مشكلة تثبيت التحديثات وإصدارات الملحق

تعتبر هذه المشكلة من أكثر الجوانب إرباكاً للمطورين الجدد. كيف يقرأ Claude Code رقم الإصدار لتحديث الملحقات المثبتة؟ يتبع النظام المعايير التالية بالترتيب للتحقق:

1. حقل version المكتوب داخل ملف الملحق الأساسي plugin.json.
2. حقل version المكتوب للملحق في ملف فهرس السوق marketplace.json.
3. عند غياب الحقلين، يتم استخدام بصمة الـ git SHA الخاصة بآخر commit للمستودع كرقم إصدار تلقائي.

وينبه التوثيق الرسمي لخطورة تثبيت رقم الإصدار يدوياً دون تحديثه:

يؤدي تعيين حقل version إلى تثبيت حالة الملحق بشكل صارم. فإذا كتبت في الملف "version": "1.0.0" وقمت لاحقاً بتعديل كود المهارات ورفعها للمستودع دون تعديل هذا الحقل، فلن يتلقى المستخدمون التحديثات نهائياً لكون Claude Code يطابق رقم الإصدار ويكتفي بقراءة النسخة المخزنة مؤقتاً لديه دون تحميل الكود الجديد.

ولتفادي هذه المشكلة، اتبع أحد المسارين التاليين:

• مسار التحديثات الصارمة المعتمدة: تعيين رقم إصدار يدوي (مثال 1.0.1 ثم 1.0.2...) وتعديله وتحديثه يدوياً مع كل عملية رفع برمجية جديدة للمستودع. ويناسب هذا المسار الملحقات العامة والمستقرة المنشورة للجمهور.
• مسار التحديث التلقائي المستمر: حذف وتجنب كتابة حقل version نهائياً في ملف التهيئة ومستند السوق. وبذلك يعتمد النظام على بصمة git SHA تلقائياً لتحديث الملحق مع كل commit جديد ترفعه للمستودع بشكل فوري وتلقائي. ويناسب هذا المسار الملحقات الداخلية والخاصة بالفريق لتسريع العمل وتفادي نسيان تحديث الأرقام.

ويُحذر التوثيق من كتابة رقم الإصدار في ملف التهيئة وفهرس السوق معاً بقيم مختلفة لكون قيم ملف التهيئة الداخلي تلغي وتتفوق على قيم فهرس السوق وتسبب فشل التحديثات الصامتة.

ثانياً: إدارة التبعيات البرمجية للملحق

إذا كان ملحقك يعتمد على مهارات أو ميزات ملحق خارجي آخر ليعمل (مثال: ملحق مراجعة الكود يتطلب ملحق فحص قواعد البيانات)، يمكنك كتابة هذه المتطلبات في حقل dependencies ليتولى النظام تثبيتها تلقائياً:

{
  "name": "my-plugin",
  "dependencies": [
    "helper-lib",
    { "name": "secrets-vault", "version": "~2.1.0" }
  ]
}

عند قيام المطور بتثبيت ملحقك، يفحص Claude Code قائمة التبعيات ويقوم بتحميل وتثبيت الملحقات المطلوبة تلقائياً بالخلفية لضمان سلامة العمل. ويمكنك تحديد قيود الإصدارات للتبعيات باستخدام صياغة semver (مثل ~2.1.0) لحماية الملحق من التحديثات الرئيسية الخارجية التي قد تسبب كسر الأكواد المدمجة.

وعند إلغاء تثبيت الملحق، يمكنك كتابة خيار التنظيف الصارم claude plugin uninstall --prune ليقوم النظام بإزالة وتطهير كافة الملحقات التابعة التي تم تثبيتها تلقائياً بالخلفية ولم يعد لها حاجة في النظام حالياً، مع الحفاظ على الملحقات التي قمت بتثبيتها يدوياً دون مساس.

💡 خلاصة سريعة: تثبيت رقم الإصدار يدوياً يمنع تحديث الملحق لدى المستخدمين في حال عدم تعديل الرقم مع كل رفع برمجى، ويُفضل تجنب كتابته للمستودعات الداخلية للاعتماد على بصمة SHA تلقائياً؛ وتُدار التبعيات بحقل dependencies لتثبيتها وإلغائها تلقائياً بالخلفية.

---

09 ملخص

شرحنا في هذا الدليل المرجعي الهياكل والمواصفات الكاملة لتصميم وبناء ونشر الملحقات (Plugins) لـ Claude Code.

لنراجع النقاط الأساسية معاً:

العنصر البرمجى	المواصفات الفنية والخطوات	نقاط هامة
الهيكل التنظيمي للملفات	مجلد التهيئة ومجلدات المكونات	يُحفظ ملف التهيئة plugin.json بمفرده في مجلد .claude-plugin/ وتنتشر بقية المكونات في المجلد الرئيسي.
المعرف البنيوي للملحق	حقل name الاجباري	يحدد البادئة العازلة (namespace) لكافة مهارات ووكلاء الملحق لمنع تعارض الأسماء المكررة.
تحديد مسارات المكونات	سلوك حقول التهيئة للمسارات	حقول تكتفي بالإضافة على المسار الافتراضي (المهارات) وأخرى تلغيه وتستبدله بالكامل (الوكلاء والأوامر).
المكونات البرمجية المتاحة	سبعة مكونات فرعية أساسية	تشمل المهارات، والوكلاء، والخطافات، وخوادم MCP و LSP، مع خضوع وكلاء الملحق لحظر الصلاحيات الحساسة.
استخدام روابط المسارات	توظيف متغيرات المسارات	يُمنع استخدام المسارات المطلقة نهائياً ويجب استخدام ${CLAUDE_PLUGIN_ROOT} للمكونات و ${CLAUDE_PLUGIN_DATA} للبيانات.
التطوير والتجربة محلياً	أوامر init و --plugin-dir	استخدام تهيئة المهارات الشخصية لتسريع التطوير، وأداة reload لتحديث المكونات الحية في الجلسة.
تأسيس ونشر الأسواق	مستند الفهرس marketplace.json	صياغة حقول التحميل للملحقات وفحص الملفات بأداة التحقق المدمجة plugin validate قبل النشر.
إدارة تحديثات الإصدارات	سلوك حقل version والتبعيات	نسيان تحديث الإصدار اليدوي يعطل التحديثات لدى المستخدمين، ويُفضل التبعيات البرمجية لإدارة التكامل التلقائي.

يمكنك الآن: تصميم وبناء حزمة ملحق مخصصة متكاملة وتوزيع ملفاتها ومجلداتها بشكل سليم، وتحديد الصلاحيات والمسارات للمكونات السبعة المتاحة، وتجنب المسارات المطلقة لضمان عمل الملحق عبر الأجهزة المختلفة، وتطوير وتحديث الملحق محلياً بـ --plugin-dir وبث التحديثات بـ /reload-plugins وإلغاء الإصدارات اليدوية للأدوات الخاصة لضمان التحديث المستمر بـ SHA، ونشر الملحق عبر مستودع السوق وإضافة التبعيات اللازمة له. هذا الدليل يمنحك الصلاحيات الكاملة لصياغة ونشر أدوات برمجية مخصصة ومشاركتها مع كامل مجتمع المطورين.

تذكر دائماً تشغيل أداة التحقق plugin validate للتأكد من سلامة ملفات الملحق قبل نشرها.

---

المقال القادم سنبدأ بالمجموعة السادسة "مشاريع وتطبيقات عملية (Real-world Projects)" وبدء المقال 39 "التطبيق العملي الأول: بناء ميزة كاملة من الصفر" - فبعد دراسة القواعد والنظريات وتفصيل الصلاحيات والمهارات والملحقات والخطافات ونقاط الاستعادة والتحكم، سننتقل للمرحلة الأكثر تشويقاً: تطبيق هذه الأدوات والمهارات مجتمعة لبناء ميزة برمجية كاملة في مشروع حقيقي من البداية وحتى التسليم والرفع، لمشاهدة كيف تترابط وتتكامل هذه الأدوات يداً بيد في بيئات العمل الحقيقية. سنبدأ العمل التطبيقي في المقال القادم.

---

قراءات موصى بها

• مجلدات وملفات تهيئة Claude Code في المشاريع البرمجية
• مستندات التطوير البرمجى وأدوات تشغيل SDK للوكيل
• إدارة سياق الجلسات وتقليل استهلاك رصيد الرموز