ما هي إضافات Claude Code وكيف تعمل وما تكلفتها؟

ما هي إضافة Claude Code

إضافة Claude Code هي دليل واحد من المكونات التي يحمّلها Claude Code ويديرها كوحدة واحدة. هذه المكونات هي المهارات (skills)، والوكلاء (agents)، والخطافات (hooks)، وخوادم MCP، وخوادم LSP، ومراقبات الخلفية. يؤدي تثبيت الإضافة إلى إضافة جميع أجزائها دفعة واحدة تحت اسم واحد، ويؤدي تعطيلها إلى إزالتها بالطريقة نفسها.

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

يحدد ملف البيان الاختياري في .claude-plugin/plugin.json اسم الإضافة، ويصبح ذلك الاسم مساحة أسماء (namespace). يتم استدعاء مهارة في إضافة تسمى commit-commands بالصيغة /commit-commands:commit، لذا يمكن لإضافتين توفير مهارة تسمى commit دون أن تحجب إحداهما الأخرى. يتم تحديد نطاق وكلاء الإضافة بالطريقة نفسها في قائمة @-mention، كـ plugin-name:agent-name.

الإضافة (Plugin)، أو المهارة (Skill)، أو خادم MCP، أو ملف القواعد

تُستخدم هذه المصطلحات الأربعة وكأنها متنافسة، لكنها ليست كذلك، ومن المفيد توضيح الحدود الفاصلة بينها مرة واحدة.

• المهارة (Skill) هي وحدة تعليمات واحدة يحمّلها Claude عندما يستدعيها تنفيذ المهمة. راجع ماهية مهارة الوكيل (Agent Skill) فعلياً.
• خادم MCP هو عملية منفصلة تعرض أدوات للوكيل عبر بروتوكول معين، وغالباً ما يكون خدمة شبكة تشغلها بنفسك.
• ملف القواعد (Rules file) مثل CLAUDE.md هو سياق للمشروع يُقرأ عند بدء الجلسة ويُطبّق على كل شيء.
• الإضافة (Plugin) هي حاوية يمكنها تجميع المهارات، والوكلاء، والخطافات (hooks)، وتعريفات خادم MCP معاً، بالإضافة إلى رقم إصدار وقناة توزيع.

لذا، السؤال الذي تجيب عليه الإضافة ليس "ما الذي يمكن للوكيل فعله"، بل "كيف أوصل هذا لفريقي وأحدّثه في الشهر القادم". إذا كنت تختار بين المصطلحات الثلاثة الأولى، فإن مقارنة المهارات وخوادم MCP وملفات القواعد تغطي هذا القرار بالتفصيل. وإذا كان جانب MCP هو ما يهمك، فإن تشغيل خوادم MCP الخاصة بك على خادم افتراضي خاص (VPS) يغطي جانب الاستضافة.

مواقع الإضافات ومحتوياتها

تُنسخ الإضافة المثبتة من المتجر إلى ذاكرة تخزين مؤقت محلية في ~/.claude/plugins/cache بدلاً من تشغيلها من المسار الذي استُنسخت منه. تحصل كل نسخة مثبتة على دليل خاص بها. عند التحديث أو إلغاء التثبيت، يُصنّف دليل النسخة القديمة كـ "يتيم" ويُحذف بعد أسبوعين تقريباً، مما يضمن استمرار الجلسة التي حمّلت النسخة القديمة في العمل دون فشل أثناء تنفيذ المهام.

بما أن المسار يتغير مع كل تحديث، يجب ألا تضع الإضافة موقعها الخاص بشكل ثابت (hardcode). تستخدم الخطافات (hooks) وإعدادات MCP داخل الإضافة المتغير ${CLAUDE_PLUGIN_ROOT}، الذي يُترجم إلى دليل التثبيت الحالي. أما البيانات التي يجب أن تبقى بعد التحديث فتوضع في ${CLAUDE_PLUGIN_DATA}، الذي يُترجم إلى دليل ثابت تحت ~/.claude/plugins/data/.

يُنسخ دليل الإضافة فقط إلى ذاكرة التخزين المؤقت، وهذا يؤدي إلى مشكلة شائعة. المسار الذي يشير إلى خارج جذر الإضافة، مثل ../shared-utils، يعمل أثناء التطوير باستخدام مسار محلي ولكنه يتعطل بعد التثبيت، لأن تلك الملفات لم تُنسخ أبداً.

يبدو الهيكل كما يلي:

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── code-review/
│       └── SKILL.md
├── agents/
├── hooks/
│   └── hooks.json
├── .mcp.json
└── bin/

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

بيان الإضافة (manifest) نفسه صغير الحجم.

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

كيفية تثبيت إضافة Claude Code

تتكون عملية التثبيت من خطوتين، ولا تقوم الخطوة الأولى بتثبيت أي شيء. أنت تضيف سوقاً (marketplace)، وهو عبارة عن فهرس للإضافات، ثم تثبت الإضافات الفردية منه. يتم تسجيل سوق Anthropic الرسمي، claude-plugins-official، تلقائياً لك في المرة الأولى التي تبدأ فيها Claude Code بشكل تفاعلي. أما الأسواق الأخرى، فيجب عليك إضافتها بنفسك.

/plugin marketplace add anthropics/claude-code
/plugin install commit-commands@claude-code-plugins

لاحظ أن المستودع هو anthropics/claude-code بينما يحمل السوق الاسم claude-code-plugins. يأتي الاسم من ملف الفهرس الموجود داخل المستودع، وليس من مسار المستودع، لذا اقرأ اسم السوق من علامة التبويب Marketplaces في /plugin قبل كتابة أمر التثبيت.

بعد التثبيت، اقرأ سطر الملخص. تعني Plugin is now active. أن المكونات قد حُمِّلت في هذه الجلسة. تعني Run /reload-plugins to activate. أنها لم تُحمَّل، وتحتاج إلى تشغيل ذلك الأمر. إذا حذرتك /reload-plugins من أنها ستعيد قراءة المحادثة، أعد تشغيلها باستخدام /reload-plugins --force. بعد ذلك، تأكد من وجود الإضافة فعلياً: تعرض /plugin الإضافة تحت علامة التبويب Installed، وتدرج /help مهاراتها تحت Custom commands، بينما تظهر أي إضافة فشل تحميلها تحت علامة التبويب Errors مع ذكر السبب.

يطلب التثبيت تحديد نطاق (scope)، ويحدد النطاق من الذي سيحصل على الإضافة. نطاق المستخدم (User scope) يعني أنت، في كل مشروع. يكتب نطاق المشروع (Project scope) الإضافة في ملف .claude/settings.json الخاص بالمستودع تحت enabledPlugins، بحيث يُعرض تثبيتها على كل من يستنسخ (clone) المستودع. النطاق المحلي (Local scope) يعني أنت، في هذا المستودع فقط.

بالنسبة للسكربتات، أو ملفات Dockerfile، أو أي جلسة لا تتوفر فيها لوحة تحكم تفاعلية، استخدم صيغة سطر الأوامر (shell) بدلاً من ذلك. يتم التثبيت في نطاق المستخدم ما لم تمرر --scope.

claude plugin install commit-commands@claude-code-plugins --scope project
claude plugin list

تعمل claude plugin install خارج الجلسة، لذا لن ترى الجلسة المفتوحة حالياً الإضافة الجديدة إلا بعد تشغيل /reload-plugins أو بدء جلسة جديدة.

إدارة ما تملكه تتبع النمط نفسه في كلا المكانين. تطبع /plugin list ما هو مثبت، وتقبل المعاملات --enabled أو --disabled. تقوم /plugin disable name@marketplace بإيقاف الإضافة دون إزالتها، وتعيدها /plugin enable للعمل، بينما تقوم /plugin uninstall بإزالتها. تفتح صيغ أوامر الشرطة المائلة (slash-command) لوحة الإضافات لتطبيق التغيير، ولهذا السبب تُستخدم مكافئات سطر الأوامر claude plugin ... في السكربتات.

لتوفير سوق لفريق عمل كامل، ضعه في ملف .claude/settings.json الخاص بالمشروع. سيُطلب من الأعضاء تثبيته بمجرد أن يمنحوا الثقة لمجلد المستودع.

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": {
        "source": "github",
        "repo": "your-org/claude-plugins"
      }
    }
  }
}

أثناء بناء إضافتك الخاصة، تخطَّ السوق تماماً. تقوم claude --plugin-dir ./my-plugin بتحميل دليل (directory) لتلك الجلسة، وتلتقط /reload-plugins تعديلاتك دون الحاجة لإعادة التشغيل، وتتحقق claude plugin validate ./my-plugin من ملف البيان (manifest)، ومهارة وواجهة العميل (frontmatter)، وhooks/hooks.json قبل أن يراها أي شخص آخر.

ما تكلفة إضافة Claude Code؟

هذه الآلية مجانية. اعتباراً من أغسطس 2026، لا توجد رسوم لإضافة سوق، أو تثبيت إضافة، أو إبقاء إحداها مفعّلة. الأسواق الرسمية والمجتمعية هي مستودعات git عامة، والإضافة هي مجرد دليل يحتوي على ملفات نصية.

ما تكلّفه الإضافة هو الـ tokens، وهي الوحدة التي يقاس بها استهلاك اشتراكك أو فاتورة الـ API الخاصة بك. تأتي هذه التكلفة بثلاث طرق مختلفة، وتعمل كل منها بشكل متباين.

تكلفة السياق الدائم (Standing context cost). ما تضيفه الإضافة يظل في سياقك ويُعاد قراءته في كل دورة من الجلسة. قبل التثبيت، يعرض عرض التفاصيل /plugin تقديراً Context cost بالـ tokens، بالإضافة إلى قسم Will install يسرد الأوامر، والمهارات، والوكلاء، والخطافات (hooks)، وخوادم MCP وLSP التي توشك على إضافتها. اقرأ كلاهما. قد لا توفر الإضافات من الأسواق المحلية أو المخصصة هذه البيانات، وفي هذه الحالة سيتعين عليك التقدير يدوياً. الإضافة التي تحزم خادم MCP تكون عادةً هي الأثقل، لأن تعريفات الأدوات كبيرة الحجم، رغم أن النماذج التي تدعم البحث عن أدوات MCP تؤجل هذه التعريفات حتى الحاجة إلى الأداة.

تكلفة الاستدعاء (Invocation cost). يؤدي تشغيل مهارة الإضافة إلى إلحاق تعليماتها بالمحادثة، لذا فأنت تدفع مقابل نص المهارة فقط عند استخدامها. الوكيل (agent) يختلف عن ذلك؛ إذ يدير الوكيل الفرعي محادثته الخاصة مع مطالبة نظام (system prompt) خاصة به وذاكرة تخزين مؤقت (cache) خاصة به، ويبدأ دون أي نتائج من الذاكرة المؤقتة. لذا، فإن الإضافة التي يولد سير عملها وكلاء تكلف أكثر بكثير مما يوحي به تقدير السياق الخاص بها.

تكلفة الذاكرة المؤقتة (Cache cost). قد يؤدي تمكين أو تعطيل إضافة في منتصف الجلسة إلى إجبار الطلب التالي على إعادة معالجة محادثتك بالكامل. المهارات، والأوامر، والوكلاء، والخطافات، وخوادم LSP، والمراقبون، والسمات (themes) لا تفعل ذلك أبداً؛ فما تضيفه يُلحق بعد السجل الحالي، لذا يدفع الطلب التالي مقابل المحتوى الجديد بينما يقرأ كل ما قبله من الذاكرة المؤقتة. الاستثناء هو الإضافة التي توفر خادم MCP. إذا تم تأجيل أدواتها بواسطة البحث عن الأدوات، فإن الذاكرة المؤقتة تظل سليمة. أما إذا تم تحميلها في بادئة المطالبة (prompt prefix)، فإن الطلب التالي يعيد قراءة المحادثة بأكملها كمدخلات غير مخزنة مؤقتاً. هذا هو السبب الدقيق وراء تحذير /reload-plugins ورفضه في هذه الحالة حتى تمرر --force.

يمكنك مراقبة ذلك بدلاً من التخمين. يبلغ كل رد من الـ API عن cache_read_input_tokens وcache_creation_input_tokens، ويضع شريط حالة مخصص يعرض استخدام الـ tokens المباشر كلاهما أمامك. الجلسة السليمة تقرأ أكثر بكثير مما تنشئ. إذا ظل الإنشاء مرتفعاً دورة بعد دورة، فهذا يعني أن شيئاً ما في بادئتك يتغير في كل دورة. للحصول على صورة أوسع لما يملأ النافذة، راجع كيفية إدارة نافذة سياق Claude Code وما تعنيه أعداد الـ tokens تلك فعلياً.

هناك إجراء تنظيمي واحد يغطي تكلفته بنفسه. تجمع علامة التبويب Installed الإضافات التي لم تستخدمها منذ أسبوعين على الأقل تحت ترويسة Not used recently، مع وجود سطر Last used في عرض التفاصيل. لا تزال تلك الإضافات تكلفك وقتاً عند بدء التشغيل ومساحة في السياق في كل جلسة. قم بتعطيلها أو إلغاء تثبيتها.

تعمل الإضافة بصلاحياتك

تُصرح وثائق Anthropic بوضوح بأن الإضافات والمتاجر هي مكونات موثوقة للغاية، ويمكنها تنفيذ تعليمات برمجية عشوائية على جهازك باستخدام صلاحيات المستخدم الخاص بك. هذا ليس افتراضاً نظرياً. تعمل خطافات (hooks) الإضافة لتنفيذ أوامر shell عند وقوع أحداث الجلسة، بما في ذلك قبل وبعد استدعاء الأدوات. يُضاف دليلها bin/ إلى PATH الخاص بأداة Bash أثناء تفعيل الإضافة. كما أنّ خوادم MCP الخاصة بها هي عمليات تبدأها الإضافة نفسها. لا يوجد شيء هنا معزول عن حساب المستخدم الخاص بك.

على الحاسوب المحمول، يقتصر هذا الخطر على ما يمكن لمستخدم سطح المكتب الوصول إليه. أما على الخادم، فالأمر مختلف عادةً. غالباً ما يمتلك الحساب الذي يشغل الوكيل مفاتيح SSH، ورموز النشر (deploy tokens)، وجلسة CLI سحابية، وصلاحية الوصول إلى مقبس Docker، لذا فإن "تنفيذ تعليمات برمجية عشوائية بصلاحياتك" يعني السيطرة على الجهاز بالكامل. إذا كنت تشغل Claude Code على خادم افتراضي خاص (VPS)، اقرأ كيفية تشغيل Claude Code بأمان على VPS قبل تثبيت أي شيء، واقرأ كيفية إبقاء بيانات الاعتماد بعيداً عن متناول الوكيل قبل تثبيت إضافة تتصل بخدمة خارجية.

توجد بعض حواجز الحماية، ومن المفيد معرفتها. تأتي الإضافة ذات النطاق الخاص بالمشروع (project-scope) من المستودع وليس منك، لذا فهي لا تُحمّل إلا بعد أن تثق في مساحة العمل، ولا تزال خوادم MCP الخاصة بها تتطلب موافقة لكل خادم، وتنتظر خوادم LSP الخاصة بها هذا الاعتماد، بينما لا تُحمّل مراقبات الخلفية الخاصة بها على الإطلاق. لا يُسمح للوكلاء المرفقين مع الإضافات بالإعلان عن خطافات أو خوادم MCP أو وضع صلاحيات. تُنسخ إضافات المتجر إلى ذاكرة التخزين المؤقت مع تخطي الروابط الرمزية (symlinks) التي تشير إلى خارج المتجر، لذا لا يمكن للإضافة سحب ملفات عشوائية من المضيف.

لا شيء من ذلك يغني عن قراءة ما تقوم بتثبيته. راجع قائمة Will install، وفضّل الإضافات التي يمكنك فتح وقراءة مصدرها البرمجي، واحتفظ بإضافات فريقك في مستودع متجر تتحكم فيه، وقم بتشغيل claude plugin validate على أي شيء تكتبه بنفسك.

FAQ

هل تكلّف إضافات Claude Code مالاً إضافياً؟

لا. لا توجد رسوم لنظام الإضافات، أو لإضافة متجر، أو لتثبيت أي إضافة. التكلفة هي استهلاك الرموز (tokens)، وتُحاسب ضمن خطتك أو إنفاقك على واجهة برمجة التطبيقات (API) تماماً مثل أي سياق آخر. تضيف الإضافة سياقاً دائماً في كل دورة، وتضيف المزيد عند استدعاء إحدى مهاراتها أو وكلائها، وقد تفرض دورة واحدة مكلفة غير مخزنة مؤقتاً إذا كانت توفر خادم MCP يتم تحميل أدواته في بادئة المطالبة (prompt prefix). يعرض عرض التفاصيل /plugin تقديراً Context cost قبل التثبيت.

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

المهارة هي وحدة تعليمات واحدة. الإضافة هي حزمة يمكن أن تحتوي على مهارات، ووكلاء، وخطافات (hooks)، وخوادم MCP، وخوادم LSP، ومراقبين، مع اسم وإصدار ومتجر للتثبيت منه. اكتب مهارة مستقلة في .claude/ عندما تكون مخصصة لك ولهذا المشروع. المهارة ذات الغرض الواحد مثل Ponytail، التي تدفع الوكيل نحو أصغر تغيير يعمل هي أوضح مثال على ذلك: ملف واحد يحتوي على قاعدة واحدة، حتى اليوم الذي يحتاجها فيه فريقك أيضاً. حوّلها إلى إضافة عندما يحتاجها أشخاص آخرون وتتطلب تحديثاً بمرور الوقت. مهارات الإضافات تتبع مساحة اسم (namespaced)، لذا يتم استدعاء المهارة داخل الإضافة كـ /plugin-name:skill-name بدلاً من /skill-name.

تم تثبيت الإضافة ولكن مهاراتها لا تظهر. ما الخطأ؟

تحقق من ملخص التثبيت أولاً. إذا كان يشير إلى Run /reload-plugins to activate.، فهذا يعني أن المكونات لم تُحمّل بعد، وإذا حذّر إعادة التحميل من أنه سيعيد قراءة المحادثة، فأعد تشغيله كـ /reload-plugins --force. إذا تم التحميل ولكن لا يظهر شيء، افتح /plugin واقرأ علامة التبويب Errors. الخطأ الهيكلي الأكثر شيوعاً هو وضع skills/ أو agents/ أو hooks/ داخل .claude-plugin/، حيث لا يبحث Claude Code عنها هناك. تذكر أن مهارات الإضافات تتبع مساحة اسم، لذا فأنت تبحث عن /plugin-name:skill-name في علامة التبويب Custom commands من /help. كحل أخير، استخدم rm -rf ~/.claude/plugins/cache، ثم أعد التشغيل، وأعد التثبيت.

هل يمكنني تثبيت الإضافات بدون اللوحة التفاعلية؟

نعم. استخدم أمر الصدفة (shell) claude plugin install name@marketplace، الذي يثبّت في نطاق المستخدم ما لم تمرر --scope project أو --scope local. يعمل هذا في النصوص البرمجية (scripts)، والصور، والبيئات غير التفاعلية حيث لا تتوفر لوحة /plugin. نظراً لأنه يعمل خارج الجلسة، فإن الجلسة المفتوحة بالفعل تحتاج إلى /reload-plugins قبل أن تصبح الإضافة سارية المفعول.

هل من الآمن تثبيت إضافة من متجر وجدته على GitHub؟

تعامل مع الأمر كما تتعامل مع تشغيل نص تثبيت ذلك المستودع بصلاحياتك، لأن هذا هو ما يحدث تقريباً. يمكن للإضافة تشغيل أوامر الصدفة عبر الخطافات، وإضافة ملفات تنفيذية إلى PATH الخاص بأداة Bash، وبدء خوادم MCP، وكل ذلك بصلاحيات المستخدم الخاص بك. لا تتحكم Anthropic في محتويات إضافات الطرف الثالث ولا تتحقق منها. ثبّت من مصادر يمكنك قراءتها، وراجع قائمة Will install قبل التأكيد، وكن أكثر صرامة على الخادم مقارنة بجهاز الكمبيوتر المحمول، حيث أن الحساب هناك عادةً ما يحتوي على مفاتيح ورموز تستحق السرقة.