مهارات Claude Code: كيف تعمل Skills وملف SKILL.md ومتى يحمّلها الوكيل

ما هي Skills في Claude Code

المهارة (Skill) مجلد يحوي ملف SKILL.md، وفيه تعليمات لنوع محدد من المهام: كيف تنشر المشروع، وكيف تجري مراجعة، وكيف تصدر إصدارًا. يعلم الوكيل بوجود المهارة منذ بداية الجلسة، لكنه لا يقرأها كاملة إلا عندما تتطلب المهمة ذلك فعلًا.

تحل Claude Code skills مشكلة يعرفها كل من يحتفظ بملف CLAUDE.md لفترة طويلة: الملف يتضخم. إجراء النشر من 80 سطرًا يُحتاج مرة في الأسبوع، لكنه يشغل مكانًا في السياق في كل جلسة، حتى عند تصحيح خطأ مطبعي في README. المهارة تنقل مثل هذه الإجراءات من السياق الدائم وتستدعيها عند الحاجة.

مم تتكون المهارة

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

.claude/skills/deploy/SKILL.md      # مهارة المشروع، مشتركة للفريق عبر git
~/.claude/skills/review/SKILL.md    # مهارة شخصية، متاحة في كل المشاريع

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

.claude/skills/deploy/
├── SKILL.md           # التعليمات الرئيسية
├── checklist.md       # قائمة تحقق مفصلة، تُقرأ عند الإشارة إليها
└── rollback.sh        # سكربت التراجع

الترويسة: name وdescription

يبدأ الملف بكتلة YAML بين سطري ---. الحقلان الأهم هما name وهو الاسم القصير للمهارة، وdescription وهو وصف ما تفعله المهارة ومتى تُستخدم.

---
name: deploy
description: نشر الموقع على الاستضافة عبر FTP. استخدمها عندما تحتاج إلى رفع التغييرات إلى الخادم أو فحص الفروقات معه أو التراجع عن النشر.
---

# النشر

1. أولًا تشغيل تجريبي: ./deploy.sh -n.
2. تحقق من قائمة الملفات: لا يجب أن تحوي أسرارًا أو سكربتات اختبار.
3. ارفع: ./deploy.sh.
4. افتح الصفحات المعدَّلة وتأكد أنها تعيد 200.

التراجع — انظر rollback.sh في هذا المجلد.

ما يلي الترويسة نص Markdown عادي: خطوات وأوامر وقيود وروابط إلى ملفات مجاورة. اكتبه كما تكتب تعليمات لزميل جديد يؤدي هذه المهمة للمرة الأولى.

متى يحمّل الوكيل المهارة

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

القاعدة العملية: المهارة تُفعَّل بحسب الوصف. الوكيل لا يرى جسم المهارة قبل أن يقرر فتحها. إذا كُتب في description «مهارة مساعدة» فلن يفهم الوكيل متى يحتاجها. أما إذا كُتب «نشر على الاستضافة؛ استخدمها عندما تحتاج إلى رفع التغييرات إلى الخادم أو التراجع عن النشر» فسيفهم.

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

كيف تكتب description حتى تُفعَّل المهارة

• ما الذي تفعله — بعبارة واحدة بفعل واضح: «نشر الموقع»، «مراجعة التغييرات قبل الـ commit».
• متى تُستخدم — اذكر الصيغ التي يطلب بها المستخدم المهمة فعلًا: «ارفعها إلى الخادم»، «انشرها»، «تراجع عن النشر».
• متى لا تُستخدم إذا كانت المهارة تُخلط بسهولة بجارتها: «ليست لنشر البوت، للموقع فقط».
• تجنب العبارات العامة مثل «مهارة مفيدة» و«تساعد في العمل» لأنها لا تحمل أي إشارة.

الكشف التدريجي

تُبنى المهارات على مبدأ الكشف التدريجي (progressive disclosure): تُقدَّم المعلومات في طبقات، وتُحمَّل كل طبقة تالية عند الحاجة فقط.

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

Skills وCLAUDE.md والأوامر المائلة: الفرق

كل هذه الآليات الثلاث تمرر تعليمات للوكيل، لكن في لحظات مختلفة وبكلفة مختلفة على السياق.

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

لا تنقل الممنوعات الصارمة إلى المهارة. قد لا تُحمَّل المهارة أصلًا، أما القاعدة «لا تُرسل الأسرار إلى المستودع» فيجب أن تسري دائمًا. هذه الثوابت تبقى في CLAUDE.md وتُدعَّم بالآلية كلما أمكن: بالهوكس، وصلاحيات الوصول، والفحوص في CI.

كيف تنشئ skill لـ Claude Code: خطوة بخطوة

1. ابحث عن إجراء متكرر. علامة جيدة أنك شرحت للوكيل الشيء نفسه ثلاث مرات، أو أن في CLAUDE.md قسمًا لا يُحتاج إلا في مهمة من عشر.
2. أنشئ المجلد .claude/skills/<الاسم>/ وداخله ملف SKILL.md.
3. اكتب الترويسة بـ name وdescription يوضح فيها متى تُطبَّق المهارة.
4. صف الخطوات بأوامر محددة ومعايير الجاهزية: ما الذي يجب فحصه، وأي نتيجة تُعد نجاحًا.
5. انقل الأجزاء الطويلة إلى ملفات مجاورة، وأشر إليها من النص الرئيسي.
6. أزل التكرار من CLAUDE.md وأبقِ سطرًا واحدًا يشير إلى المهارة: «النشر — مهارة deploy».
7. تحقق: في جلسة جديدة اطلب المهمة بكلماتك دون ذكر اسم المهارة، وانظر هل التقطها الوكيل. إن لم يفعل فأعد كتابة الوصف.

أمثلة على المهارات

مهارة النشر

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

مهارة المراجعة

---
name: review
description: مراجعة التغييرات الحالية قبل الـ commit. استخدمها عندما يُطلب فحص الـ diff أو البحث عن أخطاء في التعديلات أو تجهيز التغييرات للـ commit.
---

# مراجعة التغييرات

1. احصل على الفرق: git diff وgit diff --staged.
2. لكل ملف معدَّل تحقق من:
   - أن المدخلات من المستخدم مُعقَّمة عند عرضها؛
   - أن استعلامات SQL معاملية (parameterized)؛
   - أنه لا توجد مخرجات تصحيح أو ملفات مؤقتة.
3. شغّل الاختبارات والمدقق في المشروع (الأوامر في CLAUDE.md).
4. التقرير: قائمة المشكلات مع الملف والسطر، من الخطيرة إلى الصغيرة.
   وإذا لم توجد مشكلات فقل ذلك صراحةً دون اختلاق ملاحظات.

مثل هذه المهارة تحوّل عبارة «انظر هل كل شيء سليم» إلى فحص قابل للتكرار بالبنود نفسها في كل مرة.

مهارة إنهاء الجلسة

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

الأخطاء الشائعة

• وصف غامض. المهارة موجودة لكن الوكيل لا يستدعيها. الحل إعادة كتابة description بمحفزات محددة.
• مهارة بحجم بحث. نُقل القسم القديم كله، 400 سطر، إلى SKILL.md. مشكلة السياق المتضخم عادت، لكن لاحقًا. أبقِ النص الرئيسي قصيرًا، والتفاصيل في ملفات مجاورة.
• تكرار مع CLAUDE.md. الإجراء نفسه مكتوب في موضعين فيتباعدان مع الوقت. يجب أن يكون مصدر الحقيقة واحدًا.
• مهارات متداخلة. مهارتان بوصفين متشابهين، فيختار الوكيل بينهما عشوائيًا. افصل بينهما بعبارات صريحة «استخدم / لا تستخدم».
• أوامر قديمة. أُعيدت تسمية سكربت والمهارة ما زالت تشير إلى الاسم القديم. المهارة جزء من كود المشروع: عدّلها في الـ commit نفسه الذي يغيّر الإجراء.

كيف تعرف أن قسمًا يستحق أن يصبح مهارة

من المفيد أن تمر دوريًا على CLAUDE.md وتسأل عن كل قسم: في أي نسبة من المهام الاعتيادية يُحتاج فعلًا؟ إن كان مطلوبًا في معظم المهام فمكانه صحيح. وإن كان مطلوبًا في مهمة من عشر فهو مرشح لأن يصبح مهارة.

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

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

الخلاصة

Claude Code skills طريقة لحفظ الإجراءات بجانب المشروع دون دفع ثمنها من السياق في كل جلسة. وصف المهارة مرئي دائمًا، والنص يُحمَّل عند الحاجة، والملفات المساعدة لاحقًا. يبقى في CLAUDE.md خريطة المشروع والقواعد الصارمة، وتذهب إلى المهارات عمليات النشر والمراجعة والإصدار وغيرها من المهام ذات النوع المحدد. بنية الملفات التعليمية والكشف التدريجي للسياق شُرحت عمليًا في الدورة عن هندسة الهارنس.