meta

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

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

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

## عن المهارات

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

### ماذا تقدّم المهارات

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

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

### الاختصار هو الأساس

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

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

فضّل الأمثلة المختصرة على الشروحات المطوّلة.

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

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

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

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

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

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

### مكوّنات المهارة

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

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

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

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

- **Frontmatter** (YAML): يحتوي على حقلي `name` و`description`. هذان الحقلان فقط هما ما يقرأه Claude لتحديد وقت استخدام المهارة؛ لذلك من المهم جدًا أن يكون الوصف واضحًا وشاملًا لما تفعله المهارة ومتى ينبغي استخدامها.
- **المتن** (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 أنها مطلوبة
- **أفضل ممارسة**: إذا كانت الملفات كبيرة، أكثر من 10k كلمة، فأضف أنماط بحث grep داخل SKILL.md
- **تجنّب التكرار**: يجب أن تكون المعلومة إما في SKILL.md أو في ملفات المراجع، وليس في الاثنين معًا.

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

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

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

### مبدأ التصميم بالتدرّج في الإفصاح

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

1. **البيانات التعريفية (name + description)** - موجودة دائمًا في السياق، حوالي 100 كلمة
2. **متن SKILL.md** - عند تفعيل المهارة، أقل من 5k كلمة
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
## صيغة رسالة commit

أنشئ رسائل commit وفق هذه الأمثلة:

**مثال 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:
        unexpected = ', '.join(sorted(unexpected_keys))
        allowed = ', '.join(sorted(ALLOWED_PROPERTIES))
        return False, (
            f'مفاتيح غير متوقعة في frontmatter داخل SKILL.md: {unexpected}. '
            f'الخصائص المسموحة هي: {allowed}'
        )

    # التحقق من الحقول المطلوبة
    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'يجب أن يكون name نصًا، والقيمة الحالية من نوع {type(name).__name__}'
    name = name.strip()
    if name:
        # التحقق من اصطلاح التسمية، hyphen-case: أحرف صغيرة مع شرطات
        if not re.match(r'^[a-z0-9-]+$', name):
            return False, f'الاسم {name} يجب أن يكون بصيغة hyphen-case، أحرف صغيرة وأرقام وشرطات فقط'
        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'يجب أن يكون description نصًا، والقيمة الحالية من نوع {type(description).__name__}'
    description = description.strip()
    if description:
        # التحقق من الأقواس الزاوية
        if '<' in description or '>' in description:
            return False, 'لا يمكن أن يحتوي description على أقواس زاوية (< أو >)'
        # التحقق من طول الوصف، الحد الأقصى 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):
    '''تحويل اسم المهارة المكتوب بشرطات إلى Title Case للعرض.'''
    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()
    print(f'✅ تمت تهيئة المهارة {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}')
    print()

    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()
        print(f'✅ تم تغليف المهارة بنجاح إلى: {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()