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

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

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

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

تضع إرشادات التأليف الخاصة بـ 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 سطر يعتبر غير مكلف.

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

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

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

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

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

اكتب الوصف بصيغة الغائب. عبارة "Tests and reloads nginx safely" تعمل بشكل جيد. أما "I can help you with nginx" فلا تعمل، لأن النص يُدرج في موجه النظام (system prompt)، حيث تُقرأ صيغة المتكلم كأن النموذج يتحدث عن نفسه.

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

استخدم الكلمات التي ستكتبها فعلياً. description: Helps with nginx لا تطابق شيئاً، لأنه لا أحد يكتب "helps with". النسخة أعلاه تسمي /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) والوقت الذي تستهلكه المهارة.

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

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

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

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

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

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

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

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

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

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

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

ملاحظة حول القابلية للنقل: يقبل 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 وفي أي أداة أخرى تدعم هذا المعيار. أما كتابة التعليمات نفسها بحيث تظل فعالة عند الانتقال إلى نموذج آخر فهي مهمة منفصلة، وقد غطيناها في كتابة مهارات تعمل مع أي نموذج.

FAQ

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

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

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

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

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

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

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

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

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

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