منشئ المهارات

---
name: skill-creator
description: دليل لإنشاء مهارات فعالة. يجب استخدام هذه المهارة عندما يرغب المستخدمون في إنشاء مهارة جديدة (أو تحديث مهارة موجودة) توسع قدرات Claude بمعرفة متخصصة أو سير عمل أو تكامل أدوات.
license: الشروط الكاملة في LICENSE.txt
---

# منشئ المهارات

توفر هذه المهارة إرشادات لإنشاء مهارات فعالة.

## حول المهارات

المهارات هي حزم معيارية ومستقلة توسع قدرات Claude من خلال توفير
معرفة متخصصة، وسير عمل، وأدوات. فكر فيها على أنها "أدلة تعريفية" لمجالات أو مهام محددة - فهي تحول Claude من وكيل للأغراض العامة إلى وكيل متخصص
مجهز بمعرفة إجرائية لا يمكن لأي نموذج امتلاكها بالكامل.

### ما توفره المهارات

1. سير عمل متخصص - إجراءات متعددة الخطوات لمجالات محددة
2. تكامل الأدوات - تعليمات للعمل مع تنسيقات ملفات أو APIs محددة
3. خبرة المجال - معرفة خاصة بالشركة، مخططات، منطق الأعمال
4. موارد مجمعة - نصوص برمجية، مراجع، وأصول للمهام المعقدة والمتكررة

## المبادئ الأساسية

### الإيجاز هو المفتاح

نافذة السياق هي منفعة عامة. تشارك المهارات نافذة السياق مع كل ما يحتاجه Claude: موجه النظام، سجل المحادثة، بيانات تعريف المهارات الأخرى، وطلب المستخدم الفعلي.

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

فضل الأمثلة الموجزة على الشروحات المطولة.

### تعيين درجات الحرية المناسبة

طابق مستوى التحديد مع هشاشة المهمة وتغيرها:

**حرية عالية (تعليمات نصية)**: استخدمها عندما تكون هناك طرق متعددة صالحة، وتعتمد القرارات على السياق، أو توجه الإرشادات التجريبية النهج.

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

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

فكر في Claude وهو يستكشف مسارًا: جسر ضيق به منحدرات يحتاج إلى حواجز حماية محددة (حرية منخفضة)، بينما يسمح الحقل المفتوح بالعديد من الطرق (حرية عالية).

### تشريح المهارة

تتكون كل مهارة من ملف SKILL.md مطلوب وموارد مجمعة اختيارية:

```
skill-name/
├── SKILL.md (مطلوب)
│   ├── بيانات تعريف YAML (مطلوب)
│   │   ├── name: (مطلوب)
│   │   └── description: (مطلوب)
│   └── تعليمات Markdown (مطلوب)
└── موارد مجمعة (اختياري)
    ├── scripts/          - كود قابل للتنفيذ (Python/Bash/etc.)
    ├── references/       - وثائق مخصصة للتحميل في السياق حسب الحاجة
    └── assets/           - ملفات مستخدمة في الإخراج (قوالب، أيقونات، خطوط، إلخ.)
```

#### SKILL.md (مطلوب)

يتكون كل ملف SKILL.md من:

- **Frontmatter** (YAML): يحتوي على حقلي `name` و `description`. هذه هي الحقول الوحيدة التي يقرأها Claude لتحديد متى يتم استخدام المهارة، وبالتالي من المهم جدًا أن تكون واضحة وشاملة في وصف ماهية المهارة، ومتى يجب استخدامها.
- **Body** (Markdown): تعليمات وإرشادات لاستخدام المهارة. يتم تحميلها فقط بعد تشغيل المهارة (إذا تم ذلك على الإطلاق).

#### الموارد المجمعة (اختياري)

##### النصوص البرمجية (`scripts/`)

كود قابل للتنفيذ (Python/Bash/etc.) للمهام التي تتطلب موثوقية حتمية أو يتم إعادة كتابتها بشكل متكرر.

- **متى يتم تضمينها**: عندما يتم إعادة كتابة نفس الكود بشكل متكرر أو عندما تكون هناك حاجة إلى موثوقية حتمية
- **مثال**: `scripts/rotate_pdf.py` لمهام تدوير PDF
- **الفوائد**: فعالة من حيث الرموز، حتمية، قد يتم تنفيذها دون تحميلها في السياق
- **ملاحظة**: قد لا يزال Claude بحاجة إلى قراءة النصوص البرمجية للتصحيح أو التعديلات الخاصة بالبيئة

##### المراجع (`references/`)

وثائق ومواد مرجعية مخصصة للتحميل حسب الحاجة في السياق لإبلاغ عملية Claude وتفكيره.

- **متى يتم تضمينها**: للوثائق التي يجب أن يرجع إليها Claude أثناء العمل
- **أمثلة**: `references/finance.md` لمخططات المالية، `references/mnda.md` لقالب اتفاقية عدم الإفصاح للشركة، `references/policies.md` لسياسات الشركة، `references/api_docs.md` لمواصفات API
- **حالات الاستخدام**: مخططات قواعد البيانات، وثائق API، معرفة المجال، سياسات الشركة، أدلة سير العمل التفصيلية
- **الفوائد**: يحافظ على ملف SKILL.md خفيفًا، ويتم تحميله فقط عندما يقرر Claude أنه ضروري
- **أفضل الممارسات**: إذا كانت الملفات كبيرة (>10 آلاف كلمة)، قم بتضمين أنماط بحث grep في SKILL.md
- **تجنب التكرار**: يجب أن تكون المعلومات موجودة إما في SKILL.md أو في ملفات المراجع، وليس في كليهما.

##### الأصول (`assets/`)

ملفات غير مخصصة للتحميل في السياق، بل تستخدم ضمن الإخراج الذي ينتجه Claude.

- **متى يتم تضمينها**: عندما تحتاج المهارة إلى ملفات سيتم استخدامها في الإخراج النهائي
- **أمثلة**: `assets/logo.png` لأصول العلامة التجارية، `assets/slides.pptx` لقوالب PowerPoint
- **حالات الاستخدام**: القوالب، الصور، الأيقونات، الكود الأساسي، الخطوط، المستندات النموذجية

### مبدأ تصميم الكشف التدريجي

تستخدم المهارات نظام تحميل من ثلاثة مستويات لإدارة السياق بكفاءة:

1. **البيانات الوصفية (الاسم + الوصف)** - دائمًا في السياق (~100 كلمة)
2. **نص SKILL.md** - عند تشغيل المهارة (<5 آلاف كلمة)
3. **الموارد المجمعة** - حسب حاجة Claude

حافظ على نص SKILL.md على الأساسيات وأقل من 500 سطر لتقليل تضخم السياق.

## عملية إنشاء المهارة

يتضمن إنشاء المهارة هذه الخطوات:

1. فهم المهارة بأمثلة ملموسة
2. تخطيط محتويات المهارة القابلة لإعادة الاستخدام (النصوص البرمجية، المراجع، الأصول)
3. تهيئة المهارة (تشغيل init_skill.py)
4. تحرير المهارة (تنفيذ الموارد وكتابة SKILL.md)
5. تجميع المهارة (تشغيل package_skill.py)
6. التكرار بناءً على الاستخدام الفعلي

### الخطوة 3: تهيئة المهارة

عند إنشاء مهارة جديدة من الصفر، قم دائمًا بتشغيل النص البرمجي `init_skill.py`:

```bash
scripts/init_skill.py <skill-name> --path <output-directory>
```

### الخطوة 4: تحرير المهارة

استشر هذه الأدلة المفيدة بناءً على احتياجات مهارتك:

- **العمليات متعددة الخطوات**: راجع references/workflows.md لسير العمل المتسلسل والمنطق الشرطي
- **تنسيقات إخراج محددة أو معايير جودة**: راجع references/output-patterns.md لأنماط القوالب والأمثلة

### الخطوة 5: تجميع المهارة

```bash
scripts/package_skill.py <path/to/skill-folder>
```

يقوم النص البرمجي للتجميع بالتحقق من الصحة وإنشاء ملف .skill للتوزيع.
FILE:references/workflows.md
# أنماط سير العمل

## سير العمل المتسلسل

للمهام المعقدة، قسّم العمليات إلى خطوات واضحة ومتسلسلة. غالبًا ما يكون من المفيد إعطاء Claude نظرة عامة على العملية في بداية SKILL.md:

```markdown
يتضمن ملء نموذج PDF هذه الخطوات:

1. تحليل النموذج (تشغيل analyze_form.py)
2. إنشاء تعيين الحقول (تحرير fields.json)
3. التحقق من صحة التعيين (تشغيل validate_fields.py)
4. ملء النموذج (تشغيل fill_form.py)
5. التحقق من الإخراج (تشغيل verify_output.py)
```

## سير العمل الشرطي

للمهام ذات المنطق المتفرع، وجه Claude عبر نقاط القرار:

```markdown
1. تحديد نوع التعديل:
   **إنشاء محتوى جديد؟** ← اتبع "سير عمل الإنشاء" أدناه
   **تحرير محتوى موجود؟** ← اتبع "سير عمل التحرير" أدناه

2. سير عمل الإنشاء: [الخطوات]
3. سير عمل التحرير: [الخطوات]
```
FILE:references/output-patterns.md
# أنماط الإخراج

استخدم هذه الأنماط عندما تحتاج المهارات إلى إنتاج إخراج متسق وعالي الجودة.

## نمط القالب

توفير قوالب لتنسيق الإخراج. طابق مستوى الصرامة مع احتياجاتك.

**للمتطلبات الصارمة (مثل استجابات API أو تنسيقات البيانات):**

```markdown
## هيكل التقرير

استخدم دائمًا هيكل القالب هذا بالضبط:

# [عنوان التحليل]

## ملخص تنفيذي
[نظرة عامة من فقرة واحدة على النتائج الرئيسية]

## النتائج الرئيسية
- النتيجة 1 مع البيانات الداعمة
- النتيجة 2 مع البيانات الداعمة
- النتيجة 3 مع البيانات الداعمة

## التوصيات
1. توصية عملية محددة
2. توصية عملية محددة
```

**للتوجيه المرن (عندما يكون التكيف مفيدًا):**

```markdown
## هيكل التقرير

هذا هو تنسيق افتراضي معقول، ولكن استخدم حكمك الأفضل:

# [عنوان التحليل]

## ملخص تنفيذي
[نظرة عامة]

## النتائج الرئيسية
[تكييف الأقسام بناءً على ما تكتشفه]

## التوصيات
[تكييفها مع السياق المحدد]

اضبط الأقسام حسب الحاجة لنوع التحليل المحدد.
```

## نمط الأمثلة

للمهارات التي تعتمد جودة الإخراج فيها على رؤية الأمثلة، قم بتوفير أزواج الإدخال/الإخراج:

```markdown
## تنسيق رسالة الالتزام

قم بإنشاء رسائل التزام باتباع هذه الأمثلة:

**مثال 1:**
الإدخال: تمت إضافة مصادقة المستخدم باستخدام رموز JWT
الإخراج:
```
feat(auth): implement JWT-based authentication

Add login endpoint and token validation middleware
```

**مثال 2:**
الإدخال: تم إصلاح خطأ حيث كانت التواريخ تُعرض بشكل غير صحيح في التقارير
الإخراج:
```
fix(reports): correct date formatting in timezone conversion

Use UTC timestamps consistently across report generation
```

اتبع هذا النمط: type(scope): وصف موجز، ثم شرح مفصل.
```

تساعد الأمثلة Claude على فهم النمط المطلوب ومستوى التفاصيل بشكل أوضح من الأوصاف وحدها.
FILE:scripts/quick_validate.py
#!/usr/bin/env python3
"""
نص برمجي للتحقق السريع من المهارات - نسخة مصغرة
"""

import sys
import os
import re
import yaml
from pathlib import Path

def validate_skill(skill_path):
    """التحقق الأساسي من المهارة"""
    skill_path = Path(skill_path)

    # التحقق من وجود SKILL.md
    skill_md = skill_path / 'SKILL.md'
    if not skill_md.exists():
        return False, "لم يتم العثور على SKILL.md"

    # قراءة والتحقق من صحة frontmatter
    content = skill_md.read_text()
    if not content.startswith('---'):
        return False, "لم يتم العثور على YAML frontmatter"

    # استخراج frontmatter
    match = re.match(r'^---\n(.*?)\n---', content, re.DOTALL)
    if not match:
        return False, "تنسيق frontmatter غير صالح"

    frontmatter_text = match.group(1)

    # تحليل YAML frontmatter
    try:
        frontmatter = yaml.safe_load(frontmatter_text)
        if not isinstance(frontmatter, dict):
            return False, "يجب أن يكون Frontmatter قاموس YAML"
    except yaml.YAMLError as e:
        return False, f"YAML غير صالح في frontmatter: {e}"

    # تعريف الخصائص المسموح بها
    ALLOWED_PROPERTIES = {'name', 'description', 'license', 'allowed-tools', 'metadata'}

    # التحقق من وجود خصائص غير متوقعة (باستثناء المفاتيح المتداخلة تحت metadata)
    unexpected_keys = set(frontmatter.keys()) - ALLOWED_PROPERTIES
    if unexpected_keys:
        return False, (
            f"مفتاح (مفاتيح) غير متوقعة في SKILL.md frontmatter: {', '.join(sorted(unexpected_keys))}. "
            f"الخصائص المسموح بها هي: {', '.join(sorted(ALLOWED_PROPERTIES))}"
        )

    # التحقق من الحقول المطلوبة
    if 'name' not in frontmatter:
        return False, "حقل 'name' مفقود في frontmatter"
    if 'description' not in frontmatter:
        return False, "حقل 'description' مفقود في frontmatter"

    # استخراج الاسم للتحقق من الصحة
    name = frontmatter.get('name', '')
    if not isinstance(name, str):
        return False, f"يجب أن يكون الاسم سلسلة نصية، تم الحصول على {type(name).__name__}"
    name = name.strip()
    if name:
        # التحقق من اصطلاح التسمية (حالة الواصلة: أحرف صغيرة مع واصلات)
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f"يجب أن يكون الاسم '{name}' بحالة الواصلة (أحرف صغيرة، أرقام، وواصلات فقط)"
        if name.startswith('-') or name.endswith('-') or '--' in name:
            return False, f"لا يمكن أن يبدأ الاسم '{name}' أو ينتهي بواصلة أو يحتوي على واصلات متتالية"
        # التحقق من طول الاسم (الحد الأقصى 64 حرفًا لكل مواصفة)
        if len(name) > 64:
            return False, f"الاسم طويل جدًا ({len(name)} حرفًا). الحد الأقصى هو 64 حرفًا."

    # استخراج الوصف والتحقق من صحته
    description = frontmatter.get('description', '')
    if not isinstance(description, str):
        return False, f"يجب أن يكون الوصف سلسلة نصية، تم الحصول على {type(description).__name__}"
    description = description.strip()
    if description:
        # التحقق من الأقواس الزاوية
        if '<' in description or '>' in description:
            return False, "لا يمكن أن يحتوي الوصف على أقواس زاوية (< أو >)"
        # التحقق من طول الوصف (الحد الأقصى 1024 حرفًا لكل مواصفة)
        if len(description) > 1024:
            return False, f"الوصف طويل جدًا ({len(description)} حرفًا). الحد الأقصى هو 1024 حرفًا."

    return True, "المهارة صالحة!"

if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("الاستخدام: python quick_validate.py <skill_directory>")
        sys.exit(1)
    
    valid, message = validate_skill(sys.argv[1])
    print(message)
    sys.exit(0 if valid else 1)
FILE:scripts/init_skill.py
#!/usr/bin/env python3
"""
مهيئ المهارات - ينشئ مهارة جديدة من قالب

الاستخدام:
    init_skill.py <skill-name> --path <path>

أمثلة:
    init_skill.py my-new-skill --path skills/public
    init_skill.py my-api-helper --path skills/private
    init_skill.py custom-skill --path /custom/location
"""

import sys
from pathlib import Path


SKILL_TEMPLATE = """---
name: {skill_name}
description: [TODO: شرح كامل ومفيد لما تفعله المهارة ومتى يجب استخدامها. قم بتضمين متى يجب استخدام هذه المهارة - سيناريوهات محددة، أنواع ملفات، أو مهام تؤدي إلى تشغيلها.]
---

# {skill_title}

## نظرة عامة

[TODO: جملة أو جملتان تشرحان ما تمكنه هذه المهارة]

## الموارد

تتضمن هذه المهارة أدلة موارد مثال توضح كيفية تنظيم أنواع مختلفة من الموارد المجمعة:

### scripts/
كود قابل للتنفيذ (Python/Bash/etc.) يمكن تشغيله مباشرة لأداء عمليات محددة.

### references/
وثائق ومواد مرجعية مخصصة للتحميل في السياق لإبلاغ عملية Claude وتفكيره.

### assets/
ملفات غير مخصصة للتحميل في السياق، بل تستخدم ضمن الإخراج الذي ينتجه Claude.

---

**يمكن حذف أي أدلة غير ضرورية.** لا تتطلب كل مهارة جميع أنواع الموارد الثلاثة.
"""

EXAMPLE_SCRIPT = '''#!/usr/bin/env python3
"""
نص برمجي مساعد مثال لـ {skill_name}

هذا نص برمجي نائب يمكن تنفيذه مباشرة.
استبدله بالتنفيذ الفعلي أو احذفه إذا لم تكن هناك حاجة إليه.
"""

def main():
    print("هذا نص برمجي مثال لـ {skill_name}")
    # TODO: أضف منطق النص البرمجي الفعلي هنا

if __name__ == "__main__":
    main()
'''

EXAMPLE_REFERENCE = """# وثائق مرجعية لـ {skill_title}

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

EXAMPLE_ASSET = """# ملف أصل مثال

يمثل هذا النائب مكان تخزين ملفات الأصول.
استبدله بملفات الأصول الفعلية (القوالب، الصور، الخطوط، إلخ.) أو احذفه إذا لم تكن هناك حاجة إليه.
"""


def title_case_skill_name(skill_name):
    """تحويل اسم المهارة الموصول بشرطة إلى حالة العنوان للعرض."""
    return ' '.join(word.capitalize() for word in skill_name.split('-'))


def init_skill(skill_name, path):
    """تهيئة دليل مهارة جديد باستخدام قالب SKILL.md."""
    skill_dir = Path(path).resolve() / skill_name

    if skill_dir.exists():
        print(f"❌ خطأ: دليل المهارة موجود بالفعل: {skill_dir}")
        return None

    try:
        skill_dir.mkdir(parents=True, exist_ok=False)
        print(f"✅ تم إنشاء دليل المهارة: {skill_dir}")
    except Exception as e:
        print(f"❌ خطأ في إنشاء الدليل: {e}")
        return None

    skill_title = title_case_skill_name(skill_name)
    skill_content = SKILL_TEMPLATE.format(skill_name=skill_name, skill_title=skill_title)

    skill_md_path = skill_dir / 'SKILL.md'
    try:
        skill_md_path.write_text(skill_content)
        print("✅ تم إنشاء SKILL.md")
    except Exception as e:
        print(f"❌ خطأ في إنشاء SKILL.md: {e}")
        return None

    try:
        scripts_dir = skill_dir / 'scripts'
        scripts_dir.mkdir(exist_ok=True)
        example_script = scripts_dir / 'example.py'
        example_script.write_text(EXAMPLE_SCRIPT.format(skill_name=skill_name))
        example_script.chmod(0o755)
        print("✅ تم إنشاء scripts/example.py")

        references_dir = skill_dir / 'references'
        references_dir.mkdir(exist_ok=True)
        example_reference = references_dir / 'api_reference.md'
        example_reference.write_text(EXAMPLE_REFERENCE.format(skill_title=skill_title))
        print("✅ تم إنشاء references/api_reference.md")

        assets_dir = skill_dir / 'assets'
        assets_dir.mkdir(exist_ok=True)
        example_asset = assets_dir / 'example_asset.txt'
        example_asset.write_text(EXAMPLE_ASSET)
        print("✅ تم إنشاء assets/example_asset.txt")
    except Exception as e:
        print(f"❌ خطأ في إنشاء أدلة الموارد: {e}")
        return None

    print(f"\n✅ تم تهيئة المهارة '{skill_name}' بنجاح في {skill_dir}")
    return skill_dir


def main():
    if len(sys.argv) < 4 or sys.argv[2] != '--path':
        print("الاستخدام: init_skill.py <skill-name> --path <path>")
        sys.exit(1)

    skill_name = sys.argv[1]
    path = sys.argv[3]

    print(f"🚀 تهيئة المهارة: {skill_name}")
    print(f"   الموقع: {path}")
    print()

    result = init_skill(skill_name, path)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()
FILE:scripts/package_skill.py
#!/usr/bin/env python3
"""
حزمة المهارات - تنشئ ملف .skill قابل للتوزيع من مجلد مهارة

الاستخدام:
    python utils/package_skill.py <path/to/skill-folder> [output-directory]

مثال:
    python utils/package_skill.py skills/public/my-skill
    python utils/package_skill.py skills/public/my-skill ./dist
"""

import sys
import zipfile
from pathlib import Path
from quick_validate import validate_skill


def package_skill(skill_path, output_dir=None):
    """تجميع مجلد مهارة في ملف .skill."""
    skill_path = Path(skill_path).resolve()

    if not skill_path.exists():
        print(f"❌ خطأ: لم يتم العثور على مجلد المهارة: {skill_path}")
        return None

    if not skill_path.is_dir():
        print(f"❌ خطأ: المسار ليس دليلاً: {skill_path}")
        return None

    skill_md = skill_path / "SKILL.md"
    if not skill_md.exists():
        print(f"❌ خطأ: لم يتم العثور على SKILL.md في {skill_path}")
        return None

    print("🔍 التحقق من صحة المهارة...")
    valid, message = validate_skill(skill_path)
    if not valid:
        print(f"❌ فشل التحقق من الصحة: {message}")
        print("   يرجى إصلاح أخطاء التحقق من الصحة قبل التجميع.")
        return None
    print(f"✅ {message}\n")

    skill_name = skill_path.name
    if output_dir:
        output_path = Path(output_dir).resolve()
        output_path.mkdir(parents=True, exist_ok=True)
    else:
        output_path = Path.cwd()

    skill_filename = output_path / f"{skill_name}.skill"

    try:
        with zipfile.ZipFile(skill_filename, 'w', zipfile.ZIP_DEFLATED) as zipf:
            for file_path in skill_path.rglob('*'):
                if file_path.is_file():
                    arcname = file_path.relative_to(skill_path.parent)
                    zipf.write(file_path, arcname)
                    print(f"  تمت الإضافة: {arcname}")

        print(f"\n✅ تم تجميع المهارة بنجاح في: {skill_filename}")
        return skill_filename

    except Exception as e:
        print(f"❌ خطأ في إنشاء ملف .skill: {e}")
        return None


def main():
    if len(sys.argv) < 2:
        print("الاستخدام: python utils/package_skill.py <path/to/skill-folder> [output-directory]")
        sys.exit(1)

    skill_path = sys.argv[1]
    output_dir = sys.argv[2] if len(sys.argv) > 2 else None

    print(f"📦 تجميع المهارة: {skill_path}")
    if output_dir:
        print(f"   دليل الإخراج: {output_dir}")
    print()

    result = package_skill(skill_path, output_dir)
    sys.exit(0 if result else 1)


if __name__ == "__main__":
    main()