إضافات Claude Code: أنشئ واختبر وانشر متجر الإضافات الخاص بك

أصبح Claude Code بهدوء الوكيل البرمجي القياسي بالذكاء الاصطناعي في العديد من فرق الهندسة، وفي عام 2026 لم تعد الفرق الأكثر فعالية تضبط إعداداته لكل مطوّر على حدة. بل تحزم أوامرها المائلة ووكلاءها الفرعيين ومهاراتها وخطافاتها وخوادم MCP الخاصة بها في إضافات (Plugins)، وتنشرها في متجر إضافات (Marketplace) مستضاف في مستودع Git عادي، ثم تفعّلها للجميع بإدخال واحد في ملف الإعدادات.

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

المتطلبات المسبقة

قبل البدء، تأكد من توفر ما يلي:

• تثبيت Claude Code وتسجيل الدخول فيه (نفّذ claude --version للتحقق؛ أي إصدار 2.x يدعم الإضافات)
• تثبيت Node.js 20 أو أحدث
• حساب GitHub (أو أي مستضيف Git يمكن لفريقك الاستنساخ منه)
• إلمام أساسي بمفاهيم Claude Code مثل الأوامر المائلة وملف CLAUDE.md

لا تحتاج إلى أي خبرة سابقة في بناء الإضافات.

ما الذي ستبنيه

ستنشئ إضافة باسم team-toolkit تجمع خمس قدرات:

1. أمر مائل /team-toolkit:changelog يصيغ مسودة سجل تغييرات من آخر الإيداعات
2. وكيل فرعي code-auditor يراجع الشيفرة وفق اصطلاحات فريقك
3. مهارة conventional-commits يحمّلها Claude تلقائيًا عند كتابة رسائل الإيداع
4. خطاف (Hook) يشغّل أداة التنسيق بعد كل تعديل ملف
5. إعداد خادم MCP مدمج للوصول إلى مجلد توثيق مشترك

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

الخطوة 1: فهم بنية الإضافة

إضافة Claude Code هي مجرد مجلد يحتوي على ملف تعريف (Manifest). كل مكوّن اختياري — يمكن للإضافة أن تشحن خطافًا فقط، أو أوامر فقط، أو كل شيء معًا. البنية الكاملة تبدو هكذا:

team-toolkit/
├── .claude-plugin/
│   └── plugin.json        # ملف التعريف (إلزامي)
├── commands/              # الأوامر المائلة (ملفات Markdown)
│   └── changelog.md
├── agents/                # الوكلاء الفرعيون (ملفات Markdown)
│   └── code-auditor.md
├── skills/                # المهارات (مجلدات تحتوي SKILL.md)
│   └── conventional-commits/
│       └── SKILL.md
├── hooks/
│   └── hooks.json         # معالجات الأحداث
├── scripts/               # سكربتات مساعدة تستخدمها الخطافات
│   └── format.sh
└── .mcp.json              # خوادم MCP المدمجة

قاعدتان أهم من كل شيء آخر:

• ملف التعريف يوضع في .claude-plugin/plugin.json — داخل المجلد المخفي، وليس في جذر المستودع.
• مجلدات المكونات (commands/ وagents/ وskills/ وhooks/) توضع في جذر الإضافة، وليس داخل .claude-plugin/.

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

الخطوة 2: إنشاء هيكل الإضافة وملف التعريف

أنشئ بنية المجلدات وملف التعريف:

mkdir -p team-toolkit/.claude-plugin
mkdir -p team-toolkit/commands team-toolkit/agents
mkdir -p team-toolkit/skills/conventional-commits
mkdir -p team-toolkit/hooks team-toolkit/scripts
cd team-toolkit

الآن أنشئ .claude-plugin/plugin.json:

{
  "name": "team-toolkit",
  "description": "Noqta engineering conventions: changelog command, code auditor, commit skill, format-on-edit hook",
  "version": "1.0.0",
  "author": {
    "name": "Noqta Engineering",
    "email": "dev@noqta.tn"
  },
  "keywords": ["conventions", "review", "changelog"]
}

الحقل name هو الإلزامي الوحيد نظريًا، لكن description وversion يظهران في واجهة مدير الإضافات، لذا عاملهما كإلزاميين عمليًا. يجب أن يكون name بصيغة kebab-case دون مسافات — لأنه يصبح بادئة النطاق لكل أمر تشحنه الإضافة.

الخطوة 3: إضافة أمر مائل

الأوامر المائلة في الإضافات هي ملفات Markdown داخل commands/. اسم الملف يصبح اسم الأمر مسبوقًا باسم الإضافة: commands/changelog.md يصبح /team-toolkit:changelog. هذا التسمية النطاقية تضمن ألا تتعارض أوامر إضافتك مع أوامر إضافة أخرى.

أنشئ commands/changelog.md:

---
description: Draft a changelog entry from recent commits
argument-hint: [version] [since-tag]
allowed-tools: Bash(git log:*), Bash(git diff:*), Read
---
 
Draft a changelog entry for version $1.
 
1. Run `git log --oneline $2..HEAD` to list commits since tag $2.
   If no tag argument was given, use the most recent tag.
2. Group the commits into Added, Changed, Fixed, and Removed sections
   following the Keep a Changelog format.
3. Rewrite each line as a user-facing sentence — drop internal refactor
   noise unless it affects behavior.
4. Output the entry as Markdown ready to paste into CHANGELOG.md.
   Do not modify any files.

ثلاث تفاصيل تستحق الانتباه:

• argument-hint هو ما يراه المستخدمون عند الإكمال التلقائي للأمر.
• $1 و$2 يستقبلان الوسائط الموضعية؛ بينما $ARGUMENTS يستقبل سلسلة الوسائط كاملة.
• allowed-tools يمنح موافقة مسبقة لأنماط أدوات محددة كي يعمل الأمر دون مطالبات إذن — اجعله محدودًا قدر الإمكان.

الخطوة 4: إضافة وكيل فرعي

الوكلاء الفرعيون هم مساعدون متخصصون لهم موجّه نظام خاص وقيود أدوات ونافذة سياق مستقلة. يفوّض Claude المهام إليهم تلقائيًا عندما تطابق المهمة وصفهم، أو يمكنك استدعاؤهم صراحة.

أنشئ agents/code-auditor.md:

---
name: code-auditor
description: Reviews code changes against Noqta engineering conventions. Use proactively after significant edits or before committing.
tools: Read, Grep, Glob, Bash
model: inherit
---
 
You are a strict but pragmatic code auditor for a TypeScript/Next.js team.
 
When invoked:
1. Run `git diff HEAD` to see pending changes.
2. Check every changed file against these conventions:
   - No console.log in production code (a logger must be used)
   - No empty catch blocks
   - Files stay under 300 lines
   - Repeated logic is extracted into shared utilities
3. Report findings ordered by severity. For each finding include
   the file path, line number, and a concrete suggested fix.
4. If everything passes, say so explicitly and list what you checked.
 
Never modify files yourself. You are read-only by convention.

حقل description هو ما يقرؤه Claude عند اتخاذ قرار التفويض — عبارات مثل "use proactively" تؤثر فعليًا في سلوك التفويض. تعيين model: inherit يُبقي الوكيل الفرعي على نفس نموذج المحادثة الرئيسية؛ ويمكنك أيضًا تثبيت نموذج محدد مثل haiku للفحوصات الميكانيكية منخفضة التكلفة.

الخطوة 5: إضافة مهارة

تختلف المهارات عن الأوامر في نقطة جوهرية واحدة: الأوامر يستدعيها المستخدم، أما المهارات فيحمّلها Claude نفسه عندما تطابق المهمة وصفها. المهارة هي مجلد يحتوي ملف SKILL.md بترويسة تخبر Claude متى يحمّلها.

أنشئ skills/conventional-commits/SKILL.md:

---
name: conventional-commits
description: Format git commit messages using the team's conventional commit standard. Use whenever writing, amending, or reviewing a commit message.
---
 
# Conventional Commits — Team Standard
 
## Format
 
    type(scope): subject
 
    body (optional)
 
    footer (optional)
 
## Types
 
feat, fix, docs, style, refactor, test, chore
 
## Rules
 
1. Subject in imperative mood, lowercase, no trailing period
2. Scope is the affected module: auth, api, ui, content, build
3. One logical change per commit — never batch unrelated edits
4. Reference issues in the footer: "Refs #123" or "Closes #123"
5. Body explains the why for any non-obvious change
 
## Examples
 
    feat(auth): add password reset flow
 
    fix(api): handle null values in user profile endpoint
 
    The endpoint returned 500 when optional fields were null.
    Added null checks with sensible defaults.
 
    Closes #456

ولأن المهارة تُشحن ضمن الإضافة، فإن كل مطوّر يثبّت team-toolkit يحصل على اصطلاحات إيداع متطابقة تُطبق تلقائيًا — لا مزيد من نسخ الإرشادات ولصقها في ملف CLAUDE.md لكل مشروع.

الخطوة 6: إضافة خطاف

الخطافات تشغّل أوامر Shell عند أحداث دورة الحياة — أتمتة حتمية لا تعتمد على قرار النموذج بفعل شيء ما. سنقوم بتنسيق الملفات بعد كل تعديل.

أنشئ hooks/hooks.json:

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

والسكربت في scripts/format.sh:

#!/usr/bin/env bash
# Reads the hook payload from stdin, formats the edited file if supported.
set -euo pipefail
 
payload=$(cat)
file_path=$(echo "$payload" | jq -r '.tool_input.file_path // empty')
 
if [[ -z "$file_path" ]]; then
  exit 0
fi
 
case "$file_path" in
  *.ts|*.tsx|*.js|*.jsx|*.json|*.css|*.md)
    if command -v prettier >/dev/null 2>&1; then
      prettier --write "$file_path" >/dev/null 2>&1 || true
    fi
    ;;
esac
 
exit 0

اجعله قابلًا للتنفيذ:

chmod +x scripts/format.sh

التفصيل الحاسم هنا هو ${CLAUDE_PLUGIN_ROOT} — متغير بيئة يشير إلى موقع تثبيت الإضافة وقت التشغيل. لا تكتب مسارات ثابتة أبدًا في خطافات الإضافات؛ فالإضافة ستُثبّت في مكان لا تتحكم فيه على جهاز كل مستخدم. من الأحداث المفيدة الأخرى غير PostToolUse: حدث PreToolUse (لمنع إجراءات قبل تنفيذها)، وUserPromptSubmit (لحقن سياق مع كل موجّه)، وSessionStart، وStop.

الخطوة 7: تضمين خادم MCP

يمكن للإضافات أن تشحن إعدادات خوادم MCP تُفعَّل عند تفعيل الإضافة. أنشئ .mcp.json في جذر الإضافة:

{
  "mcpServers": {
    "team-docs": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "${CLAUDE_PLUGIN_ROOT}/docs"
      ]
    }
  }
}

يعرض هذا المثال مجلد docs/ مشحونًا داخل الإضافة نفسها — مفيد لسجلات قرارات المعمارية أو مراجع الواجهات البرمجية التي يجب أن يستعلم عنها الفريق كله. في النشر الفعلي ستشير غالبًا إلى خادم MCP داخلي (بوابة قاعدة بيانات، متتبع مشكلات، واجهة مراقبة). القاعدة نفسها تنطبق: استخدم ${CLAUDE_PLUGIN_ROOT} لأي شيء نسبي المسار، ومتغيرات البيئة للأسرار — لا تكتب بيانات الاعتماد أبدًا داخل .mcp.json.

أنشئ ملفًا مبدئيًا ليكون المجلد موجودًا:

mkdir -p docs
echo "# Team Engineering Docs" > docs/README.md

الخطوة 8: اختبار الإضافة محليًا

قبل نشر أي شيء، تحقق من صحة البنية. يأتي Claude Code بأداة تحقق مدمجة:

claude plugin validate .

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

cd ..
mkdir -p noqta-claude-plugins/.claude-plugin
mv team-toolkit noqta-claude-plugins/plugins/team-toolkit

انتظر بإنشاء ملف تعريف المتجر — فهذه هي الخطوة 9. لاختبار محلي سريع يمكنك إضافة مجلد المتجر مباشرة:

claude
# ثم داخل الجلسة:
/plugin marketplace add ./noqta-claude-plugins
/plugin install team-toolkit@noqta-claude-plugins

أعد تشغيل الجلسة عند المطالبة، ثم تحقق من كل مكوّن:

1. اكتب /team-toolkit:changelog 1.2.0 — يجب أن يظهر الأمر في الإكمال التلقائي ويعمل.
2. اطلب "راجع تعديلاتي المعلقة بحثًا عن مخالفات الاصطلاحات" — يجب أن يفوّض Claude المهمة إلى code-auditor.
3. اطلب من Claude إيداع شيء ما — يجب أن تشكّل مهارة conventional-commits رسالة الإيداع.
4. عدّل أي ملف TypeScript — يجب أن يعمل Prettier تلقائيًا عبر الخطاف.
5. نفّذ /mcp — يجب أن يظهر خادم team-docs مدرجًا ومتصلًا.

إذا لم يظهر أحد المكونات، شغّل claude --debug وراقب مخرجات تحميل الإضافات عند بدء التشغيل؛ فهي تسمّي كل ملف تعريف يُحلَّل وأي أخطاء تقع.

الخطوة 9: إنشاء المتجر والنشر

المتجر هو أي مستودع Git يحتوي على .claude-plugin/marketplace.json. أنشئ noqta-claude-plugins/.claude-plugin/marketplace.json:

{
  "name": "noqta-claude-plugins",
  "owner": {
    "name": "Noqta Engineering",
    "email": "dev@noqta.tn"
  },
  "metadata": {
    "description": "Internal Claude Code plugins for the Noqta team",
    "version": "1.0.0"
  },
  "plugins": [
    {
      "name": "team-toolkit",
      "source": "./plugins/team-toolkit",
      "description": "Team conventions: changelog command, code auditor, commit skill, format-on-edit hook",
      "version": "1.0.0",
      "category": "productivity"
    }
  ]
}

حقل source يقبل مسارًا نسبيًا (الإضافة تعيش في هذا المستودع)، أو مرجع GitHub، أو رابط Git — أي أن المتجر يمكنه أيضًا تجميع إضافات من مستودعات أخرى. تحقق وادفع:

cd noqta-claude-plugins
claude plugin validate .
git init && git add -A
git commit -m "feat: add team-toolkit plugin and marketplace manifest"
gh repo create noqta/claude-plugins --private --source . --push

يستطيع أي شخص لديه صلاحية الوصول الآن تثبيتها:

/plugin marketplace add noqta/claude-plugins
/plugin install team-toolkit@noqta-claude-plugins

للتحديثات: ارفع رقم version في كل من plugin.json ومدخل المتجر، ثم ادفع التغييرات، ويسحبها المستخدمون بالأمر /plugin marketplace update noqta-claude-plugins.

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

القوة الحقيقية تكمن في التفعيل التلقائي. في أي مستودع، أودع ملف .claude/settings.json يعلن عن المتجر ويفعّل الإضافة:

{
  "extraKnownMarketplaces": {
    "noqta-claude-plugins": {
      "source": {
        "source": "github",
        "repo": "noqta/claude-plugins"
      }
    }
  },
  "enabledPlugins": {
    "team-toolkit@noqta-claude-plugins": true
  }
}

الآن كل مطوّر يفتح ذلك المستودع بـ Claude Code تظهر له مطالبة واحدة للوثوق بالمتجر، ثم تُثبَّت الإضافة وتُفعَّل ذاتيًا. ينتقل إعداد العضو الجديد في الفريق من صفحة ويكي مليئة بالخطوات إلى مجرد git clone.

اختبار التنفيذ

راجع هذه القائمة للتأكد من أن كل شيء يعمل من البداية إلى النهاية:

• نجاح claude plugin validate . في مستودعي الإضافة والمتجر معًا
• ظهور team-toolkit في /plugin كإضافة مثبتة ومفعّلة
• إنتاج /team-toolkit:changelog 1.0.0 لمسودة سجل تغييرات مجمّعة
• ظهور الوكيل الفرعي code-auditor في /agents
• تشغيل Prettier عند تعديل ملف .ts (تحقق من تغيّر تنسيق الملف)
• إدراج /mcp لخادم team-docs كمتصل
• ظهور مطالبة تثبيت الإضافة عند استنساخ جديد لمستودع يحوي .claude/settings.json من الخطوة 10

استكشاف الأخطاء وإصلاحها

الأوامر لا تظهر بعد التثبيت. تحقق من بنية المجلدات: plugin.json داخل .claude-plugin/، لكن commands/ في جذر الإضافة. أعد تشغيل Claude Code بعد التثبيت — فالمكونات تُسجَّل عند بدء الجلسة.

الخطاف لا يعمل أبدًا. تأكد من أن format.sh قابل للتنفيذ (chmod +x) وأنك استخدمت ${CLAUDE_PLUGIN_ROOT} بدلًا من مسار نسبي. شغّل claude --debug لرؤية سجلات تسجيل الخطافات وتنفيذها.

خادم MCP يفشل في الاتصال. نفّذ /mcp لرؤية الخطأ. السبب الأكثر شيوعًا هو أمر غير موجود في PATH في البيئة التي يعمل فيها Claude Code — فضّل npx -y package-name على الثنائيات المثبتة عالميًا.

إضافة المتجر تفشل بخطأ في ملف التعريف. يجب أن يكون الملف في .claude-plugin/marketplace.json بالضبط، وكل مسار في source يجب أن يوجد نسبةً إلى جذر المستودع. أداة claude plugin validate . تكشف الحالتين.

الإضافة تعمل عندك ولا تعمل عند زملائك. غالبًا مسار ثابت مكتوب يدويًا أو اعتمادية ناقصة (مثل jq أو prettier) على أجهزتهم. يجب أن تتدهور الخطافات بسلاسة — لاحظ كيف يخرج format.sh بالرمز 0 عند غياب Prettier.

الخطوات التالية

• أضف أمر /team-toolkit:release يسلسل مسودة سجل التغييرات مع رفع رقم الإصدار والوسم
• اشحن دليل النشر الخاص بك كمهارة ثانية ليُحمَّل عند الاستجابة للحوادث عند الطلب
• استكشف دليلنا حول كتابة ملفات SKILL.md فعالة لصقل أوصاف المهارات
• ابنِ خادم MCP مخصصًا بلغة TypeScript وضمّنه في الإضافة
• قارن مع Claude Agent SDK عندما تحتاج وكلاء برمجيين بدلًا من أدوات تفاعلية

الخلاصة

لقد بنيت إضافة Claude Code كاملة — أمر مائل ووكيل فرعي ومهارة وخطاف وخادم MCP مدمج — وتحققت من صحتها، ونشرتها عبر متجر مستضاف على Git، وربطت التفعيل التلقائي للفريق عبر إعدادات المستودع. قوة صيغة الإضافات تكمن في أن كل جزء هو ملف Markdown أو JSON عادي في مستودع مُدار بالإصدارات: أصبحت أدوات الذكاء الاصطناعي لفريقك تتطور الآن عبر طلبات الدمج ومراجعة الشيفرة والإصدارات مثل أي برمجية أخرى. ابدأ صغيرًا بأمر واحد وخطاف واحد، ثم وسّع مجموعة الأدوات مع ترسّخ الاصطلاحات.