دليل إضافات Claude Code

إضافات Claude Code — إنشاء إضافات Claude Code يوسّع المساعد بوظائف مخصصة. ابنِ إضافات تتضمن خطافات (hooks) وأوامر وخوادم MCP ووكلاء فرعيين (subagents).

إضافات Claude Code: ماذا ستتعلّم

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

الإضافات هي آلية التوسيع الأعلى مستوى في Claude Code. فهي تجمع المهارات (skills) والوكلاء الفرعيين (subagents) والخطافات (hooks) وخوادم MCP وإعدادات LSP في حزمة واحدة قابلة للتثبيت. يثبّت الفريق إضافة واحدة فيحصل فورًا على كل شيء مهيّأً — دون إعداد يدوي لكل مكوّن. يغطي هذا الدرس بنية الإضافة، وصيغة البيان (manifest)، وآليات التوزيع، وكيفية بناء إضافتك الخاصة.

بنية الإضافة

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

my-plugin/
├── .claude-plugin/
│   └── plugin.json       # Required manifest
├── skills/               # SKILL.md files
│   └── my-skill/
│       └── SKILL.md
├── agents/               # Subagent definitions
│   └── specialist.md
├── commands/             # Legacy command files (also work)
│   └── my-command.md
├── hooks/
│   └── hooks.json        # Plugin-scoped hooks
├── .mcp.json             # MCP server configs
├── .lsp.json             # LSP server configs
├── settings.json         # Default settings
└── bin/
    └── helper.sh

يحدّد البيان الإضافة وبياناتها الوصفية:

{
  "name": "pr-review",
  "description": "Complete PR review workflow with security and test coverage checks",
  "version": "1.0.0",
  "author": {
    "name": "Your Name"
  },
  "repository": "https://github.com/you/pr-review",
  "license": "MIT"
}

تُخصَّص أوامر الإضافة والمهارات التي توفّرها بفضاء أسماء على شكل plugin-name:command-name لتجنب التعارض مع إعدادات مستوى المشروع. استدعِها بالصيغة الكاملة المُخصَّصة بفضاء الأسماء، مثل /pr-review:check-security.

ميزات البيان

يدعم البيان عدة حقول قوية لضبط سلوك الإضافة. يعلن الحقل userConfig عن خيارات قابلة للتهيئة من قبل المستخدم. أما الحقول الموسومة بـ sensitive: true فتُخزَّن في سلسلة مفاتيح النظام (keychain) بدلاً من ملفات الإعدادات النصية الصريحة:

{
  "name": "my-plugin",
  "version": "1.0.0",
  "userConfig": {
    "apiKey": {
      "description": "API key for the integration",
      "sensitive": true
    },
    "region": {
      "description": "Deployment region",
      "default": "us-east-1"
    }
  }
}

تحصل الإضافات على مجلد بيانات دائم عبر ${CLAUDE_PLUGIN_DATA} (الإصدار v2.1.78 فأحدث). يبقى هذا المجلد عبر الجلسات، مما يجعله مناسبًا للذواكر المؤقتة (caches) وملفات الحالة وقواعد البيانات. استخدم ${CLAUDE_PLUGIN_ROOT} للإشارة إلى المسارات النسبية لمجلد تثبيت الإضافة — وهو أمر ضروري للخطافات وإعدادات MCP:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ${CLAUDE_PLUGIN_ROOT}/bin/audit.js"
          }
        ]
      }
    ]
  }
}

تتطلّب مراقبات الإضافات (monitors) الإصدار v2.1.105 من Claude Code أو أحدث. أعلِنها تحت المفتاح experimental في بيانك (experimental.monitors) — لا تزال الصيغة على المستوى الأعلى تعمل لكن claude plugin validate سيُصدر تحذيرًا، وسيتطلب إصدار مستقبلي الصيغة المتداخلة. يربط مفتاح البيان monitors الإضافة بأداة Monitor. وجّهه إلى ملف JSON (أو ضمّن الإعداد مباشرة) فتُسلَّح مراقباته في الخلفية تلقائيًا في اللحظة التي تُفعَّل فيها الإضافة عند بدء الجلسة، أو عند استدعاء إحدى مهارات الإضافة. وهكذا تُقدِّم الإضافة سلوكًا مثل «راقب التكامل المستمر (CI) وأبلِغ عن الإخفاقات» أو «تتبّع سجل خادم التطوير» دون أن يضطر المستخدم إلى إعداده:

{
  "name": "ci-watcher",
  "version": "1.0.0",
  "experimental": {
    "monitors": "./monitors.json"
  }
}

عندما يحدّد البيان مسار monitors مخصصًا، لن يُفحَص الموقع الافتراضي monitors/monitors.json بعد ذلك — فحدّد الافتراضي صراحةً إن كنت لا تزال تريد تحميله جنبًا إلى جنب مع ملفك المخصص.

يضيف دعم LSP تكاملًا لحظيًا مع بروتوكول خادم اللغة. ضع ملف .lsp.json في جذر الإضافة لتهيئة خوادم اللغة التي توفّر تشخيصات فورية، والانتقال إلى التعريف، والبحث عن الرموز أثناء تحرير Claude للملفات:

{
  "typescript": {
    "command": "typescript-language-server",
    "args": ["--stdio"],
    "extensionToLanguage": {
      ".ts": "typescript",
      ".tsx": "typescriptreact"
    }
  }
}

التوزيع والتطوير

اختبر الإضافة محليًا باستخدام الراية --plugin-dir قبل توزيعها. فهي تحمّل الإضافة لتلك الجلسة فقط — دون أي تثبيت:

claude --plugin-dir ./my-plugin
# Test multiple plugins simultaneously:
claude --plugin-dir ./my-plugin --plugin-dir ./another-plugin

بالنسبة للإضافات المستضافة كأرشيفات .zip، تجلب الراية --plugin-url هذه الإضافات وتثبّتها للجلسة الحالية دون تثبيت دائم. كرّر الراية لإضافات متعددة:

claude --plugin-url https://example.com/my-plugin.zip
claude --plugin-url https://example.com/a.zip --plugin-url https://example.com/b.zip

استخدم --plugin-url فقط مع روابط تثق بها — فتحميل الأرشيفات البعيدة يُنفّذ شيفرة طرف ثالث على جهازك.

استخدم /reload-plugins لإعادة تحميل ملفات الإضافة فوريًا أثناء التطوير دون إعادة تشغيل الجلسة. فهو يعيد قراءة جميع البيانات والمهارات والوكلاء والخطافات وإعدادات MCP فورًا.

تعرض الآن شاشتا Discover وBrowse في /plugin جردًا كاملاً لما ستثبّته الإضافة قبل أن تلتزم بها — الأوامر والوكلاء والمهارات والخطافات وأي خوادم MCP أو LSP تشحنها. يجعل هذا تدقيق إضافة من السوق قرارًا في شاشة واحدة: يمكنك التأكد من أن إضافة pr-review لا تسجّل بهدوء خوادم MCP أو خطافات لم تتوقعها، أو التحقق من أن إضافة نشر تشحن فعلاً المهارة التي جئت من أجلها. تسرد Browse ما هو مثبّت بالفعل بالتفصيل نفسه؛ وتفعل Discover الأمر ذاته لكتالوج السوق. المعاينة للاطّلاع فقط — فلا يزال يتعيّن تثبيت الإضافة قبل أن يعمل أي من مكوناتها.

يتبع توزيع الإضافات نموذج السوق. السوق الرسمي من Anthropic هو claude-code-plugins-official. أضِف أسواقًا إضافية بـ /plugin marketplace add owner/repo-name. ثبّت الإضافات بـ /plugin install plugin-name أو claude plugin install plugin-name@marketplace:

# Install from official marketplace
/plugin install pr-review

# Install from GitHub
/plugin install github:username/my-plugin

# Install from local path (for testing)
/plugin install ./path/to/plugin

عندما يكون مصدر الإضافة اختصار GitHub بصيغة owner/repo، يلجأ Claude Code افتراضيًا إلى الاستنساخ عبر SSH. وهذا يفشل في مشغّلات CI أو الحاويات أو أي بيئة بلا مفتاح SSH مهيّأ لـ github.com. اضبط CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 لفرض الاستنساخ عبر HTTPS بدلاً من ذلك — ويبقى بقية تدفق التثبيت كما هو دون تغيير:

# Force HTTPS for plugin clones in CI
CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1 claude plugin install owner/repo

في بيئات المؤسسات، يتحكم managed-mcp.json في خوادم MCP التي يمكن للإضافات استخدامها. تتحكم إعدادات enabledPlugins وextraKnownMarketplaces وstrictKnownMarketplaces وblockedMarketplaces في السياسة المُدارة بتحديد الإضافات والأسواق المسموح بها على مستوى المؤسسة بأكملها. للوكلاء الفرعيين في الإضافات بيانات أمامية (frontmatter) مقيّدة — فلا يمكنهم تعريف hooks أو mcpServers أو permissionMode منعًا لتصعيد الامتيازات.

تشمل أوامر دورة الحياة المفيدة claude plugin list وclaude plugin enable وclaude plugin disable وclaude plugin uninstall وclaude plugin validate وclaude plugin prune (جديد في v2.1.121، باسم بديل autoremove) الذي يزيل تبعيات الإضافات المثبّتة تلقائيًا التي لم تعد أي إضافة مثبّتة أخرى بحاجة إليها — أما الإضافات التي ثبّتها مباشرةً فلا تُمَس أبدًا؛ ولإلغاء تثبيت إضافة وتنظيف تبعياتها في خطوة واحدة، شغّل claude plugin uninstall <plugin> --prune. يعرض claude plugin details <name> جرد مكونات الإضافة مجمّعةً كمهارات ووكلاء وخطافات وخوادم MCP وخوادم LSP، مع تقدير لعدد الرموز (tokens) التي تضيفها إلى كل جلسة.

ويُنشئ claude plugin tag (جديد في v2.1.118) وسم إصدار في git مع التحقق من النسخة. يمكن للأسواق أن تستمد الإضافات من GitHub أو روابط git أو المسارات المحلية أو npm أو غيرها من مصادر الحزم المدعومة.

يبدّل claude plugin enable وclaude plugin disable تشغيل إضافة مثبّتة أو إيقافها دون إزالتها. كلاهما يقبل اسم <plugin> (أو <plugin>@<marketplace> لإزالة الالتباس) ونطاق --scope من نوع user أو project أو local (الافتراضي: user). يكتب التعطيل على نطاق project الخيار في .claude/settings.json ليلتقطه الفريق بأكمله؛ بينما يُبقي نطاق user الخيار شخصيًا:

# Personal: turn off a noisy plugin just for you
claude plugin disable formatter@anthropics/claude-code-plugins

# Team: keep the plugin in settings but turn it off project-wide
claude plugin disable formatter --scope project

# Re-enable later without touching its install or version
claude plugin enable formatter --scope project

يتيح لك نمط الإضافة المضمّنة (source: 'settings' في v2.1.80 فأحدث) تضمين تعريف إضافة مباشرة في ملف إعدادات دون مستودع منفصل. وهذا مفيد للأدوات الداخلية الصغيرة الخاصة بالفريق التي لا تستدعي إنشاء مستودع git كامل:

{
  "pluginMarketplaces": [
    {
      "name": "internal-tools",
      "source": "settings",
      "plugins": [
        {
          "name": "code-standards",
          "source": "./local-plugins/code-standards"
        }
      ]
    }
  ]
}

أمثلة عملية على الإضافات

إليك أمثلة على إضافات جاهزة للإنتاج يمكنك استخدامها كقوالب:

المثال 1: بيان الإضافة

ملف .claude-plugin/plugin.json هو البيان الأساسي الذي تتطلبه كل إضافة:

{
  "name": "devops-automation",
  "version": "1.0.0",
  "description": "Complete DevOps automation for deployment, monitoring, and incident response",
  "author": { "name": "Community" },
  "license": "MIT"
}

المثال 2: خطاف الإضافة (التحقق قبل النشر)

تعيش الخطافات في hooks/hooks.json داخل مجلد الإضافة. إليك خطافًا قبل النشر مكتوبًا بـ Node.js:

#!/usr/bin/env node
// Pre-deployment hook - validates environment before deployment
async function preDeploy() {
  console.log('Running pre-deployment checks...');
  const { execSync } = require('child_process');

  try {
    execSync('which kubectl', { stdio: 'pipe' });
  } catch (error) {
    console.error('kubectl not found. Please install Kubernetes CLI.');
    process.exit(1);
  }

  try {
    execSync('kubectl cluster-info', { stdio: 'pipe' });
  } catch (error) {
    console.error('Not connected to Kubernetes cluster');
    process.exit(1);
  }

  console.log('Pre-deployment checks passed');
}

preDeploy().catch(error => {
  console.error('Pre-deploy hook failed:', error);
  process.exit(1);
});

المثال 3: أمر الإضافة وبنية المجلدات

تعيش الأوامر في commands/ وتُستدعى بصيغة فضاء الأسماء (/devops-automation:deploy):

---
name: Deploy
description: Deploy application to production or staging
---

# Deploy Application

Execute deployment workflow:
1. Run pre-deployment checks
2. Build application
3. Run tests
4. Deploy to target environment
5. Run health checks
6. Notify team on Slack

بنية مجلد الإضافة الكاملة:

devops-automation/
  .claude-plugin/
    plugin.json          # Required manifest
  commands/
    deploy.md            # /devops-automation:deploy
    rollback.md          # /devops-automation:rollback
    status.md            # /devops-automation:status
    incident.md          # /devops-automation:incident
  hooks/
    hooks.json           # Hook configurations
  agents/
    deployment-specialist.md
    incident-commander.md
    alert-analyzer.md
  scripts/
    deploy.sh
    rollback.sh
    health-check.sh
  mcp/
    kubernetes-config.json

نصائح احترافية

• استخدم الإضافات للتجميع، لا للميزة الواحدة. إن كنت تحتاج فقط إلى أمر شرطة مائلة واحد أو وكيل فرعي واحد، فأعدّه قائمًا بذاته. اِلجأ إلى إضافة حين ترغب في تجميع عدة مكونات، أو المشاركة مع فريق، أو التوزيع علنًا.
• اختبر محليًا قبل النشر. استخدم claude --plugin-dir ./my-plugin لتحميل إضافة من مسار محلي والتحقق من عمل كل مكوّن—الأوامر والوكلاء الفرعيون والخطافات وخوادم MCP—قبل تقديمها إلى سوق.
• أعِد التحميل الفوري أثناء التطوير. بعد تحرير ملفات الإضافة، شغّل /reload-plugins بدلاً من إعادة تشغيل Claude Code. فهو يعيد قراءة جميع البيانات والإعدادات فورًا.
• احترم قيود أمان الوكلاء الفرعيين في الإضافات. لا يمكن للوكلاء الفرعيين في الإضافات تعريف hooks أو mcpServers أو permissionMode. يمنع هذا تصعيد الامتيازات—فصمّم وكلاءك ضمن هذه القيود.
• أصدِر إضافاتك بإصدارات دلالية (semver) وأنشئ وسومًا للإصدارات. استخدم claude plugin tag v1.0.0 لإنشاء وسوم إصدار مُتحقَّق منها. يضمن هذا عمليات تثبيت قابلة للتكرار ويتيح للمستخدمين تثبيت نسخ محددة لأجل الاستقرار.

تحدٍّ تطبيقي

اِبنِ واختبر وثبّت محليًا إضافة بسيطة تجمع أمر شرطة مائلة ووكيلًا فرعيًا.

المهمة

أنشئ إضافة “lint-fixer” بأمر شرطة مائلة واحد (/lint-fix) ووكيل فرعي واحد للقراءة فقط (lint-reviewer)، ثم حمّلها بـ --plugin-dir وتحقّق من توفّر كلا المكوّنين.

الخطوات

1. أنشئ بنية المجلدات: lint-fixer/.claude-plugin/plugin.json وlint-fixer/commands/lint-fix.md وlint-fixer/agents/lint-reviewer.md.
2. اكتب plugin.json بحقول name وversion وdescription وauthor.
3. اكتب lint-fix.md كأمر شرطة مائلة يشغّل أداة الفحص (linter) في المشروع ويصلح المشكلات تلقائيًا (استخدم بيانات أمامية بصيغة YAML تتضمن name وdescription).
4. اكتب lint-reviewer.md كوكيل فرعي بـ tools: Read, Grep وموجّه (prompt) يركّز على نمط الشيفرة ومخالفات قواعد الفحص.
5. شغّل Claude Code بـ claude --plugin-dir ./lint-fixer.
6. تحقّق بكتابة /lint-fix وبطلب “استخدم الوكيل الفرعي lint-reviewer لفحص هذا الملف.”

النتيجة المتوقعة

مجلد إضافة صالح يُحمَّل دون أخطاء، وأمر شرطة مائلة /lint-fix يعمل، ووكيل فرعي lint-reviewer ظاهر في /agents—وكلها قابلة للاختبار محليًا قبل النشر.

تلميح

يعمل الوكلاء الفرعيون في الإضافات داخل بيئة معزولة مقيّدة—فمفاتيح البيانات الأمامية hooks وmcpServers وpermissionMode غير مسموح بها لأسباب أمنية. اختبر محليًا بـ --plugin-dir قبل النشر. وبعد تحرير الملفات، استخدم /reload-plugins لإعادة التحميل الفوري دون إعادة تشغيل الجلسة.

اختبار المعرفة

اختبر فهمك لإضافات Claude Code:

س1: ما ملف البيان الأساسي للإضافة وأين يقع؟

أ) plugin.yaml في المجلد الجذر
ب) .claude-plugin/plugin.json
ج) package.json بمفتاح «claude»
د) .claude/plugin.md

الإجابة الصحيحة: ب — يقع بيان الإضافة في .claude-plugin/plugin.json بالحقول المطلوبة: name وdescription وversion وauthor.

س2: كيف تختبر إضافة محليًا قبل النشر؟

أ) استخدم /plugin test ./my-plugin
ب) استخدم claude --plugin-dir ./my-plugin
ج) استخدم claude plugin validate ./my-plugin
د) انسخها إلى ~/.claude/plugins/

الإجابة الصحيحة: ب — تحمّل الراية --plugin-dir إضافة من مجلد محلي لأجل الاختبار.

س3: أي متغير بيئة يشير إلى مجلد تثبيت الإضافة؟

أ) $PLUGIN_HOME
ب) ${CLAUDE_PLUGIN_ROOT}
ج) $PLUGIN_DIR
د) ${CLAUDE_PLUGIN_PATH}

الإجابة الصحيحة: ب — يُحَلّ ${CLAUDE_PLUGIN_ROOT} إلى مجلد تثبيت الإضافة لأجل إشارات مسار قابلة للنقل.

س4: إضافة فيها أمر باسم «check-security» ضمن إضافة «pr-review». كيف يستدعيه المستخدم؟

أ) /check-security
ب) /pr-review:check-security
ج) /plugin pr-review check-security
د) /pr-review/check-security

الإجابة الصحيحة: ب — تستخدم أوامر الإضافات فضاء أسماء بصيغة plugin-name:command-name.

س5: أي مكونات يمكن للإضافة أن تجمعها؟

أ) الأوامر والإعدادات فقط
ب) الأوامر والوكلاء والمهارات والخطافات وخوادم MCP وإعداد LSP والإعدادات والقوالب والسكربتات
ج) الأوامر والخطافات وخوادم MCP فقط
د) المهارات والوكلاء فقط

الإجابة الصحيحة: ب — يمكن للإضافات تجميع commands/ وagents/ وskills/ وhooks/ و.mcp.json و.lsp.json وsettings.json وtemplates/ وscripts/.

مصادر إضافية

ماذا ينبغي أن تجمع الإضافة؟

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

كيف أبقي الإضافة جديرة بالثقة؟

حدِّد صلاحياتها بالحد الأدنى الذي تحتاجه الميزة ووثّق كل ما تمسّه.

كيف أتعامل مع تحديثات الإضافة؟

أصدِرها كأي تبعية، ودوّن التغييرات الكاسرة (breaking changes)، واختبر كل إصدار في مشروع للاستهلاك المؤقت أولاً.

جمع كل الخيوط معًا

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

دليل إضافات Claude Code: الأسئلة الشائعة

ما الفرق بين الإضافة (plugin) والمهارة (skill) الفردية في Claude Code؟

المهارة وحدة واحدة ضيقة الغرض، بينما الإضافة حاوية أوسع يمكن أن تجمع عدة مهارات وأوامر وخطافات وخوادم MCP معًا خلف بيان واحد، وهو ما يجعلها الخيار الأنسب حين ترتبط عدة قدرات ببعضها منطقيًا.

أين تُنشر الإضافات المعدّة للاستخدام العام؟

عادة عبر مستودع Git عام أو سجل حزم مخصص يشير إليه بيان الإضافة، بحيث يمكن لأي مستخدم إضافته كمصدر خارجي بدلًا من نسخ الملفات يدويًا.

كيف تُدار الأذونات الحساسة داخل إضافة تصل إلى أنظمة خارجية؟

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

ماذا يحدث للمستخدمين الحاليين حين تُصدر نسخة جديدة تكسر التوافق مع النسخة السابقة؟

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

هل يمكن لإضافة واحدة أن تعتمد على إضافة أخرى؟

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

إضافات Claude Code تمنحك سير عمل متينًا قابلًا للتكرار. احفظ هذا الدليل عن إضافات Claude Code ضمن مرجعياتك وعُد إلى خطواته كلما احتجت إليها.

تشريح إضافة مُحكَمة البناء

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

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

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

إضافات Claude Code: أخطاء شائعة يجب تجنّبها

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

• وضع hooks أو mcpServers أو permissionMode في بيانات الوكلاء الفرعيين للإضافة — وهذا محظور صراحةً لمنع تصعيد الامتيازات.
• نشر إضافة في سوق دون اختبارها محليًا أولًا عبر --plugin-dir، فتصل الأخطاء إلى المستخدمين مباشرة.
• نسيان فضاء الأسماء عند استدعاء أمر الإضافة (كتابة /check-security بدل /pr-review:check-security).
• الاعتماد على الاستنساخ عبر SSH في بيئات CI بلا مفتاح مهيأ بدل ضبط CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1.

إضافات Claude Code: أفضل الممارسات

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