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

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

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

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

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

موضع المهارة ولماذا يصعب مشاركتها

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

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

يحمّل Claude Code أيضاً المهارات من أدلة المشاريع المتداخلة، والأدلة المحددة باستخدام --add-dir، والمهارات المفعّلة لحسابك على claude.ai.

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

لا تساعد بيانات frontmatter في ذلك. تسمح مواصفة 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 في مستند تهيئة الحساب، أو اسم مستعار للصدفة يزامن مجلداً. كل هذه الطرق تثبّت الإصدار الموجود حالياً عند رأس الفرع.

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

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

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

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

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

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

ملفات القفل. تثبّت أداة سطر الأوامر skills من Vercel Labs (vercel-labs/skills، المرخّصة بموجب MIT، والإصدار v1.7.2 منها هو الأحدث في 9 October 2026) المهارات من مستودع git في الدليل الذي يتوقعه وكيلك، وهي تعرف بنية أكثر من سبعين وكيلاً. ينفّذ npx skills add <repo> التثبيت، وينفّذ npx skills update الترقية، ويعرض npx skills list ما ثبّتَّه. وتحافظ الأداة على ملفي قفل. يسجّل الملف العام الموجود في ~/.agents/.skill-lock.json ما ثبّته مستخدم واحد. ومنذ الإصدار v1.4.1 (20 February 2026)، يؤدي التثبيت على نطاق المشروع أيضاً إلى كتابة skills-lock.json في جذر المشروع، ويذكر المصدر البرمجي للأداة أن هذا الملف مخصّص لإدراجه في نظام التحكم بالإصدارات. يستعيد npx skills experimental_install مهارات المشروع منه. أُغلقت المسألة 283، التي طلبت الأمر skills install لاستعادة ملف القفل العام على جهاز آخر، باعتبارها غير مخططة في 5 November 2026؛ ويحدد المشرف عليها أنها الطلب نفسه الوارد في المسألة 549. تعامل مع المسألتين على أنهما تقرير عن الحالة. ملف القفل الخاص بكل مشروع موجود. أما الأمر الذي يستعيد المهارات منه، فما زال موسوماً بأنه تجريبي في الإصدار v1.7.6 المنشور؛ كما يدعم الفرع الرئيسي للمشروع الآن npx 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، وما زال أحدث إصدار على crates.io في 10 October 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، مما يكشف الرابط المعقول الذي اخترعه وكيل. ويجب على المؤلفين توفير مجموعة prompts للتقييم ومعيار لتسجيل النتائج إلى جانب المهارة. ثم تشغّل مهام التقييم المجدولة اختبارات أسبوعية على المكتبة بأكملها لاكتشاف حالات التراجع، ولكل مهارة مالك محدد يُتوقع منه إصلاحها عندما تنخفض جودتها.

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

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

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

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

تخطيط لفريق صغير على مستودع 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 ورابط رمزي.

التثبيت باستخدام وحدة 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"

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

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

git submodule status

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

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

تعني - في بداية السطر أن الوحدة الفرعية لم تتم تهيئتها مطلقاً، ولذلك يشير .claude/skills/api-review إلى لا شيء ولا تُحمَّل skill بصمت. أصلح ذلك باستخدام 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 داخل مستودع skills:

{
  "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 هو التثبيت الفعلي. تختلف أسماء الأنواع أيضاً. داخل الكتالوج، يشير url إلى مستودع git لاستنساخه. أما في مصدر السوق، فيشير url إلى رابط مباشر لملف marketplace.json، ويكون مستودع git هو git.

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

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

يسجّل Claude Code السوق لزميل الفريق بعد أن يوافق على مربع حوار الثقة بمساحة العمل لمجلد المشروع، من دون الحاجة إلى صفحة wiki تطلب منه تنفيذ ذلك. يشير إدخال الكتالوج إلى عنوان URL لمستودع git بدلاً من مسار نسبي، لذلك لا تُثبَّت الإضافة نفسها من إعدادات المستودع وحدها. ينفّذ كل زميل claude plugin install team-skills@acme-agents --scope project مرة واحدة، وإلى أن يفعل ذلك يعرض Claude Code أن الإضافة مفعّلة في إعدادات المشروع لكنها غير مثبّتة. تصبح skills متاحة بعد ذلك عبر /team-skills:api-review، لأن skills الخاصة بالإضافات تستخدم مساحة أسماء مشتقة من اسم الإضافة ولا يمكن أن تتعارض مع skill للمشروع تحمل الاسم نفسه. بعد دفع وسم جديد، يحدّث المستهلكون المحتوى باستخدام /plugin marketplace update acme-agents، ثم ينفّذون /reload-plugins إذا طلب ملخص التثبيت ذلك.

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

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

#!/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 من الجهاز الذي يعمل عليه. لذلك يمكن لإعدادات أحد أعضاء الفريق الشخصية أن تغيّر النتيجة. يتجاوز الوضع المجرد الاكتشاف التلقائي، باستثناء المهارات الموجودة في .claude/skills/ ضمن directory تم توفيره صراحةً باستخدام --add-dir؛ وهو يتجاوز مهارة المشروع التي تختبرها هنا، لذلك حمّلها صراحةً. ولا يقرأ الوضع المجرد بيانات تسجيل الدخول إلى الاشتراك، لذلك اضبط 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

تأخذ plugin التي تُحمّل باستخدام --plugin-dir اسمها من .claude-plugin/plugin.json، ومن دون ذلك manifest تُسمّى باسم directory الخاص بها. أضف plugin.json مع "name": "team-skills" بجانب catalog في مستودع المهارات، وإلا فسيتعين على الأمر أعلاه استدعاء /agent-skills:api-review بدلاً من ذلك.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

لهذا السبب، يحمل اختبار الدخان الأهمية الأكبر في هذا الترتيب. شغّل اختبار كل مهارة وفق جدول زمني، وكذلك عند تنفيذ 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 test للمهارة؟

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

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

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

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

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