عندما نشر آدي عثماني — قائد هندسة Google Chrome الذي علّم جيلاً كاملاً من المطورين أنماط تصميم جافاسكريبت — مكتبة مفتوحة المصدر تضم عشرات المهارات الهندسية الإنتاجية هذا الشهر، تجاوزت 14,000 نجمة على GitHub خلال أيام. السبب بسيط: معظم مهارات الوكلاء المنتشرة على GitHub هي تجارب نصف مكتملة لشخص ما. أما مهاراته فقد صاغها شخص شحن برمجيات على نطاق واسع. تلك الفجوة — بين مهارة تعمل ومهارة تهدر نافذة سياق بحجم 200,000 رمز — هي موضوع هذا الدليل.
إذا كنت تأمل أن كومة ملفات .md المبعثرة لديك تساعد وكيل البرمجة بهدوء، فالحقيقة المزعجة أنها على الأرجح لا تفعل. إليك كيف تكتب مهارات تُحدث فرقاً حقيقياً.
ما هي المهارة فعلاً
مهارة الوكيل هي مجلد يقع في مركزه ملف SKILL.md. يتكوّن الملف من جزأين: بيانات وصفية بصيغة YAML (حقل name وحقل description)، ومتن بصيغة markdown يحتوي على تعليمات خطوة بخطوة. اختيارياً، يضم المجلد أيضاً مستندات مرجعية ونصوصاً برمجية قابلة للتنفيذ تُحمّل فقط عند الحاجة إليها.
بدأت الصيغة في Anthropic وأصبحت معياراً مفتوحاً بحكم الأمر الواقع. نفس الملفات تعمل الآن في Claude Code وCursor وGitHub Copilot وCodex CLI وGemini CLI وWindsurf وOpenCode — أي وكيل يقرأ تعليمات markdown. اكتبها مرة، وشغّلها في كل مكان. هذه القابلية للنقل هي بالضبط سبب أهمية إتقان الكتابة عبر كل أداة يستخدمها فريقك.
الكشف التدريجي: الفكرة الجوهرية
المفهوم الأهم على الإطلاق هو الكشف التدريجي. عند بدء الجلسة، يقرأ وكيلك فقط حقلي name وdescription لكل مهارة مثبّتة — نحو 100 رمز لكل منها. ولا يقرأ متن SKILL.md كاملاً إلا حين تصبح المهارة ذات صلة، ولا يقرأ الملفات المرجعية المرفقة إلا حين تتطلبها مهمة محددة.
هذا ما يتيح لك تثبيت 100 مهارة دون إغراق نافذة السياق. وجدت دراسة من Bosch Research وجامعة Carnegie Mellon في فبراير 2026 حلّلت أكثر من 40,000 مهارة منشورة أن متوسط متن المهارة يبلغ نحو 1,400 رمز — صغير ومركّز ويُحمّل عند الطلب. البنية قائمة على نظام الملفات: يمكن تنفيذ النصوص البرمجية عبر bash دون تحميل مصدرها إلى السياق إطلاقاً، فلا يكلّف سوى الناتج رموزاً.
القواعد العملية المترتبة على ذلك:
- أبقِ متن
SKILL.mdتحت 500 سطر. إن تجاوزها، قسّمه. - أبقِ الروابط المرجعية على مستوى واحد من
SKILL.md. الوكلاء يعاينون الملفات المتداخلة بعمق جزئياً وينتهي بهم الأمر بمعلومات ناقصة. - للملفات المرجعية التي تتجاوز 100 سطر، أضف فهرس محتويات في الأعلى ليرى الوكيل النطاق الكامل حتى عند القراءة الجزئية.
تشريح مهارة ناجحة
إليك الحد الأدنى من البيانات الوصفية التي يحتاجها كل ملف SKILL.md:
---
name: processing-pdfs
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDFs or document extraction.
---حقلان ينجزان قدراً هائلاً من العمل. يجب أن يكون name بأحرف لاتينية صغيرة وأرقام وشرطات فقط، وأقل من 64 حرفاً — وصيغة المصدر الفعلية مثل processing-pdfs أو testing-code هي الأفضل. أما description فمحدود بـ 1,024 حرفاً وهو أهم سطر في الملف بأكمله، لأن الوكيل يستخدمه للاختيار بين عشرات المهارات المحتملة.
اكتب الأوصاف بصيغة الغائب واملأها بكلٍّ من ماذا تفعل المهارة ومتى تُستخدم:
# جيد — محدد ويتضمن محفزات
description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing spreadsheets or .xlsx files.
# سيئ — غامض وبلا محفزات
description: Helps with documentsوصف مثل "Helps with documents" لا يمنح الوكيل ما يميّز به. إما ألا يُفعّل أبداً أو يُفعّل في الوقت الخطأ.
وازن بين الحرية والهشاشة
متن المهارة الممتازة يضبط مقدار الحرية الممنوحة للوكيل بحسب هشاشة المهمة. تخيّل الوكيل روبوتاً يسير في طريق:
- حقل مفتوح بمسارات آمنة كثيرة — استخدم حرية عالية. أعطِ توجيهاً عاماً نثرياً وثق بالنموذج. مراجعة الكود مثال جيد: النهج الصحيح يعتمد على السياق.
## عملية مراجعة الكود
1. حلّل بنية الكود وتنظيمه
2. تحقق من الأخطاء المحتملة والحالات الحدّية
3. اقترح تحسينات للقراءة والصيانة
4. تأكد من الالتزام بأعراف المشروع- جسر ضيق بمنحدرات على الجانبين — استخدم حرية منخفضة. أعطِ أمراً دقيقاً وامنع الانحراف عنه. ترحيل قواعد البيانات هو الحالة النموذجية:
## ترحيل قاعدة البيانات
شغّل هذا النص بالضبط:
`python scripts/migrate.py --verify --backup`
لا تعدّل الأمر ولا تضف أي خيارات إضافية.الخطأ في هذه المعايرة هو السبب الأكثر شيوعاً لسوء سلوك المهارات: حرية مفرطة في مهمة هشّة تدعو إلى الارتجال حيث كنت تحتاج الدقة.
حلقات التحقق غير قابلة للتفاوض
تضيف مهارات عثماني طبقة تتخطاها معظم المهارات المنزلية كلياً: تنتهي كل مهارة بـمتطلبات إثبات وجدول مكافحة التبرير — أعذار شائعة قد يسوقها الوكيل لتخطّي خطوة، مقرونة برد موثّق. الفلسفة هي "عملية لا نثر": سير عمل بنقاط تفتيش ومعايير خروج، لا جدار من النص المرجعي.
النمط الذي يحقق أكبر قفزة في الجودة هو حلقة تحقّق-أصلح-كرّر. امنح الوكيل قائمة تحقق ينسخها في رده ويؤشّر عليها، ومدقّقاً يجب أن يجتازه قبل المتابعة:
## عملية تحرير المستند
1. أجرِ تعديلاتك على word/document.xml
2. تحقق فوراً: python ooxml/scripts/validate.py unpacked_dir/
3. إذا فشل التحقق:
- راجع رسالة الخطأ
- أصلح المشكلات
- أعد تشغيل التحقق
4. لا تتابع إلا حين ينجح التحقق
5. أعد البناء واختبر الناتجللعمليات الدفعية أو المدمّرة، اذهب أبعد بنمط خطّط-تحقق-نفّذ: اجعل الوكيل يكتب ملف خطة منظّماً، ويتحقق منه بنص برمجي، ثم يطبّق التغييرات فقط بعد ذلك. تحرير 50 حقلاً في نموذج من جدول بيانات دون هذا يدعو إلى الإشارة إلى حقول غير موجودة؛ ومعه تظهر الأخطاء قبل أن يُمَسّ أي شيء.
ابنِ التقييمات قبل التوثيق
أكبر تحوّل ذهني في الإرشادات الرسمية: اكتب تقييماتك أولاً. شغّل الوكيل على مهام حقيقية دون مهارة، وثّق أين يفشل، ثم ابنِ ثلاثة سيناريوهات اختبار تلتقط تلك الإخفاقات. حدّد خط أساس، واكتب الحد الأدنى من التعليمات اللازمة للنجاح، وكرّر. هذا يضمن أن مهارتك تحل مشكلة فعلية بدل توثيق مشكلة متخيّلة.
أكثر سير عمل فعالية يستخدم نسختين من النموذج. تساعدك "Claude A" في الصياغة والتنقيح؛ و"Claude B" — نسخة جديدة محمّلة بالمهارة — تشغّل مهام حقيقية. تراقب أين تتعثر B، وتعيد التفاصيل إلى A، وتنقّح. النماذج تفهم صيغة المهارة بالفطرة، فلا تحتاج أمراً خاصاً للحصول على بنية جيدة — تحتاج مراقبة حقيقية لكيفية استخدام المهارة.
قائمة فحص قبل النشر
قبل أن تعتمد مهارة، تحقق من:
- أن الوصف محدد ويسمّي محفزات ملموسة.
- أن متن
SKILL.mdتحت 500 سطر؛ والتفاصيل في ملفات منفصلة. - ألا تتسرب معلومات مرتبطة بالزمن — ضع الأنماط المهجورة في قسم "أنماط قديمة".
- أن المصطلحات متسقة (اختر "نقطة نهاية API" ولا تنحرف إلى "رابط" أو "مسار").
- أن المراجع على مستوى واحد والأمثلة ملموسة لا مجرّدة.
- أن النصوص البرمجية تعالج الأخطاء صراحةً بدل إرجاعها للوكيل، وأن الثوابت موثّقة لا أرقاماً سحرية.
- أن حلقات التحقق أو التغذية الراجعة موجودة لأي شيء حسّاس للجودة.
لماذا يهم هذا لفرق منطقة الشرق الأوسط وشمال أفريقيا
لأن المهارات مجرد markdown يعمل عبر كل وكيل رئيسي، فهي تحوّط ضد الارتهان لمزوّد واحد — وهو قلق حقيقي لفرق في تونس والسعودية والمنطقة الأوسع التي تتنقل بين تغيّرات الوصول إلى النماذج وأسعارها. مكتبة مهارات مكتوبة جيداً هي معرفة مؤسسية قابلة للنقل: سير عمل المهندسين الكبار الذي يعتمد عليه فريقك، مُرمّز مرة واحدة وقابل للتشغيل على أي وكيل هو الأسرع أو الأرخص أو الأكثر توفراً هذا الربع. تلك رافعة لن تمنحها كومة .md مبعثرة أبداً.
الخلاصة هي التي جعلت إصدار عثماني يلقى صدى: المهارة ليست مقتطف موجّه تلقيه في مجلد. إنها وحدة صغيرة مختبرة أحادية الغرض من الحكم الهندسي. عاملها كأنها كود إنتاجي — موجزة ومعايَرة ومُتحقَّق منها — وستبدأ وكلاؤك بالتصرف كالمهندسين الكبار الذين أردتهم أن يكونوا.
المصادر: addyosmani/agent-skills على GitHub · أفضل ممارسات كتابة المهارات — وثائق Claude · المهارات تعمل لكن معظم الفرق يبنونها خطأً — O'Reilly Radar