مهارات Claude Code عمليًا: كيف نستخدم SKILL.md والتحكم في الاستدعاء وملف CLAUDE.md أخف

أهم النقاط

مهارة Claude Code (skill) هي مجلد يحتوي على ملف SKILL.md: ترويسة YAML تحدد متى تُستخدم المهارة، تليها تعليمات بصيغة Markdown. ويصبح اسم المجلد هو أمر الشرطة المائلة (slash command).

لا يدخل السياق افتراضيًا إلا وصف المهارة؛ أما متنها فيُحمَّل عندما يكتب أحدهم /skill-name أو عندما يطابق Claude الوصف، لذا لا تكاد المواد المرجعية الطويلة تكلّف شيئًا حتى تُستخدم.

دُمجت الأوامر المخصصة في المهارات: الملف .claude/commands/deploy.md والمهارة .claude/skills/deploy/SKILL.md كلاهما ينشئ الأمر /deploy، وتضيف صيغة المهارة ملفات داعمة والتحكم في من يستدعيها.

الإعداد disable-model-invocation: true يمنع Claude من تشغيل المهارة من تلقاء نفسه، وهو الإعداد الذي نستخدمه لعمليات النشر والـ commits وكل ما له آثار جانبية.

لا يعيد Claude Code قراءة المهارة المستدعاة في الأدوار اللاحقة، وبعد الضغط التلقائي للمحادثة (auto-compaction) لا يحتفظ إلا بأول 5,000 رمز (token) من كل مهارة يعيد إرفاقها، لذا مكان التعليمات الحرجة هو أعلى الملف.

لماذا نقلنا الإجراءات خارج CLAUDE.md؟

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

ما مهارة Claude Code، وما الفرق بينها وبين CLAUDE.md؟

مهارة Claude Code هي مجلد يحتوي على ملف SKILL.md يجمع إجراءً واحدًا أو مجموعة معارف واحدة ليحمّلها Claude عند الحاجة. ترويسة YAML بين علامتي --- تخبر Claude متى تنطبق المهارة، ويحمل متن Markdown التعليمات التي يتبعها Claude عند تشغيلها. تتبع المهارات معيار Agent Skills المفتوح المنشور على agentskills.io، ويضيف Claude Code إليه التحكم في الاستدعاء والتشغيل داخل وكيل فرعي (subagent) وحقن السياق الديناميكي.

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

مهارة نموذجية لدينا هي مجلد مثل .claude/skills/release-notes/ يحتوي على SKILL.md، وملف template.md يحدد صيغة المخرجات، ومجلد scripts/. تضبط الترويسة name: release-notes ووصفًا يبدأ بما تفعله المهارة (صياغة ملاحظات الإصدار من طلبات الدمج منذ آخر وسم) وينتهي بالعبارات التي يكتبها الناس فعلًا (ملاحظات الإصدار، مُدخل في سجل التغييرات، ما الذي شُحن هذا الأسبوع).

أين توجد المهارات، وأيها يفوز عند تعارض الأسماء؟

المهارات الشخصية توجد في ~/.claude/skills/skill-name/SKILL.md وتنطبق على كل المشاريع في جهاز واحد.

مهارات المشروع توجد في .claude/skills/skill-name/SKILL.md وتصل إلى كل من ينسخ المستودع بعد إيداعها (commit).

المهارات المتداخلة توجد في مجلد .claude/skills/ داخل مجلد فرعي وتُحمَّل أول مرة يقرأ فيها Claude ملفًا في ذلك المجلد الفرعي أو يعدّله.

مهارات المؤسسة توجد في مجلد الإعدادات المُدارة وتصل إلى كل مستخدم على الأجهزة التي تديرها المؤسسة.

عندما يعرّف مستويان الاسم نفسه، تتقدم مهارة المؤسسة على الشخصية، والشخصية على مهارة المشروع، وتتقدم المهارة على ملف في .claude/commands/ يحمل الاسم نفسه. ولأن المهارة الشخصية تتقدم على مهارة المشروع، فإن /deploy الشخصي سيحجب /deploy المُودَع في المشروع داخل كل مستودع، لذا يضيف مهندسونا اسم المشروع بادئةً للمهارات الشخصية، مثل projectname-deploy.

كيف نكتب وصفًا للمهارة يطابقه Claude فعلًا؟

حقل description هو ما يحدد إن كانت المهارة ستعمل يومًا دون أن تُكتب يدويًا، لذا نكتبه كاستعلام بحث: ما تفعله المهارة، ثم العبارات التي يقولها الناس فعلًا. يقتطع Claude Code النص المجمّع لحقلي description وwhen_to_use عند 1,536 حرفًا في قائمة المهارات، لذا تأتي حالة الاستخدام الأساسية في الجملة الأولى. وصف مثل «يساعد في الإصدارات» لن يطابق أبدًا سؤال «ما الذي شُحن هذا الأسبوع؟»، أما الوصف الذي يذكر ملاحظات الإصدار وسجل التغييرات وما شُحن فيطابقه.

لقائمة المهارات ميزانيتها الخاصة. يدرج Claude Code دائمًا كل أسماء المهارات، لكن عندما تتجاوز القائمة ميزانيتها من الأحرف، والتي تساوي 1% من نافذة سياق النموذج، يحذف الأوصاف بدءًا من المهارات الأقل استدعاءً. يقدّر الأمر /doctor تكلفة القائمة من السياق، ويرفع الإعداد skillListingBudgetFraction هذه الميزانية.

ترويسة YAML المعطوبة تبدو تمامًا مثل الوصف المبهم: يحمّل Claude Code المتن ببيانات وصفية فارغة، فيظل /skill-name يعمل لكن لا يجد Claude ما يطابقه. والأمر claude plugin validate .claude/skills (في Claude Code v2.1.233 أو أحدث) يكشف الترويسات التي لا يمكن تحليلها.

من يحق له استدعاء المهارة: المطوّر أم Claude؟

افتراضيًا يمكن للمطوّر ولـ Claude استدعاء أي مهارة، ويقيّد ذلك حقلان في الترويسة.

الوضع الافتراضي: يستطيع المطوّر استدعاءها، ويستطيع Claude استدعاءها، والوصف موجود دائمًا في السياق.

disable-model-invocation: true: لا يستدعيها إلا المطوّر، ويبقى وصفها خارج السياق حتى ذلك الحين. نضبطه على كل مهارة لها آثار جانبية: النشر والـ commits والنشر على المنصات والرسائل الصادرة.

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

لذلك لا تستهلك المهارة اليدوية فقط أي جزء من ميزانية القائمة. وإن حاول Claude استدعاءها رغم ذلك، يمنع Claude Code الاستدعاء ويطلب من Claude ألا يعيد تنفيذ الخطوات بطريقة أخرى. تجمع مهارات النشر لدينا بين disable-model-invocation: true وقائمة allowed-tools تمنح موافقة مسبقة لأوامر الاختبار والبناء؛ وهذه الموافقة تسري فقط في الدور الذي استُدعيت فيه المهارة وتُلغى عند إرسال الرسالة التالية.

كيف نُدخل بيانات حية إلى المهارة؟

حقن السياق الديناميكي يشغّل أمر shell قبل أن يرى Claude المهارة، ويستبدل السطر بمخرجات الأمر. السطر المكوّن من علامة تعجب يليها أمر بين علامتي backtick، مثل gh pr diff، هو الطريقة التي تصل بها مهارات المراجعة لدينا ومعها الفروقات الحالية مضمّنة، بدلًا من إنفاق استدعاء أداة لجلبها.

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

الأوامر المحقونة لا تطلب الإذن أبدًا. يفحص Claude Code كل أمر مقابل قواعد الأذونات، وخارج الوضع التلقائي (auto mode) تؤدي أي نتيجة غير السماح إلى إلغاء الاستدعاء، لذا نمنح موافقة مسبقة لكل أمر محقون في allowed-tools.

تصل المعاملات كعناصر نائبة: يحمل $ARGUMENTS سلسلة المعاملات كاملة، وتحمل $0 و$1 وما بعدهما القيم الموضعية مع اقتباس بأسلوب shell. وإضافة context: fork مع agent: Explore تشغّل المهارة داخل وكيل فرعي منفصل لا يرى سجل المحادثة، لذا يجب أن تكون تعليمات المهارة المتفرعة مكتفية بذاتها.

لماذا يتوقف Claude عن اتباع المهارة في منتصف الجلسة؟

يُدرج Claude Code محتوى المهارة المستدعاة في المحادثة مرة واحدة ولا يعيد قراءة SKILL.md في الأدوار اللاحقة. الخطوة لمرة واحدة مثل «شغّل الاختبارات» تُطبَّق مرة واحدة، أما القاعدة الدائمة مثل «شغّل الاختبارات بعد كل تعديل» فتظل سارية.

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

القاعدة التي يجب أن تُطبَّق في كل إجراء مكانها hook وليس مهارة. يعمل hook في Claude Code عند كل حدث مطابق، مثل ما قبل كل تعديل لملف، سواء كان Claude يتبع شيئًا أم لا؛ ويمكن للمهارة أيضًا أن تعرّف hooks في حقل hooks بترويستها، تبقى فعّالة من لحظة الاستدعاء حتى نهاية الجلسة.

متى تكون القاعدة في CLAUDE.md أو في مهارة أو hook أو وكيل فرعي؟

يُحمَّل CLAUDE.md كاملًا في كل جلسة ويحمل الحقائق القصيرة الصحيحة في كل مهمة: الأوامر والأعراف والنطاقات.

تحمّل المهارة وصفها دائمًا ومتنها عند الاستدعاء، وتحمل الإجراءات والمواد المرجعية: النشر وملاحظات الإصدار وأعراف الـ API.

يعمل الـ hook عند الأحداث المطابقة خارج النموذج ويفرض قواعد حتمية: منع تعديل ملفات .env وتشغيل أداة التنسيق.

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

اختبارنا لنقل أي سطر من CLAUDE.md سؤالان. إذا كان حذف السطر لا يهم إلا في نوع واحد من المهام، ينتقل إلى مهارة. وإذا كان تجاهل Claude له مرة واحدة سيسبب ضررًا، يصبح hook. وما يجتاز السؤالين يبقى في CLAUDE.md.

الأسئلة الشائعة

س: هل ما زالت ملفات .claude/commands/ تعمل بعد دمج الأوامر في المهارات؟

ج: نعم. الملف .claude/commands/deploy.md والمهارة .claude/skills/deploy/SKILL.md كلاهما ينشئ /deploy ويقبلان الترويسة نفسها باستثناء name وpaths؛ وعند وجودهما معًا تفوز المهارة. يُفضَّل استخدام صيغة المهارة في العمل الجديد لأن المهارات وحدها تدعم الملفات الداعمة.

س: هل تستهلك مهارة Claude Code رموزًا إن لم يستخدمها أحد؟

ج: وصفها فقط، الموجود في قائمة المهارات كي يعرف Claude بوجودها. يُحمَّل المتن عند الاستدعاء فقط، والمهارة التي تضبط disable-model-invocation: true تُبقي حتى وصفها خارج السياق.

س: هل تُحمَّل المهارات الشخصية في الجلسات السحابية والمهام المجدولة؟

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