كيف تكتب مهارة خاصة لوكيل الذكاء الاصطناعي الخاص بك

كتابة مهارة الوكيل الخاصة بك بناءً على فشل حقيقي

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

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

ابدأ من مهمة أخطأ فيها الوكيل مرتين

المرة الأولى صدفة. المرة الثانية نمط، والنمط يستحق التوثيق في ملف.

إليك فشل يتكرر على الخوادم الحقيقية. تطلب من الوكيل إضافة كتلة Reverse Proxy إلى Nginx. يقوم الوكيل بتعديل /etc/nginx/conf.d/app.conf، ثم يشغّل sudo systemctl restart nginx. يحتوي التعديل على خطأ مطبعي، فيرفض Nginx البدء، ويتوقف الموقع عن العمل حتى تقوم بإصلاحه:

nginx: [emerg] unknown directive "proxy_pas" in /etc/nginx/conf.d/app.conf:12
Job for nginx.service failed because the control process exited with error code.

أنت تصحح الخطأ في المحادثة. اختبر الإعدادات باستخدام sudo nginx -t قبل لمس الخدمة، ثم طبّقها باستخدام reload بدلاً من restart. بعد أسبوع، في مهمة مختلفة، يقع نفس الخطأ. تلك المرة الثانية هي الإشارة.

دوّن شيئين بينما لا يزال الفشل أمامك: الطلب الذي كتبته، والتصحيح الذي قدمته، بالكلمات التي استخدمتها. هذان السطران يصبحان المهارة. يخبرك الطلب بما يجب أن يطابقه المحفز. التصحيح هو المحتوى الكامل.

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

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

تشريح المهارة

المهارة هي مجلد يحتوي على ملف واحد مطلوب.

.claude/skills/nginx-config-changes/
├── SKILL.md
├── reference/
│   └── proxy-headers.md
└── scripts/
    └── check-and-reload.sh

يُفتح SKILL.md بكتلة بيانات وصفية (frontmatter)، وهي بضعة إعدادات مكتوبة بصيغة YAML (نفس تنسيق الإعدادات الذي تستخدمه ملفات Docker Compose) بين علامتي ---، متبوعة بالتعليمات بصيغة markdown. إليك المهارة الكاملة للخطأ المذكور أعلاه.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
---

## Rules

Run `sudo nginx -t` after every edit under `/etc/nginx`. Do not touch the service until it prints `test is successful`.

Apply the change with `sudo systemctl reload nginx`. Never use `restart`. A reload keeps the running workers serving traffic until the new config parses, so a broken config leaves the site up. A restart stops nginx first, so a broken config takes the site down.

If `nginx -t` fails, fix the file and test again. Never reload a config that failed the test.

For the proxy header defaults this project expects, see [reference/proxy-headers.md](reference/proxy-headers.md).

هذا الملف يتكون من أقل من عشرين سطراً وهو مهارة متكاملة. إليك الأجزاء:

• name: بحد أقصى 64 حرفاً، أحرف صغيرة وأرقام وشرطات فقط، ولا يمكن أن تحتوي على الكلمتين claude أو anthropic. في المهارات الشخصية أو الخاصة بالمشروع، هذا هو مجرد اسم العرض. الأمر الذي تكتبه يأتي من اسم المجلد، لذا تستجيب هذه المهارة لـ /nginx-config-changes.
• description: ما تفعله المهارة ومتى تستخدمها، بحد أقصى 1,024 حرفاً. هذا السطر هو الذي يؤدي العمل الفعلي، والقسم التالي مخصص لهذا الغرض فقط.
• المتن: التعليمات، التي يتم تحميلها فقط عند تشغيل المهارة فعلياً.
• reference/: ملفات إضافية يقرؤها الوكيل عند الطلب. اربطها من SKILL.md واجعل الروابط على مستوى عمق واحد، لأن الملف المشار إليه من ملف آخر مشار إليه غالباً ما يُقرأ جزئياً فقط.
• scripts/: ملفات ينفذها الوكيل بدلاً من قراءتها. مخرجاتها فقط هي التي تستهلك من سياق الذاكرة، لذا فإن سكربت من 300 سطر يعتبر غير مكلف.

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

المكان الذي تضع فيه المجلد يحدد من يمكنه الوصول إلى المهارة.

• .claude/skills/<name>/SKILL.md في المستودع: لهذا المشروع فقط، وتنتقل إلى أي شخص يقوم بنسخ المستودع (clone).
• ~/.claude/skills/<name>/SKILL.md: لكل مشروع على جهازك، ولا يراها أحد غيرك.
• <plugin>/skills/<name>/SKILL.md: تُشحن داخل إضافة (plugin)، وتكون متاحة حيثما تم تفعيل تلك الإضافة.

أنشئ مهارة باستخدام mkdir -p .claude/skills/nginx-config-changes واكتب الملف. يراقب Claude Code هذه المجلدات، لذا فإن تعديل مهارة موجودة يسري مفعوله داخل الجلسة الجارية. أما إنشاء مجلد مهارات رئيسي لم يكن موجوداً عند بدء الجلسة فيتطلب إعادة تشغيل، لأنه لم يكن هناك شيء للمراقبة عند بدء الجلسة.

يُعد حقل الوصف السطر الأكثر تأثيراً في الملف

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

اكتب الوصف بصيغة الغائب. عبارة "يختبر ويعيد تحميل nginx بأمان" تعمل بشكل جيد، بينما "يمكنني مساعدتك في nginx" لا تعمل، لأن النص يُدرج في موجه النظام (system prompt)، حيث تُقرأ صيغة المتكلم كأن النموذج يتحدث عن نفسه.

ضمن في الوصف أمرين: ما تفعله المهارة، والشرط الذي تُطبق فيه. ضع حالة الاستخدام المهمة في البداية، لأن Claude Code يقتطع قائمة الإدخالات عند 1,536 حرفاً. يوجد حقل اختياري when_to_use لعبارات التشغيل الإضافية وطلبات الأمثلة، ويُلحق بالوصف تحت نفس حد الطول.

استخدم الكلمات التي ستكتبها فعلياً. description: Helps with nginx لا تطابق شيئاً، لأنه لا أحد يكتب "يساعد في". النسخة أعلاه تسمي /etc/nginx وserver block وreverse proxy وTLS (transport layer security) certificate path، وهي تقريباً مفردات أي طلب يجب أن يُفعّل المهارة.

إليك اختبار الوصف: أعطِ هذا السطر الوحيد لشخص لم يرَ المتن من قبل، مع الطلب الذي توشك على كتابته، واسأله عما إذا كانت المهارة قابلة للتطبيق. إذا لم يستطع التمييز، فلن يستطيع النموذج ذلك أيضاً.

حافظ على صغر حجم المحتوى، لأنّه يبقى ضمن السياق

عند استدعاء مهارة ما، يدخل محتواها المُعالج إلى المحادثة كرسالة واحدة ويبقى هناك طوال الجلسة. لا تعيد Claude Code قراءة الملف في المرات اللاحقة. كل سطر تكتبه هو تكلفة تدفعها طوال الجلسة، وليس لإجابة واحدة فقط.

توصي Anthropic بإبقاء SKILL.md تحت 500 سطر ونقل التفاصيل إلى ملفات منفصلة. يوضح الضغط سبب عدم تعسفية هذا الرقم. عندما يتم تلخيص المحادثة لتوفير مساحة في السياق، تعيد Claude Code إرفاق أحدث استدعاء لكل مهارة، وتحتفظ بأول 5,000 رمز (token) فقط من كل منها، وتملأ ميزانية مجمعة قدرها 25,000 رمز بدءاً من المهارة التي استُدعيت مؤخراً. المهارة الطويلة يتم قطعها في منتصفها. والمهارات الطويلة المتعددة تدفع بعضها البعض للخروج تماماً.

لذا اكتب فقط ما لا يعرفه النموذج مسبقاً. هو يعرف ماهية nginx وما يفعله الـreverse proxy. لكنه لا يعرف قاعدتك الخاصة بشأن reload مقابل restart، وهذه القاعدة هي السبب الوحيد لوجود هذا الملف.

إذا كانت المهارة تطلب من الوكيل تشغيل سكربت مجمّع، سمِّ المسار بـ ${CLAUDE_SKILL_DIR} ليتم حله أينما تم تثبيت المهارة، وقم بالموافقة المسبقة على نفس الأمر حتى لا يتوقف التشغيل عند مطالبة إذن.

---
name: nginx-config-changes
description: Tests and reloads nginx safely after a config edit. Use when editing files under /etc/nginx, adding a server block or a reverse proxy, or changing a TLS certificate path.
allowed-tools: Bash(${CLAUDE_SKILL_DIR}/scripts/check-and-reload.sh *)
---

يغطي المنح الجولة التي استدعت المهارة ويتم مسحه عند إرسال رسالتك التالية، لذا فهو لا يتحول بهدوء إلى إذن دائم.

كيفية إثبات عمل المهارة

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

1. ابدأ جلسة جديدة باستخدام claude في المشروع.
2. اكتب الطلب بالطريقة التي تستخدمها في يوم عمل عادي، بكلماتك الخاصة، دون ذكر اسم المهارة.
3. راقب عملية الاستدعاء. إذا لم تعمل المهارة، أصلح الوصف؛ فالمشكلة ليست في المتن بعد.
4. استدعِ المهارة يدوياً باستخدام /nginx-config-changes كإجراء تحكم. السلوك الصحيح عند الاستدعاء اليدوي والسلوك الخاطئ عند الطلب العادي يؤكدان وجود مشكلة في المشغّل (trigger) وليس في التعليمات.
5. نفّذ نفس الطلب مع إيقاف المهارة وقارن بين الإجابتين. في قائمة /skills، حدد المهارة، واضغط على Space لتغيير حالتها إلى off، ثم اضغط Enter للحفظ. هذا يكتب إدخال skillOverrides في .claude/settings.local.json، والضغط على Space مرة أخرى يعيدها إلى حالة on عند الانتهاء.
6. اكتب بضعة طلبات لا ينبغي أن تشغّل المهارة، وتأكد من أنها تظل خاملة في تلك الحالات.

لأتمتة هذه الحلقة، ثبّت إضافة skill-creator من المتجر الرسمي.

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

إذا أظهر مخرج التثبيت Run /reload-plugins to activate.، نفّذ ذلك الأمر. ثم اطلب من Claude تقييم مهارتك بالاسم. تخزن الإضافة حالات الاختبار في evals/evals.json داخل دليل المهارة وتنفذ كل حالة في وكيل فرعي خاص بها، بحيث يبدأ كل تشغيل بسياق نظيف. بعد ذلك، تكتب مقارنة بين النتائج مع المهارة وبدونها، وهو الرقم الدقيق: تحسن معدل النجاح مقاساً مقابل الرموز (tokens) والوقت الذي تستهلكه المهارة.

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

نمط الفشل: المهارة لا تعمل مطلقاً

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

• الوصف يوضح ما تفعله المهارة لكنه لا يذكر متى يجب استخدامها، لذا لا يوجد شيء في طلبك يطابقها.
• الوصف يتجنب الكلمات التي تكتبها. إذا قلت "nginx"، يجب أن يحتوي الوصف على كلمة nginx.
• تم ضبط disable-model-invocation: true في البيانات الوصفية (frontmatter). هذا يبقي الوصف خارج سياق النموذج تماماً، ويجعل المهارة قابلة للاستدعاء فقط من قبلك باستخدام /name.
• يوجد نمط paths في البيانات الوصفية يحد من التفعيل ليقتصر على الملفات المطابقة، والملف الذي تعمل عليه لا يطابق هذا النمط.
• تقع المهارة في دليل .claude/skills/ متداخل أسفل دليل البداية الخاص بك. يتم تحميل هذه المهارات فقط بعد أن يقوم الوكيل بقراءة أو تعديل ملف داخل ذلك الدليل الفرعي، لذا تظل المهارة غير متاحة حتى ذلك الحين.

نمط الفشل: تفعيل المهارة بشكل مستمر

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

قم بتضييق نطاق الوصف ليقتصر على الحالة التي تهمك فعلياً، وحدد الملفات أو الأوامر التي تغطيها المهارة. أضف نمط paths (glob) عندما تنطبق المهارة على ملفات معينة فقط. بالنسبة لأي إجراء له آثار جانبية، مثل النشر أو الالتزام (commit)، اضبط disable-model-invocation: true وقم باستدعائها بنفسك باستخدام /name، حتى لا يقرر الوكيل من تلقاء نفسه أن الوقت الحالي مناسب للنشر.

نمط الفشل: المهارة تنتمي إلى ملف القواعد الخاص بك

يتم تحميل ملف القواعد، مثل CLAUDE.md أو AGENTS.md، في بداية كل جلسة ويُطبّق على كل مهمة. أما متن المهارة فلا يُحمّل إلا عند تفعيل المهارة ذاتها. التكرار هو المعيار الأساسي لاتخاذ القرار. الحقيقة التي تنطبق على كل مهمة في المستودع، مثل مدير الحزم الذي تستخدمه، يجب أن توضع في ملف القواعد. أما الإجراء الذي ينطبق على جزء صغير من المهام، مثل قاعدة nginx المذكورة أعلاه، فيجب أن يوضع في مهارة، حيث لا يستهلك أي موارد في الأيام التي لا يقوم فيها أحد بتعديل nginx.

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

شارك المهارة بعد أن تثبت جدواها

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

ملاحظة حول القابلية للنقل: يقبل Claude Code قائمة طويلة من حقول الترويسة (frontmatter)، لكن معيار مهارات الوكيل (Agent Skills) يسمح بستة حقول فقط: name وdescription وlicense وcompatibility وmetadata وallowed-tools. إذا قمت برفع مهارة إلى claude.ai أو حزمتها من أجل Skills API مع وجود أي حقول أخرى في الترويسة، فستفشل العملية تماماً بدلاً من تجاهل الحقول الزائدة:

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

التزم بهذه الحقول الستة وسيعمل الملف نفسه في Claude Code وفي أي نظام آخر يقرأ هذا المعيار. المكان الذي يتم فيه تحميل الملف هو الذي يحدد ما يمكنه فعله، لأن Cowork يعمل داخل بيئة معزولة (sandbox) من Anthropic بينما يعمل Claude Code على جهازك الخاص أو خادم VPS، لذا فإن مهارة nginx المذكورة أعلاه تستحق النقل إلى جهاز زميلك، لكنها عديمة الفائدة في بيئة معزولة لا يمكنها الوصول إلى الخادم. كتابة التعليمات نفسها بحيث تظل فعالة عند الانتقال إلى نموذج آخر هي مهمة منفصلة، وقد غطيناها في كتابة مهارات تعمل مع أي نموذج.

FAQ

ما هو الطول المناسب لملف SKILL.md؟

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

لماذا لا يتم تفعيل مهارتي أبداً؟

الوصف هو السبب المعتاد، لأنه الجزء الوحيد من المهارة الموجود في السياق عندما يتخذ النموذج قراره. تأكد من أنه يوضح متى يجب استخدام المهارة، وليس فقط ما تفعله، وأنه يحتوي على الكلمات التي تكتبها فعلياً في طلباتك. إذا كان الوصف يبدو صحيحاً، فتحقق من البيانات الوصفية (frontmatter) بحثاً عن disable-model-invocation: true، التي تخفي المهارة عن النموذج تماماً، وعن نمط paths الذي يقصرها على ملفات لا تعمل عليها. المهارة الموجودة في دليل .claude/skills/ متداخل أسفل دليل البدء الخاص بك هي سبب آخر: فهي لا تُحمّل إلا بعد أن يقرأ الوكيل ملفاً أو يعدله في ذلك الدليل الفرعي.

هل يجب أن تكون هذه مهارة أم سطراً في ملف القواعد الخاص بي؟

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

كيف أعرف أن المهارة ساعدت فعلاً؟

قارنها مقابل خط أساس. اجمع بضع طلبات حقيقية، ونفذ كلاً منها في جلسة جديدة مع توفر المهارة، ثم نفذها مرة أخرى مع إيقاف المهارة من قائمة /skills، واقرأ كلتا الإجابتين جنباً إلى جنب. الجلسة الجديدة مهمة لأن المحادثة التي كتبت فيها المهارة لا تزال تحتوي على تفسيراتك، مما يجعل الملف غير المكتمل يبدو مكتملاً. تقوم إضافة skill-creator بتشغيل هذه المقارنة نيابة عنك وتقدم تقريراً عن معدل النجاح بجوار تكلفة الرموز (tokens).

هل يمكنني استخدام نفس ملف SKILL.md مع وكيل مختلف؟

نعم، طالما بقيت ضمن الحقول التي يحددها معيار Agent Skills، وهي: name، description، license، compatibility، metadata، وallowed-tools. يقبل Claude Code العديد من الحقول الإضافية، كما يدعم ميزات في المتن مثل حقن أوامر shell التي لا تشغلها أدوات أخرى. سيؤدي تحميل مهارة تحتوي على حقل خارج المعيار إلى فشل العملية مع ظهور خطأ صريح يسرد الخصائص المسموح بها، لذا قرر مبكراً ما إذا كانت المهارة مخصصة للبقاء في Claude Code أو للنقل.