مشاركة مهارات الوكيل بين المستودعات دون اختلافات

كيفية مشاركة مهارات الوكيل بين المستودعات

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

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

مهارة الوكيل هي مجلد يحتوي على ملف SKILL.md، بالإضافة إلى أيّ نصوص برمجية وملفات مرجعية تحتاج إليها. إذا كان هذا المفهوم جديدًا عليك، فاقرأ أولاً ما هي مهارة الوكيل وكيف يعمل SKILL.md. تتناول هذه الصفحة سلسلة التوريد المحيطة بهذه الوحدة.

مكان وجود المهارة، ولماذا يصعب مشاركتها

يحمّل Claude Code المهارات من ثلاثة أماكن، وتذكر وثائق المهارات كل مسار.

• ~/.claude/skills/<skill-name>/SKILL.md شخصي. يُحمَّل في جميع مشاريعك، وليس في مشاريع أي شخص آخر.
• .claude/skills/<skill-name>/SKILL.md على مستوى المشروع. يُحمَّل لكل من يستنسخ ذلك المستودع.
• <plugin>/skills/<skill-name>/SKILL.md يأتي داخل إضافة. يُحمَّل في كل مكان تكون فيه تلك الإضافة مفعّلة.

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

لا توفر البيانات التمهيدية أي مساعدة. تسمح مواصفة Agent Skills بستة مفاتيح، وتطبع مسارات التوزيع التي تفرض هذه المواصفة القائمة عند استخدام مفتاح آخر:

Unexpected key(s) in SKILL.md frontmatter: argument-hint. Allowed properties are: allowed-tools, compatibility, description, license, metadata, name

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

المشكلة الأولى: ثماني نسخ تتباعد بصمت

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

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

المشكلة الثانية: لا شيء يثبّت الإصدار

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

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

المشكلة الثالثة: لا أحد يعرف ما إذا كانت المهارة لا تزال تعمل

لا تملك المهارة مُصرِّفاً. فهي تعليمات موجّهة إلى نموذج، ولذلك قد تتوقف عن العمل بينما يبقى الملف مطابقاً بايتاً ببايت. قد تؤدي ترقية النموذج إلى تغيير مدى التزامه بالتعليمات الطويلة. وقد تعيد أداة سطر الأوامر التي تستدعيها المهارة تسمية أحد الخيارات. وقد يبدأ عنوان URL في ملف مرجعي بإرجاع الخطأ 404، فيعمل الوكيل اعتماداً على صفحة الخطأ.

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

ما الذي تحلّه الأدوات التي ستصدر في 2026

تصل عدة إجابات الآن، لكنها تختلف حول مكان حفظ الإصدار.

ملفات القفل. تثبّت أداة سطر الأوامر skills من Vercel Labs (vercel-labs/skills، المرخّصة بموجب MIT، بالإصدار v1.5.22 في 5 August 2026) المهارات من مستودع git في الدليل الذي يتوقعه وكيلك، وهي تعرف بنية أكثر من سبعين وكيلاً. ينفّذ npx skills add <repo> التثبيت، وينفّذ npx skills update الترقية، ويعرض npx skills list ما لديك. يُحفَظ سجل المهارات المثبّتة مرة واحدة لكل مستخدم، لا مرة واحدة لكل مستودع. ويطلب طلب مفتوح في ذلك المشروع (issue 283) إضافة الأمر skills install لإعادة تثبيت كل مهارة مسجّلة من ملف القفل، حتى تحصل آلة ثانية على المجموعة نفسها. تعامل مع ذلك الطلب بوصفه تقريراً عن الحالة. فكرة ملف القفل محسومة. أما الجزء الخاص بكل مشروع فما زال قيد البناء.

المواصفات والاختبارات. تتخذ SkillSpec الاتجاه الآخر. فهي تتعامل مع SKILL.md بوصفه عقداً يجب التحقق منه، لا نصاً يُوثق به، وهدفها المعلن هو جعل المهارات «قابلة للاتباع والاختبار والإثبات». يعرض skillspec doctor <path> المواضع التي يُرجح أن يفقد فيها الوكيل سياق المهمة. ويعرض skillspec boundary map <path> ما يمكن للمهارة الوصول إليه، ثم يرتّب skillspec boundary assess <path> هذه النتائج حسب مستوى المخاطر. هذه حزمة Rust، مرخّصة بموجب MIT أو Apache 2.0، وبالإصدار 0.2.2 في 29 July 2026. ثبّت الإصدار المحدد بدلاً من تثبيت الأحدث:

cargo install skillspec --version 0.2.2 --locked
skillspec --version

يُنشئ --locked البرنامج باستخدام إصدارات التبعيات التي نُشرت الحزمة معها، لذلك لا يتغير البناء أثناء التنفيذ. يجب أن يطبع skillspec --version القيمة 0.2.2. ويعني ظهور رقم مختلف أن ملفاً ثنائياً أقدم في PATH يسبق الملف المطلوب في أولوية البحث.

ممارسة المورّد. شرحت Google طريقة بناء المهارات في google/skills ضمن منشور عن كيفية بناء مهارات الوكلاء واختبارها وتوسيع نطاقها. إذا استبعدنا عامل الحجم، فالآلية هي التكامل المستمر (CI) المعتاد. تمرّر كل مهارة أدوات فحص للبيانات الوصفية في frontmatter، وعدد الأسطر، وبنية الدليل، والتسمية قبل دمجها. ويفشل مدقّق الروابط عملية البناء عند إعادة أي عنوان URL للحالة 404، وبذلك يكتشف الرابط المعقول الذي اخترعه وكيل. يجب على المؤلفين توفير مجموعة مطالبات للتقييم ومعيار لتسجيل النتائج إلى جانب المهارة. ثم تشغّل مهام تقييم مجدولة اختبارات أسبوعية على المكتبة كاملة لاكتشاف التراجعات، ولكل مهارة مالك محدد يُتوقع منه إصلاحها عند انخفاض الجودة.

النمط المشترك بين الإجابات الثلاث

لست مضطراً إلى اختيار أحدها. يوجد تحتها جميعاً شكل واحد، ويوفّر لك git العادي هذا الشكل كاملاً.

1. مصدر واحد للحقيقة. يوجد skill في مكان واحد فقط، ويشير كل مستودع إلى ذلك المكان بدلاً من الاحتفاظ بنسخة منه.
2. إصدار مثبّت لكل مستودع. يسجّل كل مشروع المراجعة الدقيقة التي يستخدمها، لذلك تصبح الترقية commit في ذلك المشروع، مع مؤلف وتاريخ.
3. اختبار دخاني لكل skill. يوجد فحص واحد قابل للتشغيل يثبت أن skill ما زال ينتج النتيجة التي يعد بها.
4. مسار للمراجعة. يخضع أي تغيير على skill مشترك للمراجعة، ويرى كل مستهلك الفرق قبل اعتماده.

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

تخطيط لفريق صغير يستخدم مستودع git مستضافاً ذاتياً

يحتوي مستودع واحد على المهارات. ولا يوجد فيه أي محتوى آخر، لذلك يعرض سجله تاريخ تغييرات للتعليمات.

agent-skills/
  skills/
    api-review/
      SKILL.md
    release-notes/
      SKILL.md
  tests/
    api-review.sh
    release-notes.sh
  CHANGELOG.md

الإصدارات هي وسوم. استخدم وسوماً مشروحة، لأنها تتضمن رسالة وتاريخاً. اكتب الرسالة بصيغة توضّح سبب رغبة المستهلك في الترقية:

git tag -a v1.4.0 -m "api-review: require pagination on list endpoints"
git push origin v1.4.0

إذا كان remote لديك هو Gitea أو Forgejo أو GitLab، أو كان مستودعاً عارياً عبر SSH على VPS تملكه، فلن يتغير أي شيء مما يلي. كل ما تحتاج إليه هنا هو git وsymlink.

التثبيت باستخدام وحدة فرعية في git

تسجّل الوحدة الفرعية commit واحداً محدداً من مستودع آخر داخل مستودعك. هذا السجل هو التثبيت. في كل مشروع يستخدمها:

git submodule add https://git.example.com/team/agent-skills.git vendor/agent-skills
git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills checkout v1.4.0
mkdir -p .claude/skills
ln -s ../../vendor/agent-skills/skills/api-review .claude/skills/api-review
git add .gitmodules vendor/agent-skills .claude/skills/api-review
git commit -m "Pin shared agent skills to v1.4.0"

الرابط الرمزي هو الجزء الذي يجعل ذلك ممكناً. قد يكون إدخال المهارة على مستوى المشروع رابطاً رمزياً إلى دليل آخر على القرص، ويتبعه Claude Code ويقرأ SKILL.md من الهدف. لذلك تُحمّل المهارة كمهارة مشروع عادية، بينما تبقى الملفات في الوحدة الفرعية عند commit اخترته.

تحقق من التثبيت:

git submodule status

يبدأ السطر السليم بمسافة، ثم commit، ثم المسار، ثم أقرب وسم:

 4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602 vendor/agent-skills (v1.4.0)

تعني - في بداية السطر أن الوحدة الفرعية لم تتم تهيئتها من قبل، ولذلك يشير .claude/skills/api-review إلى لا شيء ولا تُحمّل المهارة بصمت. أصلح ذلك باستخدام git submodule update --init. وتعني + في بداية السطر أن commit المسحوب يختلف عن commit المسجّل، ولذلك يشغّل ذلك المطوّر تعليمات لا يملكها أي شخص آخر. تحتاج النسخ المستنسخة حديثاً إلى git clone --recurse-submodules، ويجب أن يرد هذا السطر في README، لأن الاستنساخ العادي يترك vendor/agent-skills فارغاً ولا يطبع أي خطأ.

تتم الترقية عمداً، وهذا هو الهدف الأساسي:

git -C vendor/agent-skills fetch --tags
git -C vendor/agent-skills diff v1.4.0 v1.5.0 -- skills/
git -C vendor/agent-skills checkout v1.5.0
git add vendor/agent-skills
git commit -m "Bump shared agent skills to v1.5.0"

يمثل سطر diff مسار المراجعة. فهو يعرض التغيير نفسه الذي سيراه كل مستودع آخر يستخدم الوحدة، ويمكن إدراجه في pull request.

التثبيت باستخدام سوق الإضافات بدلاً من ذلك

إذا كنت تفضّل عدم مطالبة كل مطوّر بتعلّم الوحدات الفرعية، فنظام إضافات Claude Code يتولى التوزيع عنك، ويعمل مع مستودع بعيد مستضاف ذاتياً. ضع فهرساً في .claude-plugin/marketplace.json داخل مستودع المهارات:

{
  "name": "acme-agents",
  "owner": { "name": "Platform team", "email": "platform@example.com" },
  "plugins": [
    {
      "name": "team-skills",
      "description": "Shared review and release skills",
      "version": "1.4.0",
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0",
        "sha": "4d1a7c2f0b93e5a1c8d6f2b40e7a95c3d1f8b602"
      }
    }
  ]
}

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

يعلن كل مستودع مستهلك بعد ذلك عن سوق الإضافات في ملف .claude/settings.json الملتزم به:

{
  "extraKnownMarketplaces": {
    "acme-agents": {
      "source": {
        "source": "url",
        "url": "https://git.example.com/team/agent-skills.git",
        "ref": "v1.4.0"
      }
    }
  },
  "enabledPlugins": {
    "team-skills@acme-agents": true
  }
}

تظهر مطالبة بتثبيت سوق الإضافات لزميل الفريق الذي يثق بمجلد المشروع، وتُفعّل الإضافة لديه دون الحاجة إلى صفحة في الويكي تخبره بذلك. تصبح المهارات متاحة بعد ذلك عبر /team-skills:api-review، لأن مهارات الإضافات تستخدم نطاق اسم الإضافة ولا يمكن أن تتعارض مع مهارة مشروع تحمل الاسم نفسه. بعد دفع وسم جديد، يحدّث المستهلكون المحتوى باستخدام /plugin marketplace update acme-agents، ثم يشغّلون /reload-plugins إذا طلب ملخص التثبيت ذلك.

كتابة اختبار دخان لمهارة واحدة

اختبار الدخان هو تشغيل وكيل مُبرمج على fixture يتضمن عطلاً معروفاً، مع assertion واحدة. يعمل Claude Code في وضع غير تفاعلي باستخدام -p، وتعمل المهارة التي يستدعيها المستخدم في هذا الوضع: ضع /skill-name في سلسلة prompt، وسيُوسَّع قبل بدء التشغيل.

#!/usr/bin/env bash
set -euo pipefail

claude -p "/api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --allowedTools "Read" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"rule_ids":{"type":"array","items":{"type":"string"}}},"required":["rule_ids"]}' \
  | jq -e '.structured_output.rule_ids | index("pagination-required")' > /dev/null

fixtures/orders-api.md هو ملف قصير يتضمن عطلاً متعمداً واحداً. تتمثل assertion في أن تسميه المهارة. يخرج jq -e برمز غير صفري عندما ينتج filter الخاص به null، لذلك يفشل البرنامج النصي إذا توقفت المهارة عن التقاط العطل المُدرج. ويخرج claude نفسه برمز غير صفري عند فشل التشغيل، بينما يحوّل set -euo pipefail أيّاً من الفشلين إلى اختبار فاشل.

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

في CI، أضف --bare. من دونه، يحمّل claude -p السياق نفسه الذي ستحمّله جلسة تفاعلية، بما في ذلك hooks وplugins وCLAUDE.md من الجهاز الذي يعمل عليه. لذلك يمكن لإعدادات أحد أعضاء الفريق الشخصية أن تغيّر النتيجة. يتجاوز bare mode كل الاكتشاف التلقائي، ما يعني أنه يتجاوز أيضاً المهارة التي تختبرها، لذا حمّل تلك المهارة صراحةً. ولا يقرأ bare mode بيانات تسجيل الدخول إلى اشتراكك أيضاً، لذلك عيّن ANTHROPIC_API_KEY في البيئة أولاً:

claude --bare -p "/team-skills:api-review Read fixtures/orders-api.md and list the rule ids it breaks." \
  --plugin-dir vendor/agent-skills \
  --allowedTools "Read" \
  --output-format json

باستخدام --output-format stream-json، يعرض الحدث الأول في التشغيل الـplugins التي حُمّلت، ويتضمن مصفوفة plugin_errors للـplugins التي لم تُحمّل. افشل مهمة CI عند عدم فراغ plugin_errors. يكشف ذلك عن pin يشير إلى revision لم يعد موجوداً، وهو ما سيظهر بخلاف ذلك على شكل تجاهل الوكيل لقواعدك المحلية بهدوء.

المهارة المشتركة هي تعليمات قابلة للتنفيذ

تجعل ميزتان هذا الوصف حرفياً، وكلتاهما مهمتان عندما يأتي الملف من فريق آخر.

أولاً، يمكن لـ SKILL.md تنفيذ أوامر shell قبل أن يقرأ النموذج أي شيء. سطر كهذا في النص الأساسي هو معالجة مسبقة:

- Current branch: !`git rev-parse --abbrev-ref HEAD`

يُنفَّذ الأمر على الجهاز الذي يحمّل المهارة، ويستبدل ناتجه العنصر النائب في النص الذي يتلقاه النموذج. كما تنفّذ كتلة محاطة بثلاث علامات backtick ومفتوحة بـ ! عدة أوامر بالطريقة نفسها. لا يوافق أحد على أي من ذلك وقت التشغيل. تعني قراءة مهارة مشتركة قراءة استبدالات أوامرها.

ثانياً، يمكن لـ frontmatter الموافقة مسبقاً على الأدوات. يمنح allowed-tools الأدوات المدرجة دون طلب إذن أثناء الدورة التي استدعت المهارة. وبالنسبة إلى مهارة خاصة بمشروع، يسري هذا المنح بمجرد أن يقبل أحدهم مربع حوار الثقة في مساحة العمل الخاصة بالمجلد. توضح وثائق Claude Code النتيجة بوضوح: راجع مهارات المشروع قبل الوثوق بالمستودع، لأن المهارة يمكن أن تمنح نفسها وصولاً واسعاً إلى الأدوات.

لذلك تعامل مع تحديث المهارة مثل تحديث الاعتمادية تماماً. ثبّت الإصدار باستخدام commit محدد بدقة حيثما تسمح الآلية بذلك، لأن tag يمكن تغييره، بينما يتحرك branch بحكم تعريفه. على جهاز مقيّد، يستبدل "disableSkillShellExecution": true في الإعدادات كل استبدال أوامر بالنص الحرفي [shell command execution disabled by policy] بدلاً من تنفيذه، ولا يمكن للمستخدم تجاوز هذا الإعداد عند تطبيقه من خلال الإعدادات المُدارة. تُستثنى المهارات المضمّنة والمُدارة من هذا الإعداد.

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

ما يجب قراءته عند رفع الإصدار

• الفرق في محتوى كل SKILL.md، لأن هذا النص هو التعليمات التي سيتبعها وكيلك.
• كل استبدال أوامر، لأن هذه الأوامر تُنفَّذ على جهازك عند تحميل المهارة.
• أي تغيير في allowed-tools، لأن هذا السطر يمنح الأدوات دون طلب تأكيد.
• تشغيل الاختبارات المرتبط بالوسم. إذا كان المستودع المشترك يشغّل اختبارات تحقق أولية خاصة به في CI، فيجب أن يكون للوسم الذي تثبّته تشغيل ناجح مرفق به.

إذا تعذّر على المراجع قراءة الفرق الكامل خلال عشر دقائق، فهذا يعني أن المهارة أصبحت كبيرة أكثر من اللازم. قسّمها. وينطبق الأمر نفسه على مستندات المستودع التي يقرأها وكلاؤك: احتفظ بالقواعد الثابتة في الملفات الموضّحة في التقسيم بين AGENTS.md وHUMAN.md، وبالتعليل المعماري في ملف DESIGN.md المكتوب للوكلاء، واترك المهارات لإجراءات محددة وضيقة النطاق.

عندما يؤدي تغيير النموذج أو الأداة إلى تعطيل إحدى المهارات

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

لهذا السبب يحمل اختبار التشغيل الأساسي الأهمية الأكبر في هذا الترتيب. شغّل اختبار كل مهارة وفق جدول زمني، وكذلك عند تنفيذ push. تشغّل Google مهام التقييم أسبوعياً على المكتبة بأكملها لهذا السبب، وتكفي مهمة cron أسبوعية على VPS صغير لفريق لديه عشر مهارات. هذه هي الطريقة الوحيدة لمعرفة العطل قبل أن يكتشفه أحد المطورين.

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

FAQ

كيف أشارك مهارة وكيل واحدة عبر عدة مستودعات؟

ضع المهارة في مستودع git مخصص، وأنشئ علامات للإصدارات فيه، واجعل كل مشروع يستخدمها يشير إلى علامة بدلاً من نسخ الملف. توجد آليتان مناسبتان. يسجل git submodule تعييناً إلى commit محدد، ويجعل symlink من .claude/skills/<name> إلى داخل submodule المهارة تُحمَّل كمهارة عادية للمشروع. ويؤدي plugin marketplace الغرض نفسه من خلال /plugin، مع تعريف التثبيت في .claude/settings.json بالمستودع المستهلك. تحفظ كلتا الآليتين الإصدار في سجل git، لذا يمكنك تحديد التعليمات التي أنتجت تشغيل وكيل معيّناً.

هل يمكنني تثبيت مهارة وكيل على إصدار محدد؟

ليس من داخل SKILL.md، لأن frontmatter هذا لا يحتوي على المفتاح version. يجب أن يأتي التثبيت من الطبقة المحيطة بالملف. يثبت git submodule commit محدداً بحكم تصميمه. في Claude Code plugin marketplace، يقبل مصدر plugin القيمة ref لفرع أو علامة، والقيمة sha لـcommit محدد، وتكون sha هي المعتمدة عند وجود القيمتين. يقبل مصدر marketplace نفسه ref فقط. فضّل التثبيت باستخدام commit، لأن العلامة قد تُنقل بعد مراجعتها.

ما الذي ينبغي أن يؤكده اختبار smoke للمهارة؟

تحقق من شيء ثابت. شغّل المهارة بصورة غير تفاعلية على fixture يحتوي على خطأ معروف، ثم تحقق من ظهور معرّف محدد في الناتج، مثل rule id يفترض أن تبلغ عنه المهارة. يجعل طلب الناتج المنظم باستخدام --output-format json و--json-schema التحقق دقيقاً، وتفشل jq -e البرنامج النصي عند غياب القيمة. لا تتحقق من جملة كاملة، لأن النموذج يعيد صياغة إجاباته بين عمليات التشغيل.

هل تثبيت مهارة مشتركة من مستودع فريق آخر آمن؟

تعامل معها باعتبارها تبعية برمجية، لأنها تعليمات قابلة للتنفيذ. يمكن لـSKILL.md تشغيل أوامر shell عند التحميل من خلال صيغة استبدال الأوامر !، كما يمكن للحقل allowed-tools في frontmatter أن يمنح الأدوات موافقة مسبقة دون عرض مطالبة. اقرأ diff عند كل تحديث، وثبّت المهارة على commit محدد بدلاً من فرع، وفضّل مصدراً يتحكم فيه فريقك. على الأجهزة المُدارة، يمنع "disableSkillShellExecution": true في الإعدادات تشغيل استبدالات الأوامر بالكامل.

هل ستعمل المهارة المشتركة مع وكلاء غير Claude Code؟

يعتمد ذلك على frontmatter الذي تستخدمه. تحدد مواصفة Agent Skills ستة مفاتيح: name وdescription وlicense وcompatibility وmetadata وallowed-tools. تُحمَّل المهارة المقتصرة على هذه المفاتيح عبر الأدوات التي تطبق المواصفة، كما تُحمَّل في Claude Code دون تغييرات. تُتجاهل المفاتيح وميزات النص الخاصة ببيئة التشغيل التي تتجاوز المواصفة أو تُرفض في البيئات الأخرى، لذا أبقِها خارج أي مهارة تنوي مشاركتها على نطاق واسع.