مهارات Claude Code صامتة؟ إليك الحل الحقيقي

مهارات Claude Code صامتة؟ إليك الحل الحقيقي

أُدير فريق تطوير يعيش داخل Claude Code منذ ما يقرب من عام. وأعني "يعيش" فعلياً، ليس "جرّبناه لمدة سباق" فقط. فأداة التكامل المستمر (CI) لدينا تعتمد عليه، وقوالب طلبات السحب (PR) هي في الحقيقة مطالبات (prompts) خاصة بـ Claude. في مرحلة ما من هذه الرحلة، طمعت. بنيت مجموعة مهارات مخصصة لفريقي: `code-review` و`debug-protocol` و`team-conventions`. كانت موجودة في `.claude/skills/`، تبدو رائعة، وتحوي كل ما تحلم به من مقدمة YAML — لكن في الأسابيع الأولى، بقيت حبراً على ورق. صامتة. مهملة. مثل جهاز إنذار حريق لا يعمل إلا بعد أن يشتعل الحريق فعلاً.

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

فخ "المهارة التي لم تنطلق"

لأي شخص لم ينظر بعد في هاوية إعدادات مهارات Claude Code، إليك النسخة المختصرة: المهارات عبارة عن مجلدات داخل `.claude/skills//SKILL.md`. كل واحدة تحتوي على القليل من مقدمة YAML — اسم ووصف — متبوعة بالتعليمات الفعلية التي يجب أن يتبعها النموذج عند تفعيل المهارة.

```markdown
---
name: code-reivew
description: Use when the user asks for a code review.
---
```

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

قضينا ثلاثة أسابيع نلوم Claude ونلوم الـ API ونلوم أطوار القمر. ثم قرأنا فعلاً توثيق المهارات الرسمي على [docs.anthropic.com/en/docs/claude-code/skills](https://docs.anthropic.com/en/docs/claude-code/skills) وأدركنا شيئاً غير مريح: النموذج ليس كسولاً، بل حرفي فقط. لا يمكنه تفعيل مهارة إلا إذا *اعترف* بها كشيء ذي صلة من الوصف. وأوصافنا كانت سيئة للغاية.

المشكلة الحقيقية: عدم تطابق الوصف

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

إذا كان وصلك ضيقاً جداً، أو غامضاً جداً، أو مركزاً على الكلمات المفتاحية، سيخطئه Claude. وإذا تصادم وصلك مع مهارة أخرى أو أمر مدمج، سيختار Claude الخطأ. الكود في ملف SKILL.md ليس المشكلة أبداً. البيانات الوصفية (metadata) هي المشكلة.

إليك أكبر ثلاث طرق تنخدع بها الفرق الحقيقية.

السيناريو الأول: مهارة مراجعة الكود التي بقيت نائمة

كتبت مهارة `code-review` لدينا بأكثر وصف وضوحاً في العالم: *"استخدمها عندما يطلب المستخدم مراجعة كود."* بسيط، أليس كذلك؟ خطأ.

مطورونا لم يقولوا أبداً "مراجعة كود". كانوا يقولون:

- "هل يمكنك فحص الـ PR الخاص بي؟"
- "انظر إلى هذا الـ diff، شيء ما غريب."
- "راجع هذا قبل أن أشحنه."
- "هل هذا مبالغ في هندسته؟"

خمّن أي واحدة منها فعّلت المهارة؟ لا شيء. أجاب Claude على كل هذه مباشرة دون استدعاء المهارة، لأن عبارة "مراجعة كود" لم تظهر في الرسالة إطلاقاً. كان الحل محرجاً في بساطته. أعدنا كتابة الوصف ليكون دلالياً (semantic) وليس حرفياً:

```yaml
description: >-
Use for reviewing code changes, pull requests, diffs, or merge requests.
Trigger on phrases like "review this PR", "check my diff", "sanity-check
this code", "is this good to merge", or "look at these changes".
Not for general debugging or explaining code.
```

أضفنا أيضاً جملة "ليس لـ" (Not for). هذا التغيير الوحيد جعل المهارة تنطلق بنسبة 80% أكثر تقريباً. مهارات Claude Code هي في الأساس هندسة مطالبات — والمطالبة هي الوصف.

السيناريو الثاني: بروتوكول التصحيح الذي اختفى

كان من المفترض أن تكون مهارة `debug-protocol` بطلة الفريق. عملية منظمة خطوة بخطوة لإعادة إنتاج الأخطاء، وفحص السجلات، وتفحص الحالة، واقتراح الإصلاحات. كانت جميلة. ولم تنطلق أبداً.

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

تعلمنا درسين من هذا:

1. **أعطِ المهارات أسماء فريدة ومحددة.** `debug-protocol` اسم عام. `sentry-repro-protocol` أو `memory-leak-hunt` كانا سيكونان أفضل. الأسماء العامة تُسحق بالنوايا العامة.
2. **استخدم التجاوز اليدوي.** في Claude Code، يمكنك دائماً كتابة `/debug-protocol` لإجبار المهارة على العمل. أضفنا هذا إلى اتفاقيات الفريق، وفجأة لم تكن المهارة ميتة — كانت فقط بحاجة إلى دعوة مباشرة.

لكن الفكرة الأعمق هنا: النموذج اختار المهارة الخاطئة لأن *نحن* من صممنا التصادم. إذا كان لديك مهارتان تبدوان متشابهتين، سيخمّن Claude. اجعل الأوصاف يستبعد بعضها بعضاً. أخبر Claude صراحةً: "استخدم هذه بدلاً من سلوك التصحيح العام عندما تتعلق المشكلة بسجلات الخادم."

السيناريو الثالث: مهارة اتفاقيات الفريق التي نسيت كل شيء

جاء الفشل الأغرب من مهارة `team-conventions`. كانت تحمل قواعد رسائل الالتزام (commit messages)، وتسمية الفروع، وأوصاف طلبات السحب. عملت بشكل جميل في بداية الجلسة ثم توقفت تقريباً عند الرسالة رقم 20. افترضنا أن النموذج "ينسى". لم تكن مشكلة ذاكرة — كانت مشكلة سياق.

Claude Code يضخ كل أوصاف المهارات في المطالبة النظامية. الأوصاف الطويلة تلتهم السياق. وعندما يتراكم الحديث، يبدأ النظام بضغط المطالبة النظامية أو اقتطاعها لصنع مساحة. وصف `team-conventions` لدينا كان جداراً من النص — ثلاث فقرات من الخطاب المؤسسي الرنان. كان أول ما يُلقى خارج النافذة عندما يضيق السياق.

الحل كان تقليص الوصف إلى جملتين أو ثلاث، ونقل القواعد الفعلية إلى ملف مرجعي داخل مجلد المهارة. الآن الوصف مجرد لافتة: *"استخدمها لرسائل الالتزام، وتسمية الفروع، واتفاقيات الـ PR. القواعد الكاملة في convention.md."* النموذج قادر على حمل هذا القدر، وعندما تنطلق المهارة يقرأ الملف الكامل. نقلنا أيضاً القواعد غير المرتبطة بالمهارات إلى ملف `CLAUDE.md` لذاكرة المشروع، الذي يُحمَّل بشكل أكثر موثوقية لتعليمات الفريق العامة.

إصلاحات عملية تبدأ بها اليوم

بعد أسابيع من الألم، ها هي القائمة التي تمنيت لو أعطاني إياها أحد في اليوم الأول.

عامل الوصف كاستعلام بحث

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

أبقِ ملفات المهارات خفيفة

ملف مهارة طوله 500 سطر عبء ومسؤولية. يلتهم السياق، ويُقتطع، ويصبح غير موثوق. أبقِ SKILL.md مركزاً على *قرار* متى تنطلق. ادفع التفاصيل الثقيلة إلى ملفات مساعدة — `prompt.md`، `criteria.md`، `checklist.md` — يقرؤها Claude فقط بعد تفعيل المهارة.

أضف أمثلة سلبية

يبدو هذا غير بديهي، لكنه يعمل. في الوصف، حدد صراحةً ما ليست المهارة *من أجله*. اكتب: *"ليس للنقاشات المعمارية العامة. ليس لأسئلة الصياغة البرمجية (syntax)."* هذا يقلل الإيجابيات الكاذبة ويساعد النموذج أيضاً على التمييز بين المهارات المتشابهة. الأمثلة السلبية هي أشد الأدوات حدّة في الصندوق.

استخدم `/` للتجاوز اليدوي

مهما كانت بياناتك الوصفية جيدة، ستأتي لحظة يفشل فيها الاكتشاف التلقائي. درّب فريقك على كتابة `/skill-name` عندما يحتاجون إلى تفعيل قسري. هذا ليس فشلاً — إنه حل احتياطي. أذكى الفرق تعامل التفعيل التلقائي للمهارات كرفاهية وليست اعتماداً.

صححه كما تصحح أي كود آخر

Claude Code لديه علم `--debug`. استخدمه. افحص المطالبة النظامية التي تُجمَّع في بداية الجلسة وتأكد من أن أوصاف مهاراتك موجودة فعلاً فيها. يبدو هذا بديهياً، لكننا اكتشفنا أن فاصلة زائدة في أحد كتل مقدمة YAML كانت تبطل الملف بأكمله بصمت. المهارة لم تكن تُحمَّل أبداً. ليس بسبب مطابقة النوايا — بل بسبب خطأ تحليل (parse error). مخرج التصحيح التقطه في عشر ثوانٍ.

اختبر عبر صياغات مختلفة

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

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

لماذا تعمل مهارتي في جلسة جديدة لكنها تتوقف عن العمل لاحقاً؟

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

هل من الأفضل استخدام كلمات مفتاحية أم لغة طبيعية في أوصاف المهارات؟

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

هل يمكن لمهارة مخصصة تجاوز سلوك Claude Code المدمج؟

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

كيف أعرف أن ملف المهارة يُحمَّل أصلاً؟

شغّل `claude --debug` وافحص المخرجات. يجب أن ترى مهاراتك مذكورة في تجميع المطالبة النظامية. إذا لم تكن مذكورة، تحقق من مقدمة YAML وبنية المجلد واسم الملف. مجلد مهارات بدون `SKILL.md` صالح هو مجرد ديكور.

الخلاصة

إليك الحقيقة غير المريحة: عندما لا تنطلق مهارة، فإن ملف المهارة ليس المشكلة أبداً. المشكلة هي كيف ترجمت النية البشرية — "راجع عملي، اتبع قواعدنا، أصلح هذا الخطأ بالطريقة التي اتفقنا عليها" — إلى البيانات الوصفية التي يقرؤها Claude فعلاً. الأمر لا يتعلق بكتابة كود أفضل. إنه يتعلق بكتابة *لافتات* أفضل.

إذا كنت محبطاً من مهارات صامتة، لا تعِد كتابة الماركداون من الصفر. أعد كتابة أوصافك. أضف أمثلة حقيقية. أضف استثناءات. أبقِ الملف خفيفاً. وعندما تفشل كل الحلول، اكتب `/skill-name` مباشرة وامضِ في يومك.

المهارة ليست معطوبة. وصدق أو لا تصدق، Claude أيضاً ليس معطوباً. نحن فقط نسينا أن النموذج يحتاج إلى دعوة للحفلة، لا مجرد إيماءة غامضة عبر الغرفة.