المساهمة بإضافة Plugin

يشرح هذا الدليل كيفية إنشاء إضافة (Plugin) جديدة وإضافتها إلى سوق f5-sales-demo.

هيكل الإضافة (Plugin)

تعيش كل إضافة في مجلدها الخاص ضمن plugins/ وتتبع الهيكل التالي:

• Directoryplugins/

  • Directoryexample-plugin/

    • Directory.claude-plugin/

      • plugin.json
    • Directoryskills/

      • Directoryexample-skill/

        • SKILL.md
        • Directoryreferences/

          • reference-data.md
    • Directorycommands/

      • example-command.md
    • Directoryagents/

      • example-agent.md
    • README.md

إنشاء إضافة (Plugin)

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

   mkdir -p plugins/example-plugin/.claude-plugin
   mkdir -p plugins/example-plugin/skills
   mkdir -p plugins/example-plugin/commands

2. كتابة plugin.json

   أنشئ الملف plugins/example-plugin/.claude-plugin/plugin.json:

   {
     "name": "example-plugin",
     "description": "What this plugin does",
     "version": "1.0.0",
     "author": {
       "name": "f5-sales-demo"
     },
     "homepage": "https://github.com/f5-sales-demo/marketplace/tree/main/plugins/example-plugin",
     "keywords": ["relevant", "keywords"],
     "license": "Apache-2.0",
     "repository": "https://github.com/f5-sales-demo/marketplace"
   }

3. إضافة المهارات (Skills)

   أنشئ الملف plugins/example-plugin/skills/example-skill/SKILL.md مع البيانات الأولية (frontmatter):

   ---
   name: example-skill
   description: One-line description of what this skill does
   ---
   
   Detailed instructions for Claude when this skill activates.

   ضع أي بيانات مرجعية في مجلد فرعي باسم references/ بجانب SKILL.md.

4. إضافة الأوامر (Commands)

   أنشئ الملف plugins/example-plugin/commands/example-command.md:

   ---
   description: What this command does
   argument_hint: "[optional-args]"
   allowed_tools:
     - Read
     - Glob
     - Grep
   ---
   
   Instructions for Claude when the user invokes this command.

5. إضافة الإضافة إلى marketplace.json

   أضف مدخلاً إلى مصفوفة plugins في .claude-plugin/marketplace.json:

   {
     "name": "example-plugin",
     "description": "What this plugin does",
     "version": "1.0.0",
     "author": { "name": "f5-sales-demo" },
     "source": "./plugins/example-plugin",
     "category": "productivity",
     "homepage": "https://github.com/f5-sales-demo/marketplace/tree/main/plugins/example-plugin",
     "license": "Apache-2.0",
     "keywords": ["relevant", "keywords"],
     "tags": ["searchable", "tags"],
     "repository": "https://github.com/f5-sales-demo/marketplace"
   }

6. الاختبار محلياً

   اختبر إضافتك دون نشرها عن طريق توجيه Claude Code إلى المجلد المحلي:

   claude --plugin-dir ./plugins/example-plugin

   تحقق من أن المهارات (Skills) تُفعَّل في السياق الصحيح وأن الأوامر تُنتج المخرجات المتوقعة.

تقديم إضافتك (Plugin)

سير عمل المستودع

يُطبّق هذا المستودع سير عمل حوكمة صارمًا. راجع CONTRIBUTING.md للاطلاع على العملية الكاملة.

1. أنشئ طلب (Issue) على GitHub يصف الإضافة الجديدة
2. أنشئ فرعاً (Branch) للميزة من main
3. أضف مجلد إضافتك وحدّث marketplace.json
4. أضف صفحة توثيق في المسار docs/plugins/example-plugin.mdx
5. افتح طلب سحب (PR) مرتبطاً بالطلب باستخدام Closes #N
6. أصلح أي إخفاقات في CI واندمج بعد اجتياز الفحوصات

أفضل الممارسات

• أبقِ المهارات مُركّزة — يجب أن تؤدي كل مهارة شيئاً واحداً بشكل جيد
• استخدم الملفات المرجعية — ضع مجموعات البيانات الكبيرة والمخططات وجداول البحث في references/ بدلاً من تضمينها مباشرةً في SKILL.md
• حدّد النطاق بذكاء — تحقق من التغييرات غير المُقيَّدة (uncommitted changes) لتضييق نطاق العمل عند الإمكان
• جمّع المخرجات حسب الخطورة — استخدم مستويات ERROR وWARNING وINFO حتى يتمكن المستخدمون من تحديد أولويات الإصلاحات
• اكتب ملف README — أدرج أمثلة الاستخدام ووصفاً لما تفعله كل مهارة وأمر