كيف تكتب مهارة Claude (Claude Skill): بنية ملف SKILL.md وأمثلة حقيقية

إليك كيف تكتب مهارة Claude (Claude Skill) في جملة واحدة: أنشئ مجلدًا، ضع بداخله ملف SKILL.md، واكتب وصفًا (description) جيدًا بما يكفي ليعرف Claude متى يلجأ إليه. هذه هي الآلية بأكملها. الجزء الذي يحدد فعليًا نجاح مهارتك طوله 1,024 حرفًا، وهو حقل description الذي تستخدمه Anthropic لاختيار مهارتك من بين أكثر من 100 مهارة قد تكون محمّلة. نحن نُشغّل 25 مهارة في الإنتاج ضمن مكتبة مجتمع Techsy، والمهارات التي تفشل نادرًا ما تفشل بسبب تعليماتها. إنها تفشل بسبب ذلك السطر الواحد.

ملخص سريع

لكتابة مهارة Claude: (1) أنشئ مجلدًا يحمل اسم المهارة، (2) أضف ملف SKILL.md يحتوي على ترويسة YAML أمامية (frontmatter) بحقلي name وdescription بالإضافة إلى تعليمات بصيغة Markdown، (3) اكتب الوصف (description) بصيغة الغائب مع كلمات تفعيل واضحة، (4) أبقِ متن الملف أقل من 500 سطر وانقل التفاصيل إلى ملفات مرجعية، و(5) اختبرها بمهام حقيقية قبل أن تثق بها.

ما هي مهارة Claude فعليًا؟

المهارة هي مجلد يحتوي على ملف SKILL.md في جذره. لا شيء آخر مطلوب. يحمل هذا الملف أمرين: بيانات وصفية (metadata) تخبر Claude متى يستخدم المهارة، وتعليمات تخبره كيف ينفّذ المهمة بمجرد تفعيلها.

السبب في بقاء هذا الأمر منخفض التكلفة هو نموذج تحميل تسميه Anthropic الكشف التدريجي (progressive disclosure). عند بدء التشغيل، يقرأ Claude فقط حقلي name وdescription لكل مهارة مثبّتة، أي ما يقارب 100 توكن لكل منها. ولا يقرأ ملف SKILL.md كاملًا إلا عندما يتطابق وصفك مع المهمة المطروحة، ولا يقرأ أي ملفات مرجعية مرفقة إلا عندما تشير إليها التعليمات. بهذا يمكنك إطلاق مهارة كبيرة ومفصّلة دون أن تدفع ثمنها في كل طلب. يمكنك الاطلاع على كتالوج فعلي لهذه المهارات في مكتبة المهارات لدينا.

هيكل SKILL.md الذي يمكنك نسخه

تبدأ كل مهارة بالشكل نفسه. إليك النسخة الأدنى التي تعمل:

---
name: reviewing-pull-requests
description: Reviews pull request diffs for bugs, security issues, and style. Use when the user asks for a code review, mentions a PR, or shares a diff.
---

# Reviewing Pull Requests

1. Read the diff and summarize what changed.
2. Flag likely bugs and edge cases, most severe first.
3. Check for hardcoded secrets and injection risks.
4. Note style issues only if they hurt readability.
5. End with a short verdict: approve, or request changes.

يحيط رمزا --- بالترويسة الأمامية (frontmatter). وتحتهما، يكون المتن نصًا عاديًا بصيغة Markdown. عبر مهاراتنا الـ25، البنية التي صمدت أمام الاستخدام الفعلي كانت مملة ومتسقة: عنوان بسطر واحد، ثم إجراء مرقّم أو بنقاط، ثم أي قوالب أو أمثلة. عندما حاولنا أن نكون بارعين في الصياغة النثرية، تصفّح Claude النص بسرعة دون التقاطه. وعندما كتبنا خطوات، اتبعها. إن أردت دراسة مهارات مكتملة، فإن الـ25 مهارة على موقع مجتمع Techsy كلها ملفات SKILL.md قابلة للقراءة يمكنك فتحها ونسخها.

قواعد الترويسة الأمامية: name وdescription

تحتوي الترويسة الأمامية على حقلين مطلوبين بالضبط، ولكل منهما حدود صارمة تستحق الحفظ لأن أدوات Anthropic تتحقق منها.

من الأعراف المفيدة الواردة في دليل أفضل الممارسات من Anthropic: سمِّ المهارات بصيغة gerund (فعل ينتهي بـ -ing ويعمل كاسم)، مثل processing-pdfs وwriting-documentation وanalyzing-spreadsheets. تُقرأ هذه الصيغة جيدًا في القوائم وتصف النشاط بدلًا من اسم غامض مثل helper أو utils. اجعل name مطابقًا لاسم المجلد حتى لا يفترق الاثنان أبدًا. للاطلاع على قواعد التحقق الكاملة، فإن دليل أفضل الممارسات من Anthropic هو المرجع الموثوق.

اكتب وصفًا يُفعّل المهارة فعليًا

هذا هو القسم الذي تتخطاه معظم الدروس التعليمية، وهو الذي يحدد ما إذا كان عملك سيُستخدم أصلًا. يُدرَج الوصف (description) ضمن مطالبة النظام (system prompt)، ويقرأه Claude ليقرر ما إذا كان سيحمّل مهارتك من الأساس. متن مثالي خلف وصف غامض يعني مهارة لن تعمل أبدًا.

ثلاث قواعد تصنع الفرق:

اكتب بصيغة الغائب. يصف الوصف المهارة نفسها، وليس أنت ولا المستخدم. الصياغة بصيغة المتكلم أو المخاطب تُربك عملية الاختيار.

# Good
description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDFs or when the user mentions forms or document extraction.

# Avoid
description: I can help you work with your PDF files whenever you need.

اذكر الاثنين معًا: الماذا والمتى. عبارة مثل "Processes data" لا تخبر Claude بشيء عن المهمة المطابقة. سمِّ القدرة المحددة ومحفزات التفعيل المحددة.

استخدم الكلمات التي سيكتبها المستخدم فعليًا. إذا كان الناس يقولون "PR" و"diff" و"code review"، فضع هذه المصطلحات في الوصف. يطابق Claude عليها. هذا هو التعديل الأكثر تأثيرًا الذي يمكنك إجراؤه على أي مهارة، وتكلفته سطر واحد فقط.

الكشف التدريجي وبنية الملفات

بمجرد أن تنمو المهارة لتتجاوز شاشة أو شاشتين، تبدأ البنية بالأهمية. إرشادات Anthropic واضحة: أبقِ متن SKILL.md أقل من 500 سطر، وانقل أي محتوى أطول إلى ملفات مرجعية منفصلة يربطها المتن. هذه الملفات لا تكلّف أي توكنات حتى يقرأها Claude فعليًا.

مهارة نضجت تبدو هكذا:

reviewing-pull-requests/
├── SKILL.md            # overview + the core procedure
├── security.md         # detailed security checklist (read when needed)
├── style-guide.md      # house style rules (read when needed)
└── scripts/
    └── diff_stats.py    # executed, never loaded into context

قاعدتان تُبقيان هذا يعمل. أولًا، أبقِ المراجع بعمق مستوى واحد فقط: اربط كل ملف مباشرة من SKILL.md، ولا تجعل ملفًا يشير إلى ملف يشير إلى ملف آخر، لأن Claude قد يكتفي بمعاينة الملفات العميقة التداخل بقراءة جزئية فيفوته المحتوى. ثانيًا، أضف جدول محتويات في أعلى أي ملف مرجعي يتجاوز 100 سطر حتى تُظهر القراءة الجزئية النطاق الكامل. يشرح المقال الهندسي حول Agent Skills من Anthropic البنية الكامنة وراء هذا إن أردت النموذج الأعمق. وعندما تبدأ مهارتك بتنسيق أدوات متعددة، فإن كتالوج MCP لدينا رفيق مفيد لربط الخوادم.

درجات الحرية (ومتى تضيف سكربتات)

ليس من الضروري أن تكون كل تعليمة صارمة بالدرجة نفسها. اجعل مدى إحكام برمجة الخطوة متناسبًا مع مدى هشاشتها.

عندما تكون الخطوة حتمية (deterministic)، أطلق سكربتًا بدلًا من أن تطلب من Claude توليد الكود في كل مرة. السكربت المرفق أكثر موثوقية، ويوفّر التوكنات، ويبقى متسقًا بين عمليات التشغيل. عادتان تحافظان على أمانة السكربتات: عالج الأخطاء داخل السكربت نفسه بدلًا من تركها لـClaude، وبرّر كل ثابت (constant) حتى لا تحصل على أرقام سحرية (magic numbers) غير مفسَّرة. هذه أيضًا النقطة التي تختلف فيها المهارات عن الوكلاء الفرعيين (subagents)، التي تحمل قائمة أدوات ومطالبة نظام خاصة بها؛ تجمع مكتبة الأتمتة لدينا أمثلة على الوكلاء الفرعيين، ويمكنك مقارنة النهجين على صفحة أتمتة الذكاء الاصطناعي في Techsy.

اختبرها: تطوير مهارات قائم على التقييم (eval-driven)

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

حلقة عملية:

1. اختر ثلاث مهام حقيقية يُفترض أن تتعامل معها المهارة.
2. شغّلها دون تحميل أي مهارة ودوّن ما ينكسر.
3. اكتب أقل نسخة ممكنة من SKILL.md تُصلح تلك الأعطال.
4. اختبر مجددًا مع تحميل المهارة، ويُفضّل عبر Claude Haiku وSonnet وOpus معًا، لأن المهارة التي توجّه Opus جيدًا قد تكون ناقصة التفصيل بالنسبة إلى Haiku.
5. راقب كيف يتنقّل Claude بين الملفات. إن تجاهل مرجعًا، فرابطك ليس بارزًا بما يكفي. وإن أعاد قراءة الملف نفسه باستمرار، فذلك المحتوى ينتمي إلى SKILL.md.

للحصول على شرح عملي يبني مهارة من البداية إلى النهاية، يقدّم موقعنا الشقيق درسًا تعليميًا كاملًا حول Claude Skills؛ وهو يتكامل جيدًا مع قواعد الكتابة الواردة هنا. يمكنك أيضًا تتبّع بناء مهارتك مقابل قوائم التحقق الخاصة بالبناء المؤسسي لدينا.

الأخطاء الشائعة التي تقتل المهارة

تفشل معظم المهارات المعطوبة لسبب واحد من قائمة قصيرة:

• وصف مكتوب للبشر. النص التسويقي يُقرأ بشكل جيد لكنه لا يُفعّل شيئًا. اكتب للنموذج: القدرات ومحفزات التفعيل.
• خيارات كثيرة جدًا. عبارة مثل "استخدم pypdf أو pdfplumber أو PyMuPDF أو..." تجعل Claude متردّدًا. أعطِ خيارًا افتراضيًا واحدًا مع مخرج طوارئ وحيد.
• مراجع متداخلة بعمق. الملفات التي تشير إلى ملفات تشير إلى ملفات أخرى تُقرأ جزئيًا فقط. أبقِ كل شيء على بُعد خطوة واحدة من SKILL.md.
• تعليمات مرتبطة بزمن محدد. عبارة مثل "قبل أغسطس، افعل X" تصبح بالية بسرعة. ضع الإرشادات المهجورة في ملاحظة قابلة للطي بعنوان "أنماط قديمة" بدلًا من ذلك.
• مسارات بأسلوب Windows. استخدم دائمًا الشرطة المائلة الأمامية (/)؛ الشرطة المائلة الخلفية () تتعطل على أنظمة تشغيل Unix.
• مصطلحات غير متسقة. اختر كلمة واحدة للشيء الواحد ("field" وليس "field/box/element/control") واستخدمها في كل مكان.

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

عن الكاتب

مرت باتور غوربوز (Mert Batur Gurbuz) هو الشريك المؤسس لشركة Techsy، وخريج جامعة برمنغهام (University of Birmingham). يبني هو وفريق Techsy وكلاء الذكاء الاصطناعي، وأنظمة الأتمتة، ومسارات الصوت وSDR لعملاء B2B، ويشرفون على مكتبة الـ25 مهارة المُشار إليها طوال هذا الدليل. تواصل معه عبر LinkedIn. المزيد من أدلة البناء متوفرة على مدونة TECHSY.community.

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

أين تُخزَّن ملفات مهارات Claude؟

المهارة هي مجلد يحتوي على ملف SKILL.md. في Claude Code، تُوضع المهارات الشخصية في ~/.claude/skills/{skill-name}/ ومهارات المشروع في .claude/skills/{skill-name}/. أما في الـAPI وclaude.ai، فترفع مجلد المهارة مباشرة. ينبغي أن يطابق اسم المجلد حقل name في الترويسة الأمامية.

هل يجب أن يطابق اسم المهارة اسم المجلد؟

نعم، أبقهما متطابقين. يجب ألا يتجاوز حقل name 64 حرفًا، وأن يستخدم حروفًا صغيرة وأرقامًا وشرطات فقط، وأن يتجنب الكلمتين المحجوزتين "anthropic" و"claude". مطابقة اسم المجلد تمنع الافتراق بين الاثنين وتجعل الإشارة إلى المهارة سهلة في المحادثة والتوثيق.

ما الطول الأقصى المسموح لملف SKILL.md؟

أبقِ متن SKILL.md أقل من 500 سطر لأداء موثوق. لا يوجد حد صارم للتوكنات، لأن الملفات المرجعية والسكربتات لا تكلّف شيئًا حتى تُقرأ، لكن الملف الرئيسي المتضخم يزاحم كل شيء آخر في نافذة السياق (context window). عندما تقترب من 500 سطر، قسّم التفاصيل إلى ملفات مرجعية يربطها SKILL.md مباشرة.

لماذا لا تُفعَّل مهارتي؟

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

ما الفرق بين المهارة (skill) والوكيل الفرعي (subagent) وخادم MCP؟

المهارة هي تعليمات معبّأة يحمّلها Claude عند الحاجة. الوكيل الفرعي (subagent) هو وكيل منفصل له قائمة أدوات ومطالبة نظام خاصة به، ويتولى مهمة موكَلة إليه. خادم MCP يتيح أدوات وبيانات خارجية عبر Model Context Protocol. المهارات تصف كيفية إنجاز العمل؛ وخوادم MCP توفّر ما يُتصرَّف عليه.

هل يمكن لمهارة Claude تشغيل الكود؟

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

هل تعمل المهارات في كل من الـAPI وclaude.ai؟

نعم، لكن بيئة التشغيل تختلف. في claude.ai، تستطيع بيئة تنفيذ الكود تثبيت حزم من npm وPyPI، بينما لا تملك Claude API أي وصول للشبكة أو تثبيت حزم أثناء التشغيل. اذكر الحزم المطلوبة في SKILL.md وتحقق من توفرها في البيئة المستهدفة قبل الاعتماد عليها.

كم عدد المهارات التي يمكن أن يحمّلها Claude في وقت واحد؟

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