داخل finestructure-ai/claude-plugin: إضافة Claude Code في سبعة ملفات

المستودع كله سبعة ملفات

استنسخه، وسترى شجرة الملفات كاملة في شاشة واحدة:

.claude-plugin/
  plugin.json        686 B
  marketplace.json   507 B
commands/
  deploy.md          3.3 KB
  fs-domain.md       905 B
  fs-status.md       741 B
skills/
  fine-structure/
    SKILL.md         4.0 KB
LICENSE              MIT
README.md            2.3 KB

لا package.json، ولا ملف قفل، ولا CI، ولا dist. لا شيء يُصرَّف أو يُحزَم، ولا توجد نسخة من هذا المستودع يمكن أن يفشل بناؤها. إن كنت تؤجّل كتابة إضافة لأنك افترضت وجود سلسلة أدوات، فهذا هو التصحيح: الصيغة عرف لتنظيم المجلدات زائد ملفَّي JSON، وما تبقّى نثر.

ملف plugin.json مؤشّر لا برنامج

يحمل البيان حقول الهوية المعتادة (name، والإصدار 0.1.0، وdescription، وauthor، وhomepage، وrepository، وlicense، وkeywords) ثم كتلة واحدة تنهض بكل العمل المثير للاهتمام:

"mcpServers": {
  "finestructure": {
    "type": "http",
    "url": "https://finestructure.ai/api/mcp"
  }
}

مفتاحان اثنان. بلا command، وبلا args، وبلا env. قارن ذلك بالشكل الذي تتخذه معظم إعدادات MCP: عملية محلية (npx أو uvx أو مسار إلى ملف تنفيذي)، وقائمة وسائط، وخريطة env تحمل مفتاح API. والإعلان عن نقطة نهاية من نوع streamable HTTP بدلاً من ذلك ينقل الخادم خارج جهاز المستخدم، ولهذا تقف 105 أدوات (وهو العدد الذي يذكره ملف الـ skill) خلف بيان حجمه 686 بايت. لا شيء في إصدار Node أو Python لدى المستخدم يمكنه كسر التثبيت، وتصل تغييرات جانب الخادم دون إصدار جديد للإضافة. والمقابل هو قابلية إعادة الإنتاج: لا يمكنك تثبيت سطح الأدوات من جهة العميل.

ملف marketplace.json يجعل المستودع قناة توزيع لنفسه

يثبّت Claude Code الإضافات من أسواق لا من سجل حزم، والسوق ملف JSON يسرد الإضافات مع مسار مصدر. والملف الثاني في مجلد .claude-plugin يفعل ذلك تحديداً، ومدخل الإضافة الوحيد فيه يحمل "source": "./". فالمستودع هو الإضافة والسوق الذي يقدّمها في آن واحد، ولهذا يصير النشر مجرد git push علني:

/plugin marketplace add finestructure-ai/claude-plugin
/plugin install finestructure@finestructure

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

الأوامر قوالب مطالبات مع frontmatter

كل ملف في مجلد commands/ هو frontmatter بصيغة YAML يتلوه نثر. يعلن ملف deploy.md عن description وعن argument-hint، وهما النصّان اللذان يراهما المستخدم في قائمة الاختيار، ثم يبسط شجرة قرار مرقّمة: افحص جذر المشروع بحثاً عن .finestructure.json يحمل app_id، وإلا فاستدعِ list_apps وابحث عن تطابق في الاسم، وإلا فعامل الأمر بوصفه أول نشر واستخدم $ARGUMENTS اسماً للتطبيق. أما ملف fs-status.md فحجمه 741 بايت ويؤدي عمل أمر فرعي في CLI: حدّد التطبيق، واستدعِ get_app_status وget_app_links وget_errors، ثم لخّص. ويمرّ ملف fs-domain.md بالترتيب على add_custom_domain وget_domain_verification وcheck_domain_verification وget_domain_ssl_status وset_primary_domain.

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

أفضل السطور هي السطور المانعة. يمنع ملف deploy.md أدوات الحذف ما لم يطلبها المستخدم صراحة. ويلاحظ ملف fs-domain.md أن انتشار DNS يستغرق دقائق إلى ساعات، ويوجّه إلى اقتراح المحاولة لاحقاً بدل الدوران في حلقة تحقق. هذه سياسة إعادة محاولة وحواجز أمان مكتوبة على هيئة جُمل، وهي بالضبط ما تغفله الإضافات الساذجة.

skill مقابل command: سحب مقابل دفع

يضم ملف skills/fine-structure/SKILL.md حقلَي frontmatter اثنين، name وdescription، ويُقرأ الـ description بوصفه شرط تشغيل لا ملخصاً: يُستخدم كلما أراد المستخدم نشر تطبيق أو إنشاءه أو تحديثه، أو ربط نطاق، أو إدارة بيانات أو أسرار. وهذه الصياغة مقصودة. فالأمر ينطلق لأن إنساناً كتبه، والـ skill ينطلق لأن النموذج طابق الوصف مع ما يجري.

ويتبع ذلك تقسيم المحتوى. ملف SKILL.md نموذج ذهني لا قائمة مهام: ما التطبيق هنا (صفحات JSX، ومكوّنات مشتركة، ومخططات كيانات، ولا كود خادم اعتباطي)، وما الكيانات، وأي العمليات تستهلك أرصدة. ثم مسارات العمل بوصفها سلاسل أدوات، من get_app_files إلى read_app_file إلى write_app_file إلى validate_app إلى publish_app، مع مجموعات تغيير للتعديلات التي تمسّ عدة ملفات. ثم دلالات الأخطاء، وهي الأثقل وزناً لكل بايت: أخطاء المصادقة تعني إعادة الاتصال، وأخطاء الرصيد تعني الشحن، ولا واحدة منهما قابلة لإعادة المحاولة. والوكيل الذي يفتقر إلى هذه المعرفة يعيد محاولة فشل غير قابل للإعادة في حلقة مغلقة، وعلى منصة محسوبة التكلفة يكون لهذه الحلقة ثمن.

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

OAuth هو سبب خلوّ البيان من الأسرار

تُصادق نقطة النهاية عبر OAuth 2.1 مع تسجيل عميل ديناميكي، ولذلك يفتح أول استدعاء لأداة صفحة موافقة في المتصفح، ويحطّ الرمز في مخزن بيانات الاعتماد لدى Claude Code لا في المستودع. والنسخ المتفرّع آمن بحكم البنية، والإبطال يجري في جانب الخادم لا بوصفه تعديل إعدادات يجب أن يبلغ كل جهاز، ولا يُطلب من أحد لصق مفتاح طويل الأمد في ملف لا يفصله عن الظهور في فرق علني سوى إيداع واحد غير محسوب.

ما الذي يستحق النسخ إلى إضافتك

إرشادات عملية، بترتيب البناء تقريباً:

• ابدأ بملف .claude-plugin/plugin.json يحمل name وversion وdescription. وما عدا ذلك اختياري.
• إن كنت تشغّل نقطة نهاية MCP مستضافة فأعلن "type": "http" مع url بدل أمر محلي. هذا يحذف بيئة تشغيل المستخدم من سطح الدعم لديك.
• اشحن marketplace.json في المستودع نفسه مع "source": "./" ما دامت لديك إضافة واحدة، وأعطه اسماً مختلفاً عن اسم الإضافة.
• امنح كل أمر description وargument-hint في الـ frontmatter، مكتوبين بوصفهما إجابتين عن سؤالَي ما الذي يفعله هذا وماذا أكتب بعده.
• استخدم $ARGUMENTS بدل اختراع صياغة موضعية. لا يوجد محلّل نحوي، بل استبدال فقط.
• اكتب متون الأوامر شجراتِ قرار مع تسمية الأدوات صراحة. فعبارة "إن كان ملف الإعدادات موجوداً فاقرأ app_id، وإلا فاستدعِ list_apps" تصمد أفضل من فقرة نوايا.
• دوّن دلالات الفشل كتابةً: أي الأخطاء نهائية، وأيها قابل لإعادة المحاولة، وماذا يُقال بدل إعادة المحاولة.
• سمِّ أدواتك المدمّرة في النص وامنعها ما لم تُطلب.
• أبقِ نموذج المجال في SKILL.md والإجراء في الأمر. والتكرار بينهما علامة سيئة.
• اختبر بـ /plugin marketplace add مقابل مسار محلي أو مقابل نسختك المتفرّعة قبل أن توجّه أحداً إلى main.

حواف خشنة

ثلاث حواف بصراحة، ولا واحدة منها قاتلة. كل شيء بالإنجليزية، والصيغة لا تقدّم أي معلّق لإصلاح ذلك: لا مفتاح locale في الـ frontmatter، ومن ثمّ فالتوطين يعني ملفات أوامر مكرّرة أو القبول بعدم التطابق.

ولحكاية الخلوّ من مفاتيح API نجمة تحفّظ. يعترف ملف SKILL.md بأن أدوات توليد الوسائط تقع خارج اتصال OAuth وتحتاج رمز MCP ثابتاً بصلاحيات وسائط، يُنشأ في Studio الخاص بالمنصة ويُرسل في ترويسة bearer. تتعامل الإضافة مع ذلك تعاملاً حسناً، إذ تطلب من النموذج أن يشرح الغياب بدل أن يعيد المحاولة في وجه جدار، لكنه مسار مصادقة ثانٍ مركّب على تصميم نقطة بيعه أن لديه مساراً واحداً.

ثم إنه الإصدار 0.1.0 بلا changelog ولا اختبارات ولا CI. وهذا مقبول في حالة markdown، وإن كان فحص مخطط JSON داخل hook قبل الإيداع كفيلاً بالتقاط صنف الأخطاء الوحيد الذي يكسر التثبيت فعلاً، أي بيان مشوّه. وطلب الإدراج في الدليل قيد المراجعة وقت كتابة هذه السطور، ولذلك يجري التثبيت في الوقت الحالي بالإشارة إلى المستودع.

اقرأ ملفات الأوامر الثلاثة أولاً، ثم SKILL.md، ثم ملفَّي JSON. بهذا الترتيب تشرح الصيغة نفسها: الـ markdown يقرر ما ينبغي أن يحدث وبأي ترتيب، وخادم MCP يقرر ما يجري تنفيذه فعلاً، والبيان هو الدرز الرفيع بينهما.