ضياء البوزان | Tech42 صفحة
SKILLS SERIES · النسخة العربية الكاملة
SKILLS.
الدليل الكامل لبناء Skills لـ Claude

من الفكرة إلى SKILL.md جاهز للنشر — التخطيط، الكتابة، الاختبار، التوزيع، وأنماط الحلول الجاهزة، بالإضافة لقوالب عملية تبدأ منها مباشرة.

01 · Fundamentals 02 · Planning & Design 03 · Testing 04 · Distribution 05 · Patterns 06 · Templates
إعداد وترجمة
ضياء البوزان | Tech
@diyaa.albouzan.tech
ضياء البوزان
OVERVIEW · WHAT YOU WILL LEARNالفهرس

ماذا ستتعلّم في هذا الدليل؟

ست محطّات تأخذك من فهم مفهوم الـ Skill حتى بناء واحدة ونشرها فعلياً — بالتفاصيل والأمثلة.

01
Fundamentals
الأساسيات
  • ما هي الـ Skill؟
  • مبدأ الإفصاح التدريجي
  • Skills مع MCP
الفصل 1
02
Planning & Design
التخطيط والتصميم
  • حالات الاستخدام
  • معايير النجاح
  • الـ YAML frontmatter
الفصل 2
03
Testing
الاختبار والتكرار
  • ثلاث طرق للاختبار
  • اختبارات التفعيل
  • استخدام skill-creator
الفصل 3
04
Distribution
التوزيع والمشاركة
  • نموذج التوزيع الحالي
  • الاستخدام عبر API
  • كيف تُسوّق الـ skill
الفصل 4
05
Patterns
الأنماط والمشاكل
  • خمسة أنماط بناء جاهزة
  • حلّ أكثر المشاكل شيوعاً
الفصل 5
06
Templates
قوالب جاهزة
  • قالب تحويل مستند
  • قالب تحليل شامل
الملحق
كيف تقرأ الدليل

كل فصل مبني على الذي قبله — إن كنت تبني skill مستقلة ركّز على الفصول 1، 2، و5. وإن كنت تُحسّن تكامل MCP فأضف قسم "Skills + MCP".

ضياء البوزان | Tech · @diyaa.albouzan.tech 02 / 42
INTRODUCTION · GETTING STARTEDمقدّمة

ما هي الـ Skill، ولمن هذا الدليل؟

الـ Skill مجموعة تعليمات — معبّأة في مجلّد بسيط — تُعلّم Claude كيف يتعامل مع مهام أو سير عمل محدّد.

THE DEFINITION
بدل إعادة شرح تفضيلاتك وعملياتك وخبرتك في كل محادثة، الـ Skills تتيح لك تعليم Claude مرّة واحدة — والاستفادة في كل مرّة بعدها. تعمل بقوة مع سير العمل المتكرّر: توليد تصاميم من مواصفات، إجراء أبحاث بمنهجية ثابتة، إنشاء مستندات حسب دليل أسلوب فريقك، أو تنسيق عمليات متعدّدة الخطوات.
وهي تعمل جنباً إلى جنب مع قدرات Claude المدمجة مثل تنفيذ الكود وإنشاء المستندات.
✓
هذا الدليل لك إن كنت…
  • مطوّراً يريد Claude يتّبع سير عمل ثابت
  • مستخدماً محترفاً يريد اتّساقاً في النتائج
  • فريقاً يريد توحيد طريقة عمل Claude داخل المؤسسة
★
ما ستحصل عليه
بنهاية الدليل ستكون قادراً على بناء skill عاملة خلال جلسة واحدة — من 15 إلى 30 دقيقة باستخدام skill-creator.
التعريف بإيجاز

الـ Skill تُبنى من مجلّد يحتوي: SKILL.md (إلزامي)، ومجلدات اختيارية scripts/ و references/ و assets/.

ضياء البوزان | Tech · @diyaa.albouzan.tech 03 / 42
INTRODUCTION · TWO PATHS THROUGH THIS GUIDEمسارك في الدليل

مساران عبر هذا الدليل

كلا المسارين يشتركان في نفس المتطلبات التقنية، لكن تختار ما يهمّ حالتك.

A
بناء Skill مستقلّة
ركّز على:
  • Fundamentals (الفصل 1)
  • Planning and Design (الفصل 2)
  • الأنماط 1 و2 من الفصل 5
الأكثر شيوعاً
B
تحسين تكامل MCP
ركّز على:
  • قسم "Skills + MCP" في الفصل 1
  • النمط 3 من الفصل 5 (MCP Enhancement)
  • كل ما سبق ينطبق أيضاً
لأصحاب خوادم MCP
WHAT YOU\u2019LL GET
توقّع 15–30 دقيقة لبناء واختبار أول skill عاملة لك باستخدام skill-creator.
الخلاصة

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

ضياء البوزان | Tech · @diyaa.albouzan.tech 04 / 42
01
الفصل الأوّل
Fundamentals — الأساسيات

مما تتكوّن الـ Skill، وما المبادئ الثلاثة التي تجعلها فعّالة: الإفصاح التدريجي، التركيب، والقابلية للنقل.

FUNDAMENTALS · WHAT IS A SKILL?تشريح المجلّد

الـ Skill هي مجلّد يحتوي على…

ملف واحد إلزامي، وثلاثة مجلدات اختيارية — كل عنصر له دور محدد.

①إلزامي
SKILL.md
تعليمات بصيغة Markdown مع YAML frontmatter في الأعلى — قلب الـ skill.
الملف الوحيد الإلزامي
②اختياري
scripts/
كود قابل للتنفيذ — Python، Bash، وغيرها — لأي منطق حتمي يفضَّل تشغيله ككود لا كتعليمات لغوية.
③اختياري
references/
مستندات إضافية تُحمَّل عند الحاجة فقط — تفاصيل ثقيلة لا داعي لتحميلها دائماً.
④اختياري
assets/
قوالب، خطوط، أيقونات — أي ملف يُستخدم مباشرة في المخرَجات النهائية.
نصيحة

ابدأ بـ SKILL.md فقط. أضف scripts أو references أو assets لاحقاً فقط عندما تحتاجها فعلاً.

ضياء البوزان | Tech · @diyaa.albouzan.tech 06 / 42

هذا المبدأ هو ما يجعل Claude يستطيع تفعيل مئات الـ skills دون إرهاق الذاكرة السياقية.

FUNDAMENTALS · CORE DESIGN PRINCIPLEالإفصاح التدريجي

نظام Progressive Disclosure — ثلاثة مستويات

كل مستوى يُحمَّل فقط عند الحاجة إليه — هذا ما يقلّل استهلاك التوكنز مع الحفاظ على الخبرة المتخصصة.

1YAML frontmatter
المستوى الأول
يُحمَّل دائماً في الـ system prompt الخاص بـ Claude. يوفّر فقط المعلومات الكافية ليعرف Claude متى يُستخدَم كل skill — دون تحميلها بالكامل.
2SKILL.md body
المستوى الثاني
يُحمَّل فقط عندما يرى Claude أن الـ skill ذات صلة بالمهمّة الحالية. يحتوي التعليمات والتوجيهات الكاملة.
3Linked files
المستوى الثالث
ملفات إضافية داخل مجلّد الـ skill يتصفّحها Claude ويكتشفها فقط عند الحاجة الفعلية إليها.
لماذا يهمّ

الإفصاح التدريجي يقلّل استهلاك التوكنز مع الحفاظ على خبرة متخصصة كاملة عند الحاجة إليها.

ضياء البوزان | Tech · @diyaa.albouzan.tech 07 / 42
FUNDAMENTALS · TWO MORE PRINCIPLESمبدآن إضافيّان

التركيب (Composability) والقابلية للنقل (Portability)

الـ skill الجيدة لا تفترض أنها وحدها، ولا تتغيّر حسب مكان تشغيلها.

COMPOSABILITY
التركيب
Claude يمكنه تحميل عدّة skills في آنٍ واحد.
  • يجب أن تعمل الـ skill بانسجام مع غيرها
  • لا تفترض أنها القدرة الوحيدة المتاحة
  • صُمِّمت لتتكامل، لا لتتصادم
PORTABILITY
القابلية للنقل
الـ skills تعمل بنفس الطريقة عبر Claude.ai و Claude Code و الـ API.
  • ابنِها مرّة واحدة — تعمل على كل الواجهات
  • بلا أي تعديل إضافي
  • بشرط أن تدعم البيئة أي اعتماديات تحتاجها الـ skill
قاعدة التصميم

صمّم الـ skill وكأنّها ستعمل بجانب عشرات غيرها، وعلى منصّة لا تتحكّم بها بالكامل.

ضياء البوزان | Tech · @diyaa.albouzan.tech 08 / 42

إن كنت تبني skill مستقلة بلا MCP، يمكنك تخطّي هذه الصفحة والعودة إليها لاحقاً.

FOR MCP BUILDERS · SKILLS + CONNECTORSSkills + MCP

تشبيه المطبخ: MCP والـ Skills

إن كان لديك خادم MCP يعمل، فقد أنجزت الجزء الأصعب. الـ Skills هي طبقة المعرفة فوقه.

MCP
المطبخ الاحترافي
يوفّر الوصول إلى الأدوات، المكوّنات، والمعدّات.
  • يربط Claude بخدمتك (Notion، Asana، Linear…)
  • يوفّر وصولاً فورياً للبيانات واستدعاء الأدوات
ما الذي يستطيع Claude فعله
+
SKILLS
وصفات الطبخ
تعليمات خطوة بخطوة حول كيفية صنع شيء ذي قيمة.
  • تُعلِّم Claude كيف يستخدم خدمتك بفعالية
  • تُلخّص سير العمل وأفضل الممارسات التي تعرفها بالفعل
كيف ينبغي أن يفعلها Claude
الخلاصة

معاً، يُمكّنان المستخدمين من إنجاز مهام معقّدة دون الحاجة لمعرفة كل خطوة بأنفسهم.

ضياء البوزان | Tech · @diyaa.albouzan.tech 09 / 42
FOR MCP BUILDERS · WHY THIS MATTERSبدون Skills مقابل معها

لماذا يهمّ هذا لمستخدمي MCP؟

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

✕بدون Skills
  • المستخدمون يربطون MCP لكن لا يعرفون الخطوة التالية
  • تذاكر دعم تسأل "كيف أفعل X بتكاملكم؟"
  • كل محادثة تبدأ من الصفر
  • نتائج غير متّسقة لأن كل مستخدم يكتب الطلب بطريقته
  • المستخدمون يلومون الـ connector والمشكلة فعلياً في التوجيه
✓مع Skills
  • سير عمل جاهز يُفعَّل تلقائياً عند الحاجة
  • استخدام أدوات متّسق وموثوق
  • أفضل الممارسات مدمجة في كل تفاعل
  • منحنى تعلّم أقل لتكاملك
  • قيمة أسرع لمستخدمي الـ connector الخاص بك
الأثر التجاري

الـ Skills تجعل تكامل الـ MCP الخاص بك مكتملاً — تمنحك أفضلية أمام البدائل التي تعتمد على MCP فقط.

ضياء البوزان | Tech · @diyaa.albouzan.tech 10 / 42
02
الفصل الثاني
Planning and Design — التخطيط والتصميم

من حالة الاستخدام إلى الـ YAML frontmatter — كل قرار تصميمي يحدّد هل ستُفعَّل الـ skill في اللحظة الصحيحة أم لا.

PLANNING · START WITH USE CASESابدأ من حالة الاستخدام

قبل كتابة أي كود، حدّد 2–3 حالات استخدام

حالة استخدام مكتوبة جيداً توضّح: متى تُفعَّل الـ skill، وما الخطوات، وما النتيجة المتوقّعة.

GOOD USE CASE DEFINITION
حالة الاستخدام: التخطيط لسبرنت المشروع

المُحفِّز: المستخدم يقول "ساعدني أخطّط لهذا السبرنت" أو "أنشئ مهام السبرنت"

الخطوات: 1) جلب حالة المشروع من Linear عبر MCP · 2) تحليل سرعة الفريق وطاقته · 3) اقتراح ترتيب أولويات المهام · 4) إنشاء المهام في Linear بالتصنيفات والتقديرات الصحيحة

النتيجة: سبرنت مخطَّط بالكامل مع مهام منشأة فعلياً
?
اسأل نفسك
  • ما الذي يريد المستخدم إنجازه؟
  • ما سير العمل متعدّد الخطوات الذي يتطلّبه هذا؟
  • ما الأدوات المطلوبة (مدمجة أم MCP)؟
  • ما المعرفة أو أفضل الممارسات الواجب تضمينها؟
لماذا نبدأ هنا

حالة استخدام محدّدة بوضوح هي أساس كل قرار تصميمي لاحق في بناء الـ skill.

ضياء البوزان | Tech · @diyaa.albouzan.tech 12 / 42
PLANNING · COMMON USE CASE CATEGORIESثلاث فئات شائعة

ثلاث فئات لحالات استخدام Skills

كما لاحظنا في Anthropic — معظم الـ skills الناجحة تقع ضمن واحدة من هذه الفئات.

1
إنشاء المستندات والأصول
لإنتاج مخرَجات متّسقة وعالية الجودة: مستندات، عروض تقديمية، تطبيقات، تصاميم، كود.
  • مثال: frontend-design skill
  • أدلّة أسلوب وهوية بصرية مدمجة
  • قوالب هيكلية للمخرَج الموحّد
  • قوائم جودة قبل الإنهاء
مثال: frontend-design
2
أتمتة سير العمل
لعمليات متعدّدة الخطوات تستفيد من منهجية ثابتة، بما فيها التنسيق بين عدّة خوادم MCP.
  • مثال: skill-creator
  • سير عمل خطوة بخطوة مع بوّابات تحقّق
  • قوالب لهياكل شائعة
  • حلقات تحسين تكرارية
مثال: skill-creator
3
تعزيز MCP
توجيه سير العمل لتعزيز وصول الأدوات الذي يوفّره خادم MCP.
  • مثال: sentry-code-review skill
  • تنسيق عدّة استدعاءات MCP بالتسلسل
  • خبرة مجالية مدمجة
  • معالجة أخطاء لمشاكل MCP الشائعة
مثال: sentry-code-review
الخلاصة

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

ضياء البوزان | Tech · @diyaa.albouzan.tech 13 / 42
PLANNING · DEFINE SUCCESS CRITERIAمعايير النجاح

كيف تعرف أن الـ Skill تعمل؟

أهداف استرشادية أكثر من كونها عتبات دقيقة — اجتهد بصرامة لكن تقبّل عنصر التقييم الحسّي.

QUANTITATIVE
مقاييس كمّية
  • تُفعَّل الـ skill في 90% من الاستفسارات ذات الصلة — شغّل 10–20 استعلام اختبار وتتبّع التفعيل التلقائي
  • تُكمل سير العمل بعدد معيّن من استدعاءات الأدوات — قارن نفس المهمة بوجود الـ skill وبدونها
  • 0 استدعاءات API فاشلة لكل سير عمل — راقب سجلّات خادم MCP وتتبّع معدّلات إعادة المحاولة
QUALITATIVE
مقاييس نوعية
  • المستخدمون لا يحتاجون توجيه Claude بشأن الخطوة التالية
  • سير العمل يكتمل دون تصحيح من المستخدم — كرّر نفس الطلب 3–5 مرّات وقارن الاتّساق
  • نتائج متّسقة عبر الجلسات — هل يستطيع مستخدم جديد إنجاز المهمة من أول محاولة؟
ملاحظة

Anthropic تعمل حالياً على تطوير إرشادات وأدوات قياس أكثر نضجاً لهذا الجانب.

ضياء البوزان | Tech · @diyaa.albouzan.tech 14 / 42
PLANNING · TECHNICAL REQUIREMENTSالمتطلّبات التقنية

هيكل الملفّات وقواعد التسمية الصارمة

قواعد بسيطة، لكن مخالفتها تمنع رفع الـ skill بالكامل.

SKILL.MD NAMING
تسمية SKILL.md
  • يجب أن يكون بالضبط SKILL.md (حسّاس لحالة الأحرف)
  • لا اختلافات مقبولة: SKILL.MD، skill.md، إلخ
FOLDER NAMING
تسمية مجلّد الـ skill
  • استخدم kebab-case: notion-project-setup ✓
  • بلا مسافات: Notion Project Setup ✕
  • بلا شرطة سفلية: notion_project_setup ✕
  • بلا أحرف كبيرة: NotionProjectSetup ✕
NO README.MD
بدون README.md
لا تُضمِّن README.md داخل مجلّد الـ skill — كل التوثيق يذهب إلى SKILL.md أو references/. ملاحظة: عند التوزيع عبر GitHub ستحتاج مع ذلك لملف README على مستوى المستودع للزوّار البشريين — راجع فصل التوزيع.
الأكثر أهمية

هذه القواعد الثلاث هي أكثر أسباب فشل رفع الـ skill شيوعاً — تحقّق منها أولاً عند أي خطأ.

ضياء البوزان | Tech · @diyaa.albouzan.tech 15 / 42

الـ YAML frontmatter هو كيف يقرّر Claude تحميل الـ skill من عدمه — احرص على كتابته بدقّة.

PLANNING · YAML FRONTMATTERالجزء الأهم

الـ YAML frontmatter — الصيغة الدنيا

حقلان فقط مطلوبان للبدء — لكن جودتهما تحدّد مصير الـ skill بالكامل.

MINIMAL REQUIRED FORMAT
--- name: your-skill-name description: What it does. Use when user asks to [specific phrases]. ---
nameمطلوب
الحقل name
  • بصيغة kebab-case فقط
  • بلا مسافات أو أحرف كبيرة
  • يجب أن يطابق اسم المجلّد
descمطلوب
الحقل description
  • يجب أن يتضمّن: ماذا تفعل الـ skill + متى تُستخدَم
  • أقل من 1024 حرفاً
  • بلا علامات XML (< أو >)
  • اذكر مهام محدّدة قد يقولها المستخدمون
الخلاصة

هذا كل ما تحتاجه للبدء فعلياً — بقية الحقول اختيارية بالكامل.

ضياء البوزان | Tech · @diyaa.albouzan.tech 16 / 42
PLANNING · OPTIONAL FIELDS & SECURITYحقول اختيارية وأمان

حقول اختيارية وقيود أمنية صارمة

مرونة أكبر في التوثيق — لكن مع قيود واضحة لحماية سلامة النظام.

OPTIONAL
الحقول الاختيارية
  • license: عند جعل الـ skill مفتوحة المصدر — مثل MIT، Apache-2.0
  • compatibility: من 1 إلى 500 حرف — متطلّبات البيئة
  • metadata: أزواج مفتاح-قيمة حرّة — يُقترَح: author، version، mcp-server
FORBIDDEN
ممنوع في الـ frontmatter
  • أقواس XML الزاويّة (< و >) — قيد أمني
  • أسماء skills تحتوي "claude" أو "anthropic" (محجوزة)
لماذا القيود

السبب: الـ frontmatter يظهر داخل الـ system prompt الخاص بـ Claude — أي محتوى ضار قد يحاول حقن تعليمات.

ضياء البوزان | Tech · @diyaa.albouzan.tech 17 / 42
PLANNING · THE DESCRIPTION FIELDأوصاف جيدة وسيّئة

وصف جيّد مقابل وصف ضعيف

البنية الذهبية: [ماذا تفعل] + [متى تُستخدَم] + [القدرات الأساسية].

✕أوصاف ضعيفة
description: Helps with projects. description: Creates sophisticated multi-page documentation systems. description: Implements the Project entity model with hierarchical relationships.
غامضة جداً، أو تفتقد كلمات التشغيل، أو تقنية أكثر من اللازم بلا محفّزات واضحة للمستخدم.
✓أوصاف جيّدة
description: Analyzes Figma design files and generates developer handoff documentation. Use when user uploads .fig files, asks for "design specs" or "design-to-code handoff".
محدّدة وقابلة للتنفيذ، تتضمّن عبارات تشغيل واضحة، وتوضح القيمة المقدَّمة بجلاء.
اختبار سريع

اختبر وصفك: اسأل Claude "متى تستخدم skill [الاسم]؟" — سيقتبس الوصف. عدّل بناءً على ما ينقص.

ضياء البوزان | Tech · @diyaa.albouzan.tech 18 / 42
PLANNING · WRITING THE MAIN INSTRUCTIONSقالب التعليمات

كتابة التعليمات الرئيسية بعد الـ frontmatter

عدّل هذا القالب حسب الـ skill الخاصة بك — استبدل الأقسام بين قوسين بمحتواك الفعلي.

# Your Skill Name ## Instructions ### Step 1: [First Major Step] شرح واضح لما يحدث، مع مثال كود إن لزم. Expected output: [صف كيف يبدو النجاح] (أضف خطوات إضافية حسب الحاجة) ## Examples Example 1: [سيناريو شائع] User says: "..." → Actions: ... → Result: ... ## Troubleshooting Error: [رسالة خطأ شائعة] Cause: [لماذا يحدث] Solution: [كيف تُصلحه]
تذكير

استخدم الإفصاح التدريجي: أبقِ SKILL.md مركّزاً على التعليمات الأساسية، وانقل التوثيق التفصيلي إلى references/ مع رابط إليه.

ضياء البوزان | Tech · @diyaa.albouzan.tech 19 / 42
PLANNING · BEST PRACTICES FOR INSTRUCTIONSكن محدداً وقابلاً للتنفيذ

أفضل الممارسات لكتابة التعليمات

التعليمات المحدّدة تُنفَّذ. التعليمات الغامضة تُفسَّر بطرق مختلفة في كل مرّة.

✕سيّئ
Validate the data before proceeding.
غامض — لا يوضّح كيف يتحقّق Claude ولا ماذا يفعل عند الفشل.
✓جيّد
Run `python scripts/validate.py --input {filename}` to check data format. If validation fails, common issues include: - Missing required fields - Invalid date formats (YYYY-MM-DD)
أمر محدّد، ونتيجة متوقّعة، وحالات فشل شائعة مع الحلول.
تقنية متقدّمة

للتحقّقات الحرجة، فكّر بتضمين سكربت يقوم بالفحص برمجياً بدل الاعتماد على تفسير اللغة — الكود حتمي، أمّا اللغة فلا.

ضياء البوزان | Tech · @diyaa.albouzan.tech 20 / 42
03
الفصل الثالث
Testing and Iteration — الاختبار والتكرار

الـ skills وثائق حيّة. من الاختبار اليدوي السريع إلى التقييم البرمجي عبر الـ API — اختر الصرامة المناسبة لحالتك.

TESTING · THREE LEVELS OF RIGORمستويات الاختبار

ثلاث طرق لاختبار الـ Skills

اختر المستوى المناسب لمدى ظهور الـ skill الخاصة بك — فريق داخلي صغير يختلف عن آلاف المستخدمين.

1
اختبار يدوي في Claude.ai
شغّل استعلامات مباشرة ولاحظ السلوك.
تكرار سريع، بلا إعداد
2
اختبار مبرمَج في Claude Code
أتمتة حالات اختبار للتحقّق المتكرّر عبر التغييرات.
قابل للتكرار
3
اختبار برمجي عبر skills API
ابنِ مجموعات تقييم تعمل بشكل منهجي مقابل مجموعات اختبار محدّدة.
الأكثر صرامة
PRO TIP
كرِّر على مهمّة واحدة صعبة قبل التوسّع
أكثر صنّاع الـ skills فعالية يكرّرون على مهمّة صعبة واحدة حتى ينجح Claude، ثم يستخرجون النهج الفائز في skill. هذا يستفيد من التعلّم داخل السياق ويمنح إشارة أسرع من الاختبار الواسع.
الترتيب الموصى به

ابنِ أساساً ناجحاً على مهمّة واحدة أولاً، ثم وسّع لحالات اختبار متعدّدة للتغطية الكاملة.

ضياء البوزان | Tech · @diyaa.albouzan.tech 22 / 42
TESTING · TRIGGERING TESTSاختبارات التفعيل

هل تُفعَّل الـ Skill في اللحظة الصحيحة؟

الهدف: التأكّد من أن الـ skill تُحمَّل في الأوقات الصحيحة فقط — لا أكثر ولا أقلّ.

✕يجب ألّا يُفعَّل
"What is the weather in San Francisco?" "Help me write Python code" "Create a spreadsheet" (unless the skill handles sheets)
استعلامات غير ذات صلة — إن فعّلت الـ skill هنا فهي "over-triggering".
✓يجب أن يُفعَّل
"Help me set up a new ProjectHub workspace" "I need to create a project in ProjectHub" "Initialize a ProjectHub project for Q4 planning"
مهام واضحة ومُعاد صياغتها — إن لم تُفعَّل هنا فهي "under-triggering".
كيف تقيس

شغّل 10–20 استعلام اختبار يجب أن تُفعِّل الـ skill، وتتبّع كم مرّة تُحمَّل تلقائياً مقابل الحاجة لتفعيل يدوي.

ضياء البوزان | Tech · @diyaa.albouzan.tech 23 / 42
TESTING · FUNCTIONAL TESTS & COMPARISONالاختبار الوظيفي

أثبِت أن الـ Skill تُحسّن النتائج فعلياً

قارن نفس المهمّة بوجود الـ skill وبدونها — الأرقام تتحدّث.

WITHOUT SKILL
بلا Skill
  • المستخدم يزوّد التعليمات في كل مرّة
  • 15 رسالة ذهاباً وإياباً
  • 3 استدعاءات API فاشلة تحتاج إعادة محاولة
  • 12{,}000 توكن مستهلَكة
مجهود متكرّر ونتائج غير مضمونة
VS
WITH SKILL
مع Skill
  • تنفيذ سير العمل تلقائياً
  • سؤالان توضيحيّان فقط
  • 0 استدعاءات API فاشلة
  • 6{,}000 توكن مستهلَكة
نصف التوكنز، صفر أخطاء
كيف تبني المقارنة

استخدم مقاييس "معايير النجاح" من الفصل الثاني لبناء هذه المقارنة على بياناتك الفعلية.

ضياء البوزان | Tech · @diyaa.albouzan.tech 24 / 42
TESTING · SKILL-CREATOR & ITERATIONskill-creator والتكرار

استخدم skill-creator ثم كرِّر بناءً على الإشارات

الـ skills وثائق حيّة — خطّط للتكرار المستمر بناءً على ثلاث إشارات رئيسية.

UNDER-TRIGGERING
تفعيل ناقص
  • الـ skill لا تُحمَّل عندما يجب
  • المستخدمون يفعّلونها يدوياً
  • أسئلة دعم حول متى تُستخدَم
الحل: أضف تفاصيل ودقّة للوصف
OVER-TRIGGERING
تفعيل زائد
  • تُحمَّل لاستعلامات غير ذات صلة
  • المستخدمون يعطّلونها
  • ارتباك حول الغرض منها
الحل: أضف محفّزات سلبية، وكن أكثر تحديداً
EXECUTION ISSUES
مشاكل تنفيذ
  • نتائج غير متّسقة
  • فشل استدعاءات API
  • تصحيحات متكرّرة من المستخدم
الحل: حسّن التعليمات وأضف معالجة أخطاء
كيف تستخدمه

"استخدم skill-creator لبناء skill لـ [حالتك]" — يولّد SKILL.md صحيح البنية، ويقترح عبارات تشغيل وحالات اختبار، ويراجع الإصدارات السابقة.

ضياء البوزان | Tech · @diyaa.albouzan.tech 25 / 42
04
الفصل الرابع
Distribution and Sharing — التوزيع والمشاركة

من الرفع الفردي إلى النشر على مستوى المؤسسة، ومن الاستخدام عبر الواجهة إلى الأتمتة الكاملة عبر الـ API.

DISTRIBUTION · CURRENT MODEL (JANUARY 2026)نموذج التوزيع

كيف تصل الـ Skills إلى المستخدمين اليوم

من التنزيل الفردي إلى النشر التلقائي على مستوى المؤسسة بالكامل.

INDIVIDUAL USERS
للمستخدم الفردي
  • نزّل مجلّد الـ skill
  • اضغطه بصيغة .zip إن لزم
  • ارفعه عبر Claude.ai › Settings › Capabilities › Skills
  • أو ضعه في مجلّد skills الخاص بـ Claude Code
ORGANIZATION-WIDE
على مستوى المؤسسة
  • المدراء ينشرون الـ skills على مستوى بيئة العمل بالكامل
  • تحديثات تلقائية
  • إدارة مركزية
AN OPEN STANDARD
معيار مفتوح للجميع
نشرت Anthropic معيار Agent Skills كمعيار مفتوح — تماماً كـ MCP. نفس الـ skill يجب أن تعمل سواء استخدمت Claude أو منصّة أخرى. بعض الـ skills مصمَّمة للاستفادة الكاملة من منصّة محدَّدة — يمكن للمؤلفين توضيح ذلك في حقل compatibility.
ميزة المستوى التنظيمي

كل تحديث ينتشر تلقائياً — لا حاجة لإعادة توزيع يدوي للفِرَق.

ضياء البوزان | Tech · @diyaa.albouzan.tech 27 / 42
DISTRIBUTION · USING SKILLS VIA APIالاستخدام عبر API

متى تستخدم API ومتى Claude.ai؟

للاستخدامات البرمجية — بناء تطبيقات أو وكلاء أو سير عمل آلي — يمنحك الـ API تحكماً مباشراً.

حالة الاستخدامBest Surface
مستخدمون يتفاعلون مع الـ skills مباشرةClaude.ai / Claude Code
اختبار وتكرار يدوي أثناء التطويرClaude.ai / Claude Code
سير عمل فردي غير متكرّرClaude.ai / Claude Code
تطبيقات تستخدم الـ skills برمجياًAPI
نشر إنتاجي على نطاق واسعAPI
أنابيب آلية وأنظمة وكلاءAPI
KEY CAPABILITIES
قدرات الـ API الأساسية
  • نقطة النهاية /v1/skills لسرد وإدارة الـ skills
  • إضافة skills لطلبات Messages API عبر معامل container.skills
  • إدارة الإصدارات عبر Claude Console
  • يعمل مع Claude Agent SDK لبناء وكلاء مخصّصين
متطلّب تقني

ملاحظة: الـ skills عبر الـ API تتطلّب ميزة Code Execution Tool (beta) — توفّر البيئة الآمنة التي تحتاجها الـ skills للتشغيل.

ضياء البوزان | Tech · @diyaa.albouzan.tech 28 / 42
DISTRIBUTION · RECOMMENDED APPROACH TODAYالمسار الموصى به

ابدأ باستضافة الـ Skill على GitHub

مستودع عام، README واضح للزوّار البشريين، وأمثلة استخدام بلقطات شاشة.

1STEP 1 OF 3
استضِف على GitHub
  • مستودع عام لـ skills مفتوحة المصدر
  • README واضح مع تعليمات التثبيت
  • أمثلة استخدام ولقطات شاشة
2STEP 2 OF 3
وثّق في مستودع الـ MCP
  • اربط الـ skill من توثيق MCP الخاص بك
  • اشرح قيمة استخدام الاثنين معاً
  • قدّم دليل بدء سريع
3STEP 3 OF 3
أنشئ دليل تثبيت
  • استنسخ المستودع أو نزّل ZIP من Releases
  • Claude.ai › Settings › Skills › Upload skill
  • فعّل الـ skill واختبرها: "Set up a new project in [Service]"
تذكير مهم

مستودع الـ skill نفسه يجب ألّا يحتوي README.md — الـ README هنا على مستوى المستودع لزوّار GitHub البشريين فقط.

ضياء البوزان | Tech · @diyaa.albouzan.tech 29 / 42
DISTRIBUTION · POSITIONING YOUR SKILLكيف تُسوّق Skill الخاصة بك

ركّز على النتائج، لا على الميزات التقنية

كيف تصف الـ skill في الـ README أو التوثيق أو التسويق يحدّد هل سيجرّبها المستخدمون أصلاً.

✕وصف سيّئ
"The ProjectHub skill is a folder containing YAML frontmatter and Markdown instructions that calls our MCP server tools."
يشرح كيف بُنيت تقنياً — لا يهتمّ المستخدم بهذا، بل بما تحلّه له.
✓وصف جيّد
"The ProjectHub skill enables teams to set up complete project workspaces in seconds — instead of spending 30 minutes on manual setup."
يركّز على النتيجة الملموسة والوقت الموفَّر — هذا ما يقنع المستخدم بالتجربة.
صيغة جاهزة

أبرِز قصّة "MCP + Skills معاً": الـ MCP يمنح Claude الوصول، والـ Skill تُعلّمه سير عمل فريقك — معاً يُمكّنان إدارة مشاريع مدعومة بالذكاء الاصطناعي.

ضياء البوزان | Tech · @diyaa.albouzan.tech 30 / 42
05
الفصل الخامس
Patterns and Troubleshooting — الأنماط ومعالجة المشاكل

أنماط ظهرت من skills بناها متبنّون أوائل وفرق داخلية — تمثّل نُهجاً شائعة أثبتت نجاحها، لا قوالب إلزامية.

تماماً كمتجر Home Depot: قد تدخل بمشكلة "أحتاج أصلح خزانة مطبخي" فيوجّهك الموظّف للأداة الصحيحة — أو تختار مثقاباً وتسأل كيف تستخدمه لمهمّتك.

PATTERNS · CHOOSING YOUR APPROACHاختيار المنهج

Problem-first مقابل Tool-first

مُعظم الـ skills تميل لاتّجاه واحد — معرفة أيّهما يناسب حالتك يوجّهك للنمط الصحيح.

PROBLEM-FIRST
"أحتاج إعداد مساحة عمل مشروع"
الـ skill تنسّق استدعاءات MCP الصحيحة بالترتيب الصحيح.
  • المستخدمون يصفون النتائج
  • الـ skill تتولّى الأدوات
VS
TOOL-FIRST
"لدي Notion MCP متّصل"
الـ skill تُعلّم Claude سير العمل الأمثل وأفضل الممارسات.
  • المستخدمون لديهم الوصول
  • الـ skill توفّر الخبرة
قبل أن تختار

حدّد أي إطار يناسب حالة الاستخدام لديك قبل اختيار أحد الأنماط الخمسة التالية.

ضياء البوزان | Tech · @diyaa.albouzan.tech 32 / 42
PATTERNS · FIVE BUILD PATTERNS AT A GLANCEخمسة أنماط

خمسة أنماط بناء جاهزة للاستخدام

اختر النمط الأقرب لطبيعة سير العمل الذي تبنيه.

1
تنسيق تسلسلي
لسير عمل متعدّد الخطوات بترتيب محدّد.
  • ترتيب خطوات صريح
  • اعتماديات بين الخطوات
  • تحقّق في كل مرحلة
2
تنسيق متعدّد MCP
لسير عمل يمتدّ عبر عدّة خدمات.
  • فصل واضح بين المراحل
  • تمرير بيانات بين الخوادم
  • معالجة أخطاء مركزية
3
تحسين تكراري
حين تتحسّن الجودة بالتكرار.
  • معايير جودة صريحة
  • حلقة تحسين وتحقّق
  • معرفة متى تتوقّف
4
اختيار أداة واعٍ بالسياق
نفس النتيجة، أدوات مختلفة حسب السياق.
  • شجرة قرار واضحة
  • خيارات احتياطية
  • شفافية حول الاختيار
5
ذكاء مجالي متخصّص
حين تضيف الـ skill معرفة متخصصة تتجاوز الوصول للأدوات.
  • خبرة مجالية مدمجة بالمنطق
  • تحقّق قبل التنفيذ
  • حَوكمة وتوثيق واضحان
للتفصيل الكامل

راجع أمثلة كل نمط في المصادر المرفقة — Sequential Orchestration، Multi-MCP، Iterative Refinement، Context-Aware Selection، Domain Intelligence.

ضياء البوزان | Tech · @diyaa.albouzan.tech 33 / 42
TROUBLESHOOTING · UPLOAD & TRIGGERINGأعطال شائعة · 1

"الـ Skill لا تُرفَع" أو لا تُفعَّل

أكثر ثلاث مشاكل شيوعاً عند البدء — وحلّها المباشر.

WON'T UPLOAD
لا يُرفَع "SKILL.md not found"
  • السبب: الملف غير مُسمَّى SKILL.md بالضبط
  • الحل: أعد التسمية (حسّاس لحالة الأحرف)
  • تحقّق بـ: ls -la يجب أن يُظهر SKILL.md
INVALID FRONTMATTER
"Invalid frontmatter"
  • السبب الشائع: نسيان الفواصل --- أو علامات اقتباس غير مغلقة
  • تأكّد من --- في البداية والنهاية
  • تأكّد من إغلاق كل علامات الاقتباس
DOESN'T TRIGGER
لا تُفعَّل الـ skill تلقائياً
  • هل الوصف عام جداً؟ ("Helps with projects" لن ينجح)
  • هل يتضمّن عبارات تشغيل يقولها المستخدمون فعلياً؟
  • هل يذكر أنواع الملفات ذات الصلة؟
اختبار تشخيصي

اختبار تشخيصي سريع: اسأل Claude "متى تستخدم skill [الاسم]؟" وقارن الإجابة بما تنوي فعلاً.

ضياء البوزان | Tech · @diyaa.albouzan.tech 34 / 42
TROUBLESHOOTING · MCP, INSTRUCTIONS & CONTEXTأعطال شائعة · 2

مشاكل الاتصال والتنفيذ والسياق

حين تُحمَّل الـ skill لكن النتائج ليست كما هو متوقّع.

MCP CONNECTION
استدعاءات MCP تفشل
  • تحقّق من اتصال الخادم: Settings › Extensions
  • تأكّد من صلاحية مفاتيح API والصلاحيات
  • اختبر MCP مباشرة بدون الـ skill أولاً
  • تحقّق من دقّة أسماء أدوات MCP (حسّاسة لحالة الأحرف)
INSTRUCTIONS IGNORED
Claude لا يتّبع التعليمات
  • التعليمات مطوَّلة أكثر من اللازم — اختصر واستخدم نقاطاً
  • ضع التعليمات الحرجة في الأعلى، استخدم ## Critical
  • لغة غامضة؟ اكتب تحقّقات صريحة بدل "تأكّد من صحة الأمور"
LARGE CONTEXT
الـ skill بطيئة أو الاستجابة ضعيفة
  • أبقِ SKILL.md تحت 5{,}000 كلمة
  • انقل التفاصيل إلى references/ واربط إليها
  • قيّم إن كان لديك أكثر من 20–50 skill مفعّلة معاً
تقنية إضافية

للكسل النموذجي: أضف تشجيعاً صريحاً — "خذ وقتك للتأكّد من الجودة، لا تتخطَّ خطوات التحقّق" — هذا أكثر فعالية في الـ prompt من كتابته في SKILL.md.

ضياء البوزان | Tech · @diyaa.albouzan.tech 35 / 42
06
الفصل السادس
Resources and References — المصادر والمراجع

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

RESOURCES · OFFICIAL DOCS, EXAMPLES & TOOLSمصادر رسمية

أين تجد المزيد؟

التوثيق الرسمي، مستودع الأمثلة، وأداة skill-creator لبناء ومراجعة الـ skills.

ANTHROPIC RESOURCES
توثيق ومدوّنات
  • دليل أفضل الممارسات · توثيق الـ Skills
  • مرجع الـ API · توثيق MCP
  • "Introducing Agent Skills" وتدوينات هندسية ذات صلة
EXAMPLE SKILLS
مستودع الأمثلة العامّ
  • GitHub: anthropics/skills
  • يحتوي skills أنشأتها Anthropic يمكنك تخصيصها
  • استنسخها، عدّلها، استخدمها كقوالب
TOOLS & SUPPORT
الأدوات والدعم
  • skill-creator: مدمجة في Claude.ai ومتوفّرة لـ Claude Code
  • أسئلة عامّة: منتديات مجتمع Claude Developers Discord
  • تقارير الأعطال: GitHub Issues على anthropics/skills
من أين تبدأ

ابدأ من دليل أفضل الممارسات، ثم راجع مراجع API التقنية عند الحاجة فقط.

ضياء البوزان | Tech · @diyaa.albouzan.tech 37 / 42
REFERENCE · QUICK CHECKLIST & YAML CHEAT-SHEETمرجع سريع

قائمة تحقّق قبل النشر

استخدمها للتحقّق من الـ skill قبل وبعد الرفع — أو ابدأ بـ skill-creator ثم راجع هذه القائمة.

BEFORE YOU START
قبل البدء
  • حدّدت 2–3 حالات استخدام ملموسة
  • حدّدت الأدوات (مدمجة أو MCP)
  • راجعت هذا الدليل و skills مثال
DURING DEVELOPMENT
أثناء التطوير
  • مجلّد بصيغة kebab-case
  • ملف SKILL.md موجود بالتسمية الصحيحة
  • الـ description يتضمّن ماذا ومتى، وبلا أقواس XML
BEFORE / AFTER UPLOAD
قبل وبعد الرفع
  • اختُبر التفعيل على مهام واضحة ومُعاد صياغتها
  • اختبارات وظيفية ناجحة، ومضغوط بصيغة .zip
  • راقب التفعيل الناقص/الزائد بعد الرفع وكرّر
YAML — الحدّ الأدنى

الحقول المطلوبة فقط: name (kebab-case) و description (ماذا + متى، أقل من 1024 حرفاً، بلا < >).

ضياء البوزان | Tech · @diyaa.albouzan.tech 38 / 42
+
ملحق
Templates — قوالب إنشاء Skills

قالبان جاهزان لطلب Claude ببنائهما — الصقهما مباشرة في المحادثة وعبّئ الأقواس بمحتواك.

TEMPLATES · METHOD 1قالب 1

حوّل مستنداً إلى Skill

الأنسب حين يكون لديك مستند موجود (دليل أسلوب، عملية، معيار) وتريد تحويله مباشرة.

CLAUDE CHAT REQUEST
Review the [document_name] document I attached for you. Transform it into a reusable Claude Skill that can [purpose].
NOTES
ملاحظات إلزامية
  • قبل البدء، تحقّق من إرفاق كل ملفات سياق العلامة اللازمة — وإن نقص شيء، توقّف واسأل أسئلة محدّدة
  • التزم بدقّة بالخطوات الموضّحة في المستند
  • حافظ على اتّساق التسمية والنبرة وأسلوب التنسيق وبنية المجلدات
  • احفظ الـ skill الجاهزة داخل مجلّد /claude/skills/ بصيغة صحيحة وجاهزة للنشر
  • استخدم skill-creator لضمان البنية والتنسيق الصحيحين
متى تستخدمه

الأبسط للبدء — مثالي حين يكون لديك مصدر جاهز تريد Claude يستخرج منه الـ skill.

ضياء البوزان | Tech · @diyaa.albouzan.tech 40 / 42
TEMPLATES · METHOD 2قالب 2

قالب تحليل شامل ومنظّم

الأنسب حين تبني skill من الصفر بلا مستند مصدر — عبّئ كل قسم بعناية.

Create a custom Claude skill called "[skill-name]". ## What This Skill Does [وصف الغرض في 1-2 جملة — ما المشكلة التي يحلّها؟] ## Trigger Conditions - [عبارة أو سياق التشغيل 1] - [عبارة أو سياق التشغيل 2] ## Core Behavior 1. [أول ما يفعله Claude] 2. [ثاني ما يفعله Claude] ## Input It Accepts / Output It Produces [ما يقدّمه المستخدم] → [صيغة وتسمية المخرَج] ## Dependencies / MCP Tools Required [الأداة] — [استخدامها]. إن كانت غير متاحة: أبلغ المستخدم ولا تشغّل الـ skill بدونها. ## Example Input → Output Input: "[مثال طلب المستخدم]" Expected Output: "[وصف موجز للمخرَج]"
ملاحظات إلزامية

استخدم skill-creator لضمان بنية SKILL.md الصحيحة، واحفظها داخل .claude/skills/[skill-name]/ جاهزة للاستخدام الفوري.

ضياء البوزان | Tech · @diyaa.albouzan.tech 41 / 42
من الفكرة إلى SKILL.md جاهز للنشر

ابدأ بحالة استخدام واحدة، اكتب وصفاً محدّداً، اختبر التفعيل، وكرّر. 15 إلى 30 دقيقة تفصلك عن أول skill عاملة.

@diyaa.albouzan.tech
ضياء البوزان | Tech42 صفحة