> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crewai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# المهارات

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

## نظرة عامة

المهارات هي مجلدات مستقلة توفر للوكلاء **تعليمات وإرشادات ومواد مرجعية خاصة بالمجال**. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown.

عند التفعيل، يتم حقن تعليمات المهارة مباشرة في إرشادات مهمة الوكيل — مما يمنح الوكيل خبرة دون الحاجة لأي تغييرات في الكود.

<Note type="info" title="المهارات مقابل الأدوات — التمييز الأساسي">
  **المهارات ليست أدوات.** هذه هي نقطة الارتباك الأكثر شيوعًا.

  * **المهارات** تحقن *تعليمات وسياق* في إرشادات الوكيل. تخبر الوكيل *كيف يفكر* في مشكلة ما.
  * **الأدوات** تمنح الوكيل *دوال قابلة للاستدعاء* لاتخاذ إجراءات (البحث، قراءة الملفات، استدعاء APIs).

  غالبًا ما تحتاج **كليهما**: مهارات للخبرة، وأدوات للإجراء. يتم تكوينهما بشكل مستقل ويُكمّلان بعضهما.
</Note>

***

## البداية السريعة

### 1. إنشاء مجلد المهارة

```
skills/
└── code-review/
    ├── SKILL.md          # مطلوب — التعليمات
    ├── references/       # اختياري — مستندات مرجعية
    │   └── style-guide.md
    └── scripts/          # اختياري — سكربتات قابلة للتنفيذ
```

### 2. كتابة SKILL.md الخاص بك

```markdown theme={null}
---
name: code-review
description: Guidelines for conducting thorough code reviews with focus on security and performance.
metadata:
  author: your-team
  version: "1.0"
---

## إرشادات مراجعة الكود

عند مراجعة الكود، اتبع قائمة التحقق هذه:

1. **الأمان**: تحقق من ثغرات الحقن وتجاوز المصادقة وكشف البيانات
2. **الأداء**: ابحث عن استعلامات N+1 والتخصيصات غير الضرورية والاستدعاءات المحظورة
3. **القابلية للقراءة**: تأكد من وضوح التسمية والتعليقات المناسبة والأسلوب المتسق
4. **الاختبارات**: تحقق من تغطية اختبار كافية للوظائف الجديدة

### مستويات الخطورة
- **حرج**: ثغرات أمنية، مخاطر فقدان البيانات → حظر الدمج
- **رئيسي**: مشاكل أداء، أخطاء منطقية → طلب تغييرات
- **ثانوي**: مسائل أسلوبية، اقتراحات تسمية → الموافقة مع تعليقات
```

### 3. ربطها بوكيل

```python theme={null}
from crewai import Agent
from crewai_tools import GithubSearchTool, FileReadTool

reviewer = Agent(
    role="Senior Code Reviewer",
    goal="Review pull requests for quality and security issues",
    backstory="Staff engineer with expertise in secure coding practices.",
    skills=["./skills"],                          # يحقن إرشادات المراجعة
    tools=[GithubSearchTool(), FileReadTool()],   # يسمح للوكيل بقراءة الكود
)
```

الوكيل الآن لديه **خبرة** (من المهارة) و**قدرات** (من الأدوات) معًا.

***

## المهارات + الأدوات: العمل معًا

إليك أنماط شائعة توضح كيف تُكمّل المهارات والأدوات بعضهما:

### النمط 1: مهارات فقط (خبرة المجال، بدون إجراءات مطلوبة)

استخدم عندما يحتاج الوكيل لتعليمات محددة لكن لا يحتاج لاستدعاء خدمات خارجية:

```python theme={null}
agent = Agent(
    role="Technical Writer",
    goal="Write clear API documentation",
    backstory="Expert technical writer",
    skills=["./skills/api-docs-style"],  # إرشادات وقوالب الكتابة
    # لا حاجة لأدوات — الوكيل يكتب بناءً على السياق المقدم
)
```

### النمط 2: أدوات فقط (إجراءات، بدون خبرة خاصة)

استخدم عندما يحتاج الوكيل لاتخاذ إجراءات لكن لا يحتاج لتعليمات مجال محددة:

```python theme={null}
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

agent = Agent(
    role="Web Researcher",
    goal="Find information about a topic",
    backstory="Skilled at finding information online",
    tools=[SerperDevTool(), ScrapeWebsiteTool()],  # يمكنه البحث والاستخراج
    # لا حاجة لمهارات — البحث العام لا يحتاج إرشادات خاصة
)
```

### النمط 3: مهارات + أدوات (خبرة وإجراءات)

النمط الأكثر شيوعًا في العالم الحقيقي. المهارة توفر *كيف* تقترب من العمل؛ الأدوات توفر *ما* يمكن للوكيل فعله:

```python theme={null}
from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool

analyst = Agent(
    role="Security Analyst",
    goal="Audit infrastructure for vulnerabilities",
    backstory="Expert in cloud security and compliance",
    skills=["./skills/security-audit"],   # منهجية وقوائم تحقق التدقيق
    tools=[
        SerperDevTool(),                  # البحث عن ثغرات معروفة
        FileReadTool(),                   # قراءة ملفات التكوين
        CodeInterpreterTool(),            # تشغيل سكربتات التحليل
    ],
)
```

### النمط 4: مهارات + MCP

المهارات تعمل مع خوادم MCP بنفس الطريقة التي تعمل بها مع الأدوات:

```python theme={null}
agent = Agent(
    role="Data Analyst",
    goal="Analyze customer data and generate reports",
    backstory="Expert data analyst with strong statistical background",
    skills=["./skills/data-analysis"],           # منهجية التحليل
    mcps=["https://data-warehouse.example.com/sse"],  # وصول بيانات عن بُعد
)
```

### النمط 5: مهارات + تطبيقات

المهارات يمكن أن توجّه كيف يستخدم الوكيل تكاملات المنصة:

```python theme={null}
agent = Agent(
    role="Customer Support Agent",
    goal="Respond to customer inquiries professionally",
    backstory="Experienced support representative",
    skills=["./skills/support-playbook"],  # قوالب الردود وقواعد التصعيد
    apps=["gmail", "zendesk"],             # يمكنه إرسال رسائل بريد وتحديث التذاكر
)
```

***

## المهارات على مستوى الطاقم

يمكن تعيين المهارات على الطاقم لتُطبّق على **جميع الوكلاء**:

```python theme={null}
from crewai import Crew

crew = Crew(
    agents=[researcher, writer, reviewer],
    tasks=[research_task, write_task, review_task],
    skills=["./skills"],  # جميع الوكلاء يحصلون على هذه المهارات
)
```

المهارات على مستوى الوكيل لها الأولوية — إذا تم اكتشاف نفس المهارة في كلا المستويين، يتم استخدام نسخة الوكيل.

***

## تنسيق SKILL.md

```markdown theme={null}
---
name: my-skill
description: وصف قصير لما تفعله هذه المهارة ومتى تُستخدم.
license: Apache-2.0                    # اختياري
compatibility: crewai>=0.1.0          # اختياري
metadata:                              # اختياري
  author: your-name
  version: "1.0"
allowed-tools: web-search file-read   # اختياري، تجريبي
---

التعليمات للوكيل تُكتب هنا. يتم حقن محتوى Markdown هذا
في إرشادات الوكيل عند تفعيل المهارة.
```

### حقول البيانات الوصفية

| الحقل           | مطلوب | الوصف                                                              |
| :-------------- | :---- | :----------------------------------------------------------------- |
| `name`          | نعم   | 1-64 حرف. أحرف صغيرة أبجدية رقمية وشرطات. يجب أن يطابق اسم المجلد. |
| `description`   | نعم   | 1-1024 حرف. يصف ما تفعله المهارة ومتى تُستخدم.                     |
| `license`       | لا    | اسم الترخيص أو مرجع لملف ترخيص مضمّن.                              |
| `compatibility` | لا    | حد أقصى 500 حرف. متطلبات البيئة (منتجات، حزم، شبكة).               |
| `metadata`      | لا    | تعيين مفتاح-قيمة نصي عشوائي.                                       |
| `allowed-tools` | لا    | قائمة أدوات معتمدة مسبقًا مفصولة بمسافات. تجريبي.                  |

***

## هيكل المجلد

```
my-skill/
├── SKILL.md            # مطلوب — البيانات الوصفية + التعليمات
├── scripts/            # اختياري — سكربتات قابلة للتنفيذ
├── references/         # اختياري — مستندات مرجعية
└── assets/             # اختياري — ملفات ثابتة (إعدادات، بيانات)
```

يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة.

***

## المهارات المحمّلة مسبقًا

للمزيد من التحكم، يمكنك اكتشاف المهارات وتفعيلها برمجيًا:

```python theme={null}
from pathlib import Path
from crewai.skills import discover_skills, activate_skill

# اكتشاف جميع المهارات في مجلد
skills = discover_skills(Path("./skills"))

# تفعيلها (تحميل محتوى SKILL.md الكامل)
activated = [activate_skill(s) for s in skills]

# تمرير إلى وكيل
agent = Agent(
    role="Researcher",
    goal="Find relevant information",
    backstory="An expert researcher.",
    skills=activated,
)
```

***

## كيف يتم تحميل المهارات

تستخدم المهارات **الكشف التدريجي** — تحمّل فقط ما هو مطلوب في كل مرحلة:

| المرحلة  | ما يتم تحميله                       | متى                 |
| :------- | :---------------------------------- | :------------------ |
| الاكتشاف | الاسم، الوصف، حقول البيانات الوصفية | `discover_skills()` |
| التفعيل  | نص محتوى SKILL.md الكامل            | `activate_skill()`  |

أثناء التنفيذ العادي للوكيل (تمرير مسارات المجلدات عبر `skills=["./skills"]`)، يتم اكتشاف المهارات وتفعيلها تلقائيًا. التحميل التدريجي مهم فقط عند استخدام الواجهة البرمجية.

***

## المهارات مقابل المعرفة

كلا المهارات والمعرفة تُعدّل إرشادات الوكيل، لكنهما يخدمان أغراضًا مختلفة:

| الجانب          | المهارات                              | المعرفة                                       |
| :-------------- | :------------------------------------ | :-------------------------------------------- |
| **ما توفره**    | تعليمات، إجراءات، إرشادات             | حقائق، بيانات، معلومات                        |
| **كيف تُخزّن**  | ملفات Markdown (SKILL.md)             | مُضمّنة في مخزن متجهي (ChromaDB)              |
| **كيف تُسترجع** | يتم حقن المحتوى الكامل في الإرشادات   | البحث الدلالي يجد الأجزاء ذات الصلة           |
| **الأفضل لـ**   | المنهجيات، قوائم التحقق، أدلة الأسلوب | مستندات الشركة، معلومات المنتج، بيانات مرجعية |
| **يُعيّن عبر**  | `skills=["./skills"]`                 | `knowledge_sources=[source]`                  |

**القاعدة العامة:** إذا كان الوكيل يحتاج لاتباع *عملية*، استخدم مهارة. إذا كان يحتاج للرجوع إلى *بيانات*، استخدم المعرفة.

***

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

<AccordionGroup>
  <Accordion title="هل أحتاج لتعيين المهارات والأدوات معًا؟">
    يعتمد على حالة الاستخدام. المهارات والأدوات **مستقلتان** — يمكنك استخدام أيّ منهما أو كليهما أو لا شيء.

    * **مهارات فقط**: عندما يحتاج الوكيل خبرة لكن لا يحتاج إجراءات خارجية (مثال: الكتابة بإرشادات أسلوبية)
    * **أدوات فقط**: عندما يحتاج الوكيل إجراءات لكن لا يحتاج منهجية خاصة (مثال: بحث بسيط على الويب)
    * **كليهما**: عندما يحتاج الوكيل خبرة وإجراءات (مثال: تدقيق أمني بقوائم تحقق محددة وقدرة على فحص الكود)
  </Accordion>

  <Accordion title="هل توفر المهارات أدوات تلقائيًا؟">
    **لا.** حقل `allowed-tools` في SKILL.md هو بيانات وصفية تجريبية فقط — لا يُنشئ أو يحقن أي أدوات. يجب عليك دائمًا تعيين الأدوات بشكل منفصل عبر `tools=[]` أو `mcps=[]` أو `apps=[]`.
  </Accordion>

  <Accordion title="ماذا يحدث إذا عيّنت نفس المهارة على كل من الوكيل والطاقم؟">
    المهارة على مستوى الوكيل لها الأولوية. يتم إزالة التكرار حسب الاسم — مهارات الوكيل تُعالج أولاً، لذا إذا ظهر نفس اسم المهارة في كلا المستويين، تُستخدم نسخة الوكيل.
  </Accordion>

  <Accordion title="ما الحجم الأقصى لمحتوى SKILL.md؟">
    هناك تحذير ناعم عند 50,000 حرف، لكن بدون حد صارم. حافظ على تركيز المهارات وإيجازها للحصول على أفضل النتائج — الحقن الكبيرة في الإرشادات قد تُشتت انتباه الوكيل.
  </Accordion>
</AccordionGroup>