في كل فريق مهام تتكرر بخطوات ثابتة لا يعرفها إلا من عمل في المشروع: كيف تكتب ملاحظات الإصدار Release Notes بصيغة الفريق، وكيف تكتب ترحيل قاعدة البيانات Migration مع ملف الرجوع، وما هي الكلمات التي تستعملها في رسائل الواجهة العربية. والمكان الأول الذي يفكر فيه المطور ليعلم الوكيل Agent هذه الخطوات هو ملف تعليمات المشروع AGENTS.md، وهو مكان مناسب للقواعد التي تنطبق على كل مهمة، ولكنه مكان سيئ لخطوات مهمة تحدث مرة في الأسبوع، لأن الملف يرسل في كل طلب، فتدفع ثمن تعليمات الترحيل وأنت تصلح خطأً في CSS، ويطول الملف حتى يقطع كما رأينا في مقال ملف التعليمات Instructions. والمهارات Agent Skills هي الحل الذي ظهر لهذه المشكلة: مجلد فيه تعليمات المهمة وملفاتها، لا يرى الوكيل منه في البداية إلا اسمه ووصفه، فإذا جاءت مهمة تناسبه قرأ الباقي.
وفي هذا المقال نبني ثلاث مهارات حقيقية حسب مواصفة Agent Skills، ونفحصها بالمكتبة المرجعية للمواصفة، ثم نرى بعيوننا كيف يضعها Codex CLI في طلبه، ثم نقيس على نموذج محلي صغير سؤالين يهمان كل من يكتب مهارة: هل يختار النموذج Model المهارة الصحيحة من وصفها وحده؟ وإذا اختارها، هل يتبع ما فيها؟
في هذا المقال سوف نتناول:
- ما هي المهارة Skill، ومن أين جاءت، وأي الأدوات تدعمها اليوم.
- بنية المجلد وملف
SKILL.mdوالحقول المطلوبة وحدود كل حقل. - الإفصاح التدريجي Progressive Disclosure: ثلاث درجات تدخل بها المهارة السياق Context.
- الفحص بالأداة المرجعية، والأخطاء التي ترفضها.
- كيف يعرض Codex المهارات في طلبه، وكم يكلف كل واحدة.
- تجربتان على نموذج محلي: اختيار المهارة من الوصف، واتباع تعليماتها بعد الاختيار.
- الفرق بين المهارة وملف التعليمات وأداة MCP والوكيل الفرعي، ومخاطر المهارات من مصادر غير موثوقة.
ما هي المهارة Agent Skill؟
المهارة مجلد فيه ملف واحد مطلوب اسمه SKILL.md، وفي أوله بيانات وصفية Metadata بصيغة YAML أهمها الاسم والوصف، وبعدها تعليمات المهمة بصيغة Markdown، ويمكن أن يحتوي المجلد ملفات أخرى يحتاجها الوكيل أثناء المهمة، مثل سكربت يشغله أو مرجع يقرؤه أو قالب ينسخه. وفكرتها بسيطة: بدل أن تشرح للوكيل كيف يكتب ملاحظات الإصدار في كل مرة، أو تضع الشرح في ملف يرسل مع كل طلب، تكتب الشرح مرة في مجلد، ويقرؤه الوكيل في اليوم الذي يحتاجه فقط.
وقدمت Anthropic المهارات في Claude في أكتوبر 2025، ثم شرحتها في مقالها الهندسي عن المهارات المنشور في 16 أكتوبر 2025، ثم نشرتها مواصفة مفتوحة في 18 ديسمبر 2025 كما يذكر تحديث على المقال نفسه، والمواصفة Spec اليوم في موقع agentskills.io ومستودعها على GitHub. وفي نوفمبر 2026 تقرأ المهارات أدوات كثيرة من شركات مختلفة: Claude Code من المجلد .claude/skills/، وCodex من .agents/skills/، وGitHub Copilot من .github/skills أو .claude/skills أو .agents/skills، وOpenCode وغيرها، أي أن المهارة التي تكتبها مرة تعمل في أكثر من أداة بنقل المجلد أو بوضعه في المسار الذي تقرؤه.
وقد يتساءل البعض: إذا كانت المهارة تعليمات في ملف، فما الفرق بينها وبين أن أقول للوكيل «اقرأ الملف docs/release.md ثم اتبعه»؟ والإجابة أن الفرق في من يقرر متى تقرأ: في الحالة الثانية أنت تتذكر الملف وتطلبه، وفي المهارة يرى الوكيل قائمة المهارات ووصف كل واحدة من بداية الجلسة، فيقرر بنفسه أن طلبك عن ملاحظات الإصدار وأن هذه المهارة تناسبه. وهذا القرار هو أضعف نقطة في المهارات، وهو ما قسناه في التجربة الأولى.
وفي مقال بيئة تشغيل الوكيل رأينا أن الوكيل حلقة تستدعي أدوات، وفي مقال ملف التعليمات رأينا أن ما يحمل في كل طلب له ثمن في السياق والزمن، والمهارة تقع بين الاثنين: هي تعليمات مثل ملف AGENTS.md، ولكنها تحمل مثل الأداة، أي عندما يطلبها النموذج. ولذلك فإن كل ما تعلمناه عن الأدوات ينطبق عليها، فالوصف هو ما يقرأه النموذج ليقرر، والاسم يجب أن يكون واضحاً، والمخرج يجب أن يكون صغيراً، وكل ما تعلمناه عن ملف التعليمات ينطبق عليها أيضاً، فاكتب فيها ما لا يعرفه النموذج، واترك ما يعرفه.
بنية المجلد وملف SKILL.md
المواصفة تحدد البنية التالية، والمجلدات الثلاثة الاختيارية أسماء مقترحة وليست مطلوبة:
release-notes/
├── SKILL.md # مطلوب: البيانات الوصفية والتعليمات
├── scripts/ # اختياري: كود يشغله الوكيل
├── references/ # اختياري: مراجع يقرؤها عند الحاجة
└── assets/ # اختياري: قوالب وملفات ثابتةوالحقول في رأس الملف كما في المواصفة، اثنان مطلوبان وأربعة اختيارية:
| الحقل | مطلوب؟ | الحدود |
|---|---|---|
name | نعم | من 1 إلى 64 حرفاً، حروف إنجليزية صغيرة وأرقام وشرطة - فقط، لا يبدأ بشرطة ولا ينتهي بها، ولا شرطتان متتاليتان، ويجب أن يطابق اسم المجلد |
description | نعم | من 1 إلى 1024 حرفاً، يقول ماذا تفعل المهارة ومتى تستعمل |
license | لا | اسم الرخصة أو ملف مرفق فيه نصها |
compatibility | لا | حتى 500 حرف، متطلبات البيئة مثل الأدوات أو الوصول إلى الشبكة |
metadata | لا | أزواج من مفتاح وقيمة نصية لأي بيانات إضافية |
allowed-tools | لا | قائمة أدوات مسموحة مسبقاً مفصولة بمسافات، وهو حقل تجريبي يختلف دعمه بين الأدوات |
والمهارة الأولى في المختبر تكتب ملاحظات الإصدار من تاريخ git، وهي كاملة كما يلي:
---
name: release-notes
description: Writes the release notes of this repository from the git history since the last tag, in the team's format (Added, Fixed, Changed, Security). Use when the user asks for release notes, a changelog entry, or "what changed since v1.4".
license: MIT
metadata:
owner: platform-team
version: "1.0"
---
# Release notes
1. Run `scripts/collect.sh` from the repository root. It prints one line per commit since the last tag:
`<type>|<short hash>|<subject>`.
2. Group the lines by type: `feat` goes under **Added**, `fix` under **Fixed**, `refactor` and `perf` under
**Changed**, and any subject that mentions `CVE` or `security` under **Security**.
3. Drop commits whose type is `chore`, `test` or `ci`. Users do not care about them.
4. Write each item as one sentence a user understands, followed by the short hash in parentheses.
5. Start the file with `## <next version> (<today's date, YYYY-MM-DD>)`. Ask for the version if it is not given.
Never invent an item that is not in the script's output.والسكربت الذي تشير إليه في المجلد scripts/ كما يلي:
#!/bin/sh
# Commits since the last tag as type|hash|subject (conventional commit prefixes).
last=$(git describe --tags --abbrev=0 2>/dev/null || git rev-list --max-parents=0 HEAD)
git log --format='%h|%s' "$last"..HEAD | sed -E 's/^([0-9a-f]+)\|([a-z]+)(\([^)]*\))?!?: /\2|\1|/'في المهارة أعلاه لاحظ التالي:
- الوصف فيه شيئان كما تطلب المواصفة: ماذا تفعل المهارة، أي ملاحظات الإصدار من تاريخ git بصيغة الفريق، ومتى تستعمل، أي عندما يطلب المستخدم ملاحظات الإصدار أو سجل التغييرات أو «ماذا تغير منذ v1.4». والجزء الثاني أهم، لأن النموذج يقرر من الوصف وحده.
- العمل الثابت، أي جمع الـ commits من آخر وسم Tag وتقسيمها، في سكربت، والعمل الذي يحتاج فهماً، أي كتابة جملة يفهمها المستخدم، في التعليمات. والسبب أن السكربت يعطي النتيجة نفسها كل مرة ولا يكلف توكنات إلا لمخرجه، أما النموذج فقد يخطئ في عد الـ commits.
- السطر الأخير «لا تخترع بنداً ليس في مخرج السكربت» قاعدة تمنع أشهر خطأ في هذه المهمة.
والمهارة الثانية db-migration تكتب ترحيل PostgreSQL مع ملف الرجوع، وتشير إلى مرجع منفصل بقواعد التسمية في references/naming.md، والثالثة arabic-ui-text تكتب نصوص الواجهة العربية بأسلوب المنتج، والثلاث كلها في مجلد المختبر.
مهارة ترحيل قاعدة البيانات ومرجعها
المهارة الثانية هي التي استعملناها في التجربة الثانية، ولذلك نعرضها كاملة، ونصها كما يلي:
---
name: db-migration
description: Creates a PostgreSQL schema migration for this repository (new table, column, index or constraint) with its rollback, following the naming rules in references/naming.md. Use when the user asks to change the database schema or add a migration. Not for querying data.
---
# Database migration
1. Read `references/naming.md` before you name anything.
2. Create two files in `migrations/`: `<YYYYMMDDHHMM>_<snake_case_summary>.up.sql` and the matching `.down.sql`.
3. The down file must undo the up file exactly. A migration without a working down file is not done.
4. Adding a column to a big table: add it as nullable first, backfill in a separate migration, then add `NOT NULL`.
5. Create indexes with `CREATE INDEX CONCURRENTLY` and put them in their own migration, because it cannot run
inside a transaction.
6. Never edit a migration that is already merged. Write a new one.والمرجع الذي يشير إليه في السطر الأول كما يلي:
# Naming rules
- Tables: plural snake_case (`invoices`, `invoice_lines`).
- Primary key: `id bigint generated always as identity`.
- Foreign keys: `<singular table>_id` (`invoice_id`), constraint `fk_<table>_<column>`.
- Indexes: `ix_<table>_<columns>`; unique indexes `ux_<table>_<columns>`.
- Timestamps: `created_at` and `updated_at`, type `timestamptz`, default `now()`.
- Money: `bigint` in halalas, column name ends with `_halalas`.في المهارة أعلاه لاحظ التالي:
- الوصف ينتهي بجملة «Not for querying data»، وهذه الجملة تحدد حدود المهارة، لأن طلباً مثل «كم فاتورة عندنا؟» يذكر قاعدة البيانات أيضاً ولكنه لا يحتاج ترحيلاً، وسوف نرى في التجربة الأولى أن هذه الجملة هي الفرق بين الاختيار الصحيح والخاطئ.
- القواعد التي تحتاجها كل مهمة ترحيل، مثل ملف الرجوع والفهرس في ملف مستقل، في نص المهارة، أما التفاصيل التي تحتاج الرجوع إليها، مثل صيغة كل اسم، ففي المرجع، وهذا هو الإفصاح التدريجي داخل المهارة الواحدة.
- كل قاعدة معها سببها حيث يلزم، مثل أن
CREATE INDEX CONCURRENTLYلا يعمل داخل معاملة Transaction، لأن النموذج يتبع القاعدة التي يفهم سببها أكثر من القاعدة المجردة، وهي النصيحة نفسها التي نكتبها لزميل جديد.
الإفصاح التدريجي Progressive Disclosure
هذه هي الفكرة التي تجعل المهارات مختلفة عن ملف التعليمات، والمواصفة تصفها بثلاث درجات: البيانات الوصفية، أي الاسم والوصف، تحمل لكل المهارات عند بداية الجلسة، وتقدرها المواصفة بحوالي 100 توكن للمهارة، ثم نص SKILL.md كاملاً يحمل عندما يقرر الوكيل أن المهارة تلزم، وتنصح المواصفة بأن يكون أقل من 5000 توكن وأقل من 500 سطر، ثم الملفات المرفقة تحمل عند الحاجة فقط. وقسنا الملفات الثلاث في المختبر بترميز o200k_base، والمخرج سوف يكون كما يلي:
skills/arabic-ui-text/SKILL.md 203 tokens frontmatter 59
skills/db-migration/SKILL.md 212 tokens frontmatter 61
skills/db-migration/references/naming.md 127 tokens
skills/release-notes/SKILL.md 269 tokens frontmatter 81
skills/release-notes/scripts/collect.sh 99 tokens
all files 910أي أن الرؤوس الثلاثة معاً حوالي 200 توكن، بينما كل الملفات 910 توكنات. والفرق هنا صغير لأن المهارات صغيرة، ولكن تخيل عشرين مهارة، كل واحدة فيها تعليمات من 2000 توكن ومراجع من 5000، فالفرق يصبح بين ألفي توكن في كل طلب ومئة وأربعين ألفاً. والشكل التالي يبين الدرجات الثلاث بأرقام المختبر:

ولاحظ أن السكربت في الدرجة الثالثة مختلف عن المرجع، فالمرجع يقرأ فيدخل السياق، أما السكربت فيشغل، ولا يدخل السياق إلا مخرجه، ولذلك فإن العمل الذي يمكن أن يكتب كوداً مرة واحدة، مثل استخراج بيانات من ملف أو تحويل صيغة، أرخص في السياق وأدق في النتيجة إذا كان سكربتاً.
الفحص بالأداة المرجعية skills-ref
المواصفة لها مكتبة مرجعية بلغة Python اسمها skills-ref، ونسخة 0.1.1 على PyPI تثبت أمراً اسمه agentskills وليس skills-ref كما قد تتوقع من اسم الحزمة، وأول محاولة لنا فشلت بالرسالة skills-ref: not found لهذا السبب. والسكربت validate.sh يثبتها في Container ويفحص المهارات الثلاث، ثم مجلدين فيهما أخطاء مقصودة، والمخرج سوف يكون كما يلي:
$ agentskills validate skills/arabic-ui-text
Valid skill: skills/arabic-ui-text
exit 0
$ agentskills validate skills/db-migration
Valid skill: skills/db-migration
exit 0
$ agentskills validate skills/release-notes
Valid skill: skills/release-notes
exit 0
$ agentskills validate broken/Release_Notes
Validation failed for broken/Release_Notes:
- Skill name 'Release_Notes' must be lowercase
- Skill name 'Release_Notes' contains invalid characters. Only letters, digits, and hyphens are allowed.
exit 1
$ agentskills validate broken/db-migration
Validation failed for broken/db-migration:
- Directory name 'db-migration' must match skill name 'database-migration'
- Missing required field in frontmatter: description
exit 1في المخرج أعلاه لاحظ التالي:
- الاسم
Release_Notesرفض لسببين: الحروف الكبيرة، والشرطة السفلية_، والمواصفة تسمح بالحروف الصغيرة والأرقام والشرطة فقط. - المجلد الثاني فيه خطآن يقع فيهما من ينسخ مهارة ويغير اسمها: الاسم في الملف
database-migrationلا يطابق اسم المجلدdb-migration، والوصف غير موجود أصلاً. وبعض الأدوات تتسامح مع الخطأ الأول، ولكن المهارة دون وصف لن يختارها أي وكيل، لأنه لا يعرف متى تستعمل. - الأداة ترجع رمز خروج Exit Code غير صفر عند الخطأ، ولذلك يمكنك أن تضعها في خط النشر CI لكل Pull Request يغير مجلد المهارات.
وللأداة أمران آخران مفيدان: read-properties يطبع رأس الملف بصيغة JSON، وto-prompt يطبع النص الذي تقترح المواصفة أن يضعه المضيف في تعليمات النظام، ومخرجه لمهاراتنا الثلاث كما يلي، مختصراً:
<available_skills>
<skill>
<name>
arabic-ui-text
</name>
<description>
Writes or reviews Arabic user interface text (buttons, error messages, empty states, emails) in the product's tone. Use when ...
</description>
<location>
/s/skills/arabic-ui-text/SKILL.md
</location>
</skill>
...
</available_skills>أي أن ما يراه النموذج في الدرجة الأولى هو الاسم والوصف والمسار، والمسار هو ما يستعمله الوكيل ليقرأ الملف عندما يقرر أن المهارة تلزم.
كيف يعرض Codex المهارات في طلبه؟
شغلنا Codex CLI بالإصدار 0.170.0 على السيرفر Server الوهمي الذي يحفظ الطلبات، كما في مقال ملف تعليمات المشروع، ونسخنا المهارات الثلاث إلى .agents/skills/ في جذر المستودع Repository، وهو المسار الذي تذكره صفحة المهارات في توثيق Codex، ثم قارنا الطلب بطلب دون مهارات. والجزء الذي تغير كما يلي:
### Skill roots
- `r0` = `/root/.codex/skills/.system`
- `r1` = `/work/repo/.agents/skills`
### Available skills
- imagegen: Generate or edit raster images when the task benefits from AI-created bitmap visuals ... (file: r0/imagegen/SKILL.md)
- openai-docs: API first-timers, Codex/Work Q&A. ... (file: r0/openai-docs/SKILL.md)
- skill-creator: Create or update a Codex skill with appropriately scoped instructions ... (file: r0/skill-creator/SKILL.md)
- skill-installer: Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. ... (file: r0/skill-installer/SKILL.md)
- arabic-ui-text: Writes or reviews Arabic user interface text (buttons, error messages, empty states, emails) in the product's tone. Use when the user asks for Arabic copy, a translation of UI strings, or a review of Arabic messages in the locale files. (file: r1/arabic-ui-text/SKILL.md)
- db-migration: Creates a PostgreSQL schema migration for this repository (new table, column, index or constraint) with its rollback, following the naming rules in references/naming.md. Use when the user asks to change the database schema or add a migration. Not for querying data. (file: r1/db-migration/SKILL.md)
- release-notes: Writes the release notes of this repository from the git history since the last tag, in the team's format (Added, Fixed, Changed, Security). Use when the user asks for release notes, a changelog entry, or "what changed since v1.4". (file: r1/release-notes/SKILL.md)وعدد التوكنات Tokens في الحالتين كما يلي:
== captures/nested.json
developer: <skills_instructions> 536 tokens
total 8316 tokens
== captures/skills.json
developer: <skills_instructions> 765 tokens
total 8545 tokensفي المخرج أعلاه لاحظ التالي:
- Codex يأتي بأربع مهارات خاصة به في
/root/.codex/skills/.system، منهاskill-creatorلكتابة المهارات وskill-installerلتثبيتها، وأضاف مهاراتنا الثلاث بعدها، كل واحدة في سطر: الاسم، ثم الوصف كاملاً، ثم مسار الملف مختصراً بجذر اسمهr1. - نص المهارات نفسه لم يصل إلى النموذج، فلا أثر في الطلب لجملة «Read references/naming.md before you name anything» من مهارة الترحيل، أي أن Codex يطبق الدرجة الأولى فقط، وينتظر أن يقرأ النموذج الملف بأداة تشغيل الأوامر عندما يحتاجه.
- المهارات الثلاث رفعت قسم المهارات من 536 توكناً إلى 765، أي 229 توكناً، وحوالي 76 للمهارة، وهذا أقل من المئة التي تقدرها المواصفة لأن أوصافنا قصيرة.

وصفحة المهارات في توثيق Codex تذكر أن هذه القائمة تأخذ افتراضياً 2% على الأكثر من نافذة النموذج، أو 8,000 حرف إذا كانت النافذة غير معروفة، وأن Codex إذا كثرت المهارات يختصر الأوصاف أولاً، ثم قد يحذف بعض المهارات من القائمة ويظهر تحذيراً، وأن الإعداد skills.max_context_tokens يغير هذه الميزانية حتى 10,000 توكن. وصفحة المهارات في توثيق Claude Code تذكر حداً قريباً، فالوصف مع الحقل الإضافي when_to_use يقطع عند 1,536 حرفاً في قائمة المهارات. والنتيجة العملية واحدة: ضع في أول الوصف الحالة التي تستعمل فيها المهارة والكلمات التي سوف يكتبها المستخدم، لأن آخر الوصف هو ما يقص أولاً.
التجربة الأولى: هل يختار نموذج صغير المهارة من وصفها؟
رأينا أن المضيف يعطي النموذج الاسم والوصف فقط، وأن كل شيء بعد ذلك يعتمد على قرار النموذج. والسكربت 02_activation.py يبني هذا الموقف بالطريقة التي يقترحها دليل المواصفة للتفعيل بأداة مخصصة: تعليمات نظام فيها قائمة <available_skills> بالاسم والوصف، وأداة واحدة activate_skill مدخلها اسم المهارة من قائمة ثابتة Enum بالأسماء الثلاثة، وجملة تقول «إذا طابق الطلب مهارة فاستدع activate_skill باسمها قبل أي شيء، وإذا لم يطابق فلا تستدعها وأجب مباشرة». ثم يرسل عشرة طلبات: سبعة يجب أن تختار مهارة، منها طلبان بالعربية، وثلاثة يجب ألا تختار شيئاً، منها طلب قريب Near-miss يقصد قاعدة البيانات ولكنه استعلام لا ترحيل، وهو النوع الذي ينصح به دليل كتابة الأوصاف في موقع المواصفة، ويقترح الدليل نفسه حوالي عشرين طلباً بعدة تشغيلات لكل طلب، وتجربتنا أصغر من ذلك عمداً بسبب بطء المعالج. ويشغل السكربت الطلبات مرتين: مرة بالأوصاف المكتوبة في ملفات المهارات، ومرة بأوصاف عامة قصيرة مثل «Helps with releases» و«Database stuff» و«Arabic text». والنموذج qwen2.5:3b، وهو نموذج عام وليس نموذج برمجة، لأن نماذج البرمجة الصغيرة كتبت استدعاءات الأدوات نصاً عادياً في دليل الوكيل بنموذج محلي.
المحاولة الأولى: ردود فارغة
أول تشغيل أعطى نتيجة غريبة، فالنموذج لم يختر أي مهارة في سبعة طلبات من سبعة بالأوصاف الجيدة، والمخرج كان كما يلي:
### qwen2.5:3b, descriptions from SKILL.md
MISS want release-notes got None Write the release notes for v2.3.0.
MISS want release-notes got None What changed since v1.4? I need it for the changelog.
...
correct 3/10, prompt tokens of the last request 421والطريقة البسيطة أن نكتب أن النموذج لا يعرف أن يختار المهارات، ولكن الرقم مريب، فالنتيجة الصحيحة الوحيدة كانت في الطلبات التي لا تحتاج مهارة أصلاً. ولذلك طبعنا الرد الخام لطلبين، فوجدنا أن الرد ليس فيه نص ولا استدعاء أداة، بينما يقول سجل السيرفر إن النموذج كتب حوالي 35 توكناً. ثم أرسلنا الطلب نفسه بقالب النموذج كما يعرضه الأمر ollama show، ولكن بالخيار raw الذي يجعل Ollama يرجع النص كما كتبه النموذج دون أن يحلله، والمخرج كان كما يلي:
--- Write the release notes for v2.3.0. (want release-notes)
'<tool_call>\n{"name": "activate_skill", "arguments": {"name": "release-notes"}}\n</tool_call>'
--- Add a nullable column due_date to the invoices table. (want db-migration)
'<tool_call>\n{"name": "activate_skill", "arguments": {"name": "db-migration"}}\n</tool_call>'
--- Fix the typo in README.md: 'recieve'. (want None)
'None of the provided skills can be used to fix the typo in the README.md file. ...'أي أن النموذج استدعى الأداة بشكل صحيح تماماً، والذي ضاع هو تحويل هذا النص إلى استدعاء منظم في سيرفر Ollama بالإصدار 0.40.13، فقد رجعت واجهة /api/chat بنص فارغ ودون tool_calls، والواجهة المتوافقة مع OpenAI أعطت النتيجة نفسها. ولم نبحث في سبب ذلك داخل Ollama، ولكن الدرس العملي واضح: إذا رأيت وكيلاً لا يستعمل أداة كان يجب أن يستعملها، فانظر إلى النص الخام الذي كتبه النموذج قبل أن تحكم عليه، لأن العطل قد يكون في الطبقة التي بينه وبينك. ولذلك عدلنا السكربت ليرسل الطلب بالقالب نفسه وبالخيار raw، ويقرأ وسم <tool_call> بنفسه، كما تفعل بيئات التشغيل التي تتسامح مع النماذج الصغيرة.
النتيجة: الوصف الجيد يفرق في الطلبات القريبة
وبعد التعديل كان المخرج كما يلي:
### qwen2.5:3b, descriptions from SKILL.md
ok want release-notes got release-notes Write the release notes for v2.3.0.
ok want release-notes got release-notes What changed since v1.4? I need it for the changelog.
ok want release-notes got release-notes اكتب ملاحظات الإصدار للنسخة القادمة
ok want db-migration got db-migration Add a nullable column due_date to the invoices table.
ok want db-migration got db-migration We need an index on invoices(customer_id).
MISS want arabic-ui-text got None Translate the strings of the login screen in locales/en.json
MISS want arabic-ui-text got None راجع رسائل الخطأ العربية في ملف الترجمة
ok want None got None How many invoices did we create last month? Query the databa
ok want None got None Fix the typo in README.md: 'recieve'.
ok want None got None Write unit tests for parse_date in utils/dates.py.
correct 8/10, prompt tokens of the last request 442
### qwen2.5:3b, vague descriptions
ok want release-notes got release-notes Write the release notes for v2.3.0.
ok want release-notes got release-notes What changed since v1.4? I need it for the changelog.
ok want release-notes got release-notes اكتب ملاحظات الإصدار للنسخة القادمة
ok want db-migration got db-migration Add a nullable column due_date to the invoices table.
ok want db-migration got db-migration We need an index on invoices(customer_id).
MISS want arabic-ui-text got None Translate the strings of the login screen in locales/en.json
MISS want arabic-ui-text got None راجع رسائل الخطأ العربية في ملف الترجمة
MISS want None got db-migration How many invoices did we create last month? Query the databa
MISS want None got arabic-ui-text Fix the typo in README.md: 'recieve'.
ok want None got None Write unit tests for parse_date in utils/dates.py.
correct 6/10, prompt tokens of the last request 297في المخرج أعلاه لاحظ التالي:
- الطلبات الواضحة نجحت بالوصفين: ملاحظات الإصدار والترحيل اختيرت بالأوصاف الجيدة والعامة معاً، حتى الطلب العربي «اكتب ملاحظات الإصدار للنسخة القادمة» مع أن الوصف بالإنجليزية فقط. أي أن الطلب الذي يقول ما تفعله المهارة بكلمات قريبة من اسمها لا يحتاج وصفاً ممتازاً.
- الفرق كله في الطلبات القريبة: بالوصف العام «Database stuff» اختار النموذج مهارة الترحيل لطلب «كم فاتورة أنشأنا الشهر الماضي؟ استعلم من قاعدة البيانات»، وبالوصف الجيد لم يخترها، والسبب على الأرجح الجملة الأخيرة في الوصف «Not for querying data». وبالوصف العام «Arabic text» اختار مهارة النصوص العربية لإصلاح خطأ إملائي في README، وهذا خطأ مكلف في وكيل حقيقي لأنه يحمل تعليمات لا تخص المهمة ويتبعها.
- الوصف الجيد كلف 145 توكناً إضافياً في كل طلب، من 297 إلى 442، وهذا ثمن صغير مقابل طلبين صحيحين من عشرة.
أما طلبا النصوص العربية فقد فشلا في الحالتين، ولكي نفهم السبب طبعنا الرد الخام، والمخرج كان كما يلي:
--- Translate the strings of the login screen in locales/en.json to Arabic.
'<tool_call>\n{"name": "arabic-ui-text", "arguments": {"strings": {"login": "تسجيل الدخول", "login_error": "هذا البريد الإلكتروني أو كلمة المرور غير صحيحة"}}}\n</tool_call>'
--- راجع رسائل الخطأ العربية في ملف الترجمة
'<tool_call>\n{"name": "arabic-ui-text", "arguments": {"action": "review", "file_path": "translation_file.arb"}}\n</tool_call>'وهذا أطرف ما في التجربة وأكثره فائدة: النموذج عرف المهارة الصحيحة، ولكنه بدل أن يستدعي activate_skill باسمها، استدعى المهارة نفسها كأنها أداة اسمها arabic-ui-text، أي أداة غير موجودة، واخترع لها مدخلات، بل كتب الترجمة من عنده في الطلب الأول دون أن يقرأ ملف locales/en.json أصلاً. والقائمة الثابتة Enum التي ينصح بها الدليل تمنع النموذج من أن يخترع اسم مهارة داخل activate_skill، ولكنها لا تمنعه من أن يخترع أداة كاملة، ولذلك فإن بيئة التشغيل الجيدة ترفض استدعاء أي أداة غير معرفة وترجع للنموذج رسالة خطأ واضحة تذكر الأدوات الموجودة، بدل أن تتجاهله. وقد يتساءل البعض: لماذا حدث هذا مع مهارة النصوص العربية وحدها؟ ولا نعرف السبب يقيناً، ولكن الطلبين يطلبان فعلاً محدداً بمدخلات واضحة، ترجم هذه النصوص وراجع هذا الملف، فبدا للنموذج أن المهارة أداة تنفذه، وهذا يتكرر مع النماذج الصغيرة عندما يشبه اسم المهارة اسم فعل.

التجربة الثانية: هل يتبع النموذج المهارة بعد أن يقرأها؟
الاختيار الصحيح نصف العمل، والنصف الثاني أن يتبع النموذج ما في المهارة. والسكربت 03_follow.py يعطي النموذج نفسه طلباً واحداً لترحيل قاعدة البيانات: «أضف فهرساً Index على invoices(customer_id)، وجدولاً جديداً invoice_notes مرتبطاً بالفواتير فيه نص، واعرض كل ملف ترحيل باسمه ثم محتواه»، بثلاث طرق: دون مهارة، ومع نص SKILL.md لمهارة db-migration، ومع النص ومعه ملف المرجع references/naming.md الذي يشير إليه، أي الدرجات الثلاث للإفصاح التدريجي. ثم يفحص الرد بست قواعد كلها مكتوبة في المهارة أو مرجعها، مثل وجود ملف .up.sql باسم يبدأ بالتاريخ والوقت ومعه ملف .down.sql، وCREATE INDEX CONCURRENTLY، واسم الفهرس ix_invoices_customer_id، واسم القيد fk_invoice_notes_invoice_id، والمفتاح الأساسي generated always as identity، والعمود created_at بنوع timestamptz. والمخرج سوف يكون كما يلي:
no skill prompt 72 out 229 passed 0/6 ✗ up+down files ✗ index in own file, CONCURRENTLY ✗ index name ix_invoices_customer_id ✗ fk name fk_invoice_notes_invoice_id ✗ id generated always as identity ✗ created_at timestamptz
SKILL.md only prompt 225 out 200 passed 2/6 ✓ up+down files ✓ index in own file, CONCURRENTLY ✗ index name ix_invoices_customer_id ✗ fk name fk_invoice_notes_invoice_id ✗ id generated always as identity ✗ created_at timestamptz
SKILL.md + naming.md prompt 362 out 299 passed 3/6 ✓ up+down files ✓ index in own file, CONCURRENTLY ✓ index name ix_invoices_customer_id ✗ fk name fk_invoice_notes_invoice_id ✗ id generated always as identity ✗ created_at timestamptzفي المخرج أعلاه لاحظ التالي:
- دون مهارة صفر من ست: كتب النموذج ملفين باسمي
001_create_invoices_table.sqlو002_create_invoice_notes_table.sql، أي دون ملفات رجوع، وأعاد إنشاء جدول الفواتير نفسه الذي طلبنا أن نضيف إليه فهرساً، ووضع المبلغ فيDECIMAL(10, 2)، وكل هذا مقبول في مشروع لا قواعد له، وكله مخالف لقواعد هذا المشروع. - مع
SKILL.mdاثنتان من ست: ظهرت ملفات.up.sqlو.down.sql، وظهر الفهرس في ملف خاص به معCONCURRENTLY، أي أن الخطوات المكتوبة في نص المهارة نفسه طبقت. أما قواعد التسمية فلم تكن أمامه، لأن النص يقول «اقرأreferences/naming.md» والملف لم يحمل، فسمى الفهرسidx_invoices_customer_idوالجدولinvoices_notesبخطأ في الاسم المطلوب نفسه. - مع المرجع ثلاث من ست: اسم الفهرس أصبح
ix_invoices_customer_idكما في المرجع، ولكن القيد سميfk_invoice_notes_invoiceبدلfk_invoice_notes_invoice_id، والمفتاح بقيSERIALبدلgenerated always as identity، وcreated_atبنوعTIMESTAMPبدلtimestamptz، مع أن القواعد الثلاث كانت أمامه سطراً سطراً.

وفي الردود تفصيلان يستحقان الانتباه: الأول أن أسماء الملفات بدأت بتواريخ من أكتوبر 2023 مثل 202310101200، أي أن النموذج كتب «تاريخ اليوم» من ذاكرة تدريبه، لأن أحداً لم يعطه التاريخ، والثاني أن الرد الأخير أضاف ملاحظة تقول إن CREATE INDEX يجب أن ينفذ داخل معاملة Transaction، وهو عكس ما تقوله المهارة نفسها التي قرأها للتو، أي أن CREATE INDEX CONCURRENTLY لا يعمل داخل معاملة. أي أن المهارة حسنت النتيجة في كل درجة، من صفر إلى اثنتين إلى ثلاث، ولكنها لم تجعل النموذج الصغير يلتزم بكل قاعدة، وهذا يعيدنا إلى ما قلناه في مقال ملف التعليمات: التعليمات تحسن الاحتمال، والفحص هو الذي يضمن، ولذلك فإن المهارة الجيدة تحمل معها سكربت فحص إذا استطاعت، مثل سكربت يتأكد من أسماء الملفات والقيود قبل أن يقول الوكيل إنه انتهى.
كيف يدعم المضيف المهارات من الداخل؟
إذا كنت تبني وكيلك الخاص، أو تريد أن تفهم لماذا تتصرف أداتك بطريقة معينة، فإن موقع المواصفة فيه دليل لمن يضيف دعم المهارات إلى وكيل، وخطواته خمس، ورأينا أغلبها في طلب Codex المحفوظ:
- الاكتشاف Discovery: يبحث المضيف في مجلدات معروفة، مثل
.agents/skills/في المشروع وفي مجلد المستخدم، ويذكر الدليل أن بعض الأدوات تبحث أيضاً في.claude/skills/لأن كثيراً من المهارات المنشورة موجودة هناك، وأن المهارة في المشروع تغلب المهارة التي بالاسم نفسه في مجلد المستخدم. - القراءة Parsing: يقرأ رأس كل ملف، ويقترح الدليل أن يتسامح المضيف مع الأخطاء الصغيرة في YAML، مثل النقطتين في نص الوصف دون علامات تنصيص، بدل أن يرفض المهارة كلها.
- الإفصاح Disclosure: يضع قائمة الأسماء والأوصاف في تعليمات النظام، أو في وصف أداة مخصصة للتفعيل، ومعها جملة قصيرة تقول للنموذج متى وكيف يستعمل المهارة.
- التفعيل Activation: بطريقتين: أن يقرأ النموذج
SKILL.mdبأداة قراءة الملفات العادية، وهذا ما يفعله Codex، أو أن يستدعي أداة مخصصة مثلactivate_skillتأخذ اسم المهارة وترجع نصها، والدليل ينصح في الحالة الثانية بأن يكون الاسم قيمة من قائمة ثابتة Enum حتى لا يخترع النموذج اسم مهارة غير موجودة، وهذه هي الطريقة التي استعملناها في التجربة الأولى. - إدارة السياق: يحمي المضيف نص المهارة من الحذف عند ضغط المحادثة، لأن ضياعها في منتصف الجلسة يجعل الوكيل يكمل دون تعليماتها دون أي رسالة خطأ، ولا يضيف المهارة مرتين إذا فعلت مرتين.
وفي الخطوة الأولى نقطة أمنية يذكرها الدليل صراحة: المهارات التي في المشروع تأتي من المستودع الذي تعمل عليه، وقد يكون مستودعاً مفتوح المصدر نسخته للتو، ولذلك يقترح ألا يحملها المضيف إلا إذا أعلنت أن مجلد المشروع موثوق، حتى لا يدخل مستودع غريب تعليمات إلى سياق وكيلك دون أن تعرف.
ما تضيفه الأدوات فوق المواصفة
المواصفة تحدد الحد الأدنى الذي تفهمه كل الأدوات، وكل أداة تضيف فوقه، وتوثيق Claude Code يذكر ما يلي، كما كان في 19 نوفمبر 2026:
- أماكن المهارات: مهارات الشركة في مجلد الإعدادات المدارة Managed Settings، ومهاراتك الشخصية في
~/.claude/skills/، ومهارات المشروع في.claude/skills/، ومهارات المجلدات الفرعية في<subdir>/.claude/skills/وتحمل عندما يعمل الوكيل على ملف في ذلك المجلد، وعند تكرار الاسم تغلب مهارة الشركة ثم الشخصية ثم المشروع. - من يفعل المهارة: الحقل
disable-model-invocation: trueيجعل المهارة لا تعمل إلا عندما تكتب اسمها أنت، والتوثيق يقترحه للمهام التي تريد أن تبدأها بنفسك مثل النشر أو الـ commit. - التشغيل في وكيل فرعي: الحقل
context: forkيشغل المهارة في نافذة سياق منفصلة، فلا يملأ عملها نافذة المحادثة الرئيسية. - الأوامر القديمة أصبحت مهارات: التوثيق يذكر أن الأمر المخصص في
.claude/commands/deploy.mdيمكن أن ينقل إلى.claude/skills/deploy/SKILL.mdفيبقى اسمه/deploy، ويمكن أن تضاف إليه ملفات مساعدة. - التعديل أثناء الجلسة: الأداة تراقب مجلدات المهارات، فإذا أضفت مهارة أو عدلتها ظهرت في الجلسة نفسها دون إعادة تشغيل.
ويذكر التوثيق أيضاً أن الحقول التي خارج المواصفة، مثل context وdisable-model-invocation، لا تعمل في المنتجات الأخرى، وأن المهارة التي تريد أن تنقلها بين الأدوات يجب أن تكتفي بالحقول الستة. أما Codex فيقرأ المهارات من .agents/skills في كل مجلد من المجلد الحالي إلى جذر المستودع، ومن $HOME/.agents/skills ومن /etc/codex/skills، وتستطيع أن تطلب المهارة بالاسم بكتابة $ قبله أو من الأمر /skills، كما في توثيقه.
المهارة أم ملف التعليمات أم MCP أم الوكيل الفرعي؟
هذه أربع طرق لإعطاء الوكيل معرفة أو قدرة، وكل واحدة لها مكانها، والجدول التالي يجمعها:
| الطريقة | متى تدخل السياق | ما تحمله | استعملها عندما |
|---|---|---|---|
ملف التعليمات AGENTS.md | في كل طلب من البداية | قواعد قصيرة تنطبق على كل مهمة | تريد أن يعرف الوكيل الأمر الصحيح للاختبار وقواعد الكود Code دائماً |
| المهارة Skill | الوصف دائماً، والباقي عند الاختيار | خطوات مهمة معينة، ومراجع، وسكربتات | مهمة تتكرر بخطوات ثابتة ولكن ليس في كل جلسة |
| أداة MCP | تعريف الأداة دائماً، والنتيجة عند الاستدعاء | وصول إلى نظام خارجي ببيانات حية | الوكيل يحتاج بيانات أو فعلاً في نظام آخر، مثل التذاكر وقاعدة البيانات |
| الوكيل الفرعي Subagent | نافذة منفصلة، وتعود الخلاصة فقط | مهمة فرعية تحتاج قراءة كثيرة | البحث في عشرين ملفاً لتجيب عن سؤال واحد |

وتجتمع هذه الطرق في الغالب، فمهارة release-notes قد تستعمل أداة MCP لتقرأ عناوين التذاكر المرتبطة بكل commit، وClaude Code يسمح للمهارة أن تعمل في وكيل فرعي بالحقل context: fork، ويسمح أن تمنع الوكيل من اختيارها بنفسه بالحقل disable-model-invocation: true فلا تعمل إلا عندما تكتب اسمها أنت بعد الشرطة المائلة، وهذا مناسب لمهمة مثل النشر Deploy لا تريد أن يقرر الوكيل وحده متى يبدأها. ولاحظ أن هذه الحقول إضافات من Claude Code وليست من المواصفة، والتوثيق نفسه يقول إن خارج Claude Code تستعمل الحقول الستة للمواصفة فقط.
مهارات من مصادر غير موثوقة
المهارة ليست نصاً بريئاً، فهي تعليمات يتبعها وكيل يملك صلاحياتك، ومعها سكربتات يشغلها بتلك الصلاحيات Permissions. ومقال Anthropic نفسه يحذر من ذلك صراحة: المهارات الخبيثة قد تفتح ثغرات في البيئة التي تعمل فيها أو توجه النموذج إلى إرسال البيانات إلى الخارج، وينصح بتثبيت المهارات من مصادر موثوقة فقط، وبقراءة كل ملف في المهارة قبل استعمالها إذا جاءت من مصدر أقل ثقة، وخاصة السكربتات والاعتماديات Dependencies والتعليمات التي تطلب الاتصال بمصادر خارجية.
وهذا التحذير ليس نظرياً، فدراسة «Agent Skills in the Wild» لـ Yi Liu وزملائه في يناير 2026، وملخصها على arXiv يذكر أنهم جمعوا 42,447 مهارة من متجرين معروفين، وحللوا منها 31,132، ووجدوا أن 26.1% منها فيها ثغرة واحدة على الأقل من أربع فئات: حقن التعليمات، وإخراج البيانات Data Exfiltration، ورفع الصلاحيات Privilege Escalation، ومخاطر سلسلة التوريد Supply Chain، وأن 5.2% فيها أنماط خطيرة تدل بقوة على نية خبيثة، وأن المهارات التي تحمل سكربتات أكثر احتمالاً للثغرات بـ 2.12 مرة من المهارات التي فيها تعليمات فقط. ودراسة ثانية للباحث نفسه وزملائه في فبراير 2026 بعنوان «Do Not Mention This to the User»، وملخصها يذكر أنهم فحصوا 98,380 مهارة من سجلين، وأكدوا سلوكاً خبيثاً في 157 منها فيها 632 ثغرة بـ 13 طريقة هجوم. وفيما يلي ما ننصح به عملياً:
- اقرأ
SKILL.mdوكل سكربت في المجلد قبل أن تضعه في.agents/skills/أو.claude/skills/، كما تقرأ أي كود تضيفه إلى المستودع. - راجع تغييرات مجلد المهارات في Pull Request مثل الكود، واجعل فحص
agentskills validateفي خط النشر CI. - لا تعط المهارة صلاحيات مسبقة بالحقل
allowed-toolsإلا لأدوات القراءة، لأن هذا الحقل يعني أن الوكيل لا يسألك قبل أن يستعملها. - تذكر أن السكربت الذي يشغله الوكيل يعمل بصلاحياته، ولذلك فإن الصندوق المعزول Sandbox الذي شرحناه في مقال بيئة تشغيل الوكيل هو الحد الحقيقي، وليس ما تقوله المهارة عن نفسها.
كيف تكتب مهارة جيدة؟
- ابدأ بالوصف: اكتب أولاً متى تستعمل المهارة، بالكلمات التي سوف يكتبها زملاؤك فعلاً، بالعربية والإنجليزية إذا كان الفريق يكتب بهما، ثم اكتب ماذا تفعل، ثم متى لا تستعمل إذا كان هناك التباس، مثل «Not for querying data» في مهارة الترحيل.
- اجعل التعليمات خطوات مرقمة: بمدخلات ومخرجات واضحة، والخطوة التي تتكرر دائماً بالطريقة نفسها اجعلها سكربتاً.
- ضع المهم في أول الملف: توثيق Claude Code يذكر أن المهارات التي استعملت تعود بعد ضغط المحادثة Compaction بحد 5,000 توكن لكل مهارة، وأن القطع يبقي أول الملف.
- انقل التفاصيل إلى المراجع: المواصفة تنصح بأقل من 500 سطر في
SKILL.md، وبأن تكون الإشارات إلى الملفات الأخرى على مستوى واحد، أي أنSKILL.mdيشير إلى المرجع، والمرجع لا يشير إلى مرجع آخر. - اختبر الاختيار قبل التعليمات: اكتب عشرة طلبات يجب أن تختار المهارة وخمسة يجب ألا تختارها، كما فعلنا في التجربة الأولى، وتوثيق Codex نفسه ينصح باختبار الطلبات مقابل وصف المهارة.
كيف تقيس الوصف قبل أن تنشر المهارة؟
التجربة الأولى نسخة صغيرة من طريقة يشرحها دليل تحسين الأوصاف في موقع المواصفة، وإذا كانت المهارة ستستعمل في فريق كامل فإن الطريقة الكاملة تستحق ساعة من وقتك، وخطواتها كما يلي:
- اكتب حوالي عشرين طلباً: ثمانية إلى عشرة يجب أن تفعل المهارة، وثمانية إلى عشرة يجب ألا تفعلها، والدليل يقول إن أفيد الطلبات الإيجابية هي التي لا تذكر موضوع المهارة صراحة، وأفيد الطلبات السلبية هي القريبة التي تشترك مع المهارة في الكلمات وتطلب شيئاً آخر، مثل طلب الاستعلام من قاعدة البيانات في تجربتنا.
- شغل كل طلب أكثر من مرة: الدليل يقترح ثلاث مرات لكل طلب، ويعتبر الطلب الإيجابي ناجحاً إذا فعل المهارة في أكثر من نصف المرات، والسلبي ناجحاً إذا فعلها في أقل من النصف، لأن النتيجة تختلف من تشغيل إلى آخر مع النماذج التي تعمل بحرارة أكبر من صفر.
- اقسم الطلبات إلى مجموعتين: حوالي 60% للتدريب Train تستعملها لتعرف أين يفشل الوصف، و40% للتحقق Validation لا تنظر إليها أثناء التعديل، وتختار في النهاية الوصف الذي نجح أكثر في مجموعة التحقق، حتى لا تكتب وصفاً يناسب طلباتك العشرين فقط.
- عدل الوصف بالمفهوم لا بالكلمة: إذا لم تفعل المهارة في طلبات يجب أن تفعلها فالوصف ضيق، فوسع الحالات التي يذكرها، وإذا فعلت في طلبات قريبة يجب ألا تفعلها فالوصف واسع، فاكتب ما لا تفعله المهارة، والدليل يحذر من أن تضيف كلمات الطلب الذي فشل نفسها إلى الوصف، لأن هذا يحفظ الطلب ولا يحل المشكلة.
- توقف بعد خمس محاولات تقريباً: الدليل يقول إن خمس دورات تكفي في الغالب، وإن الوصف إذا لم يتحسن فقد تكون المشكلة في الطلبات نفسها.
ويقترح الدليل نفسه أن يكتب الوصف بصيغة الأمر للوكيل، مثل «Use this skill when…»، وأن يركز على ما يريده المستخدم لا على طريقة عمل المهارة من الداخل، وأن يذكر الحالات التي لا يسمي فيها المستخدم الموضوع صراحة. ولاحظ أن هذا القياس يقيس الاختيار فقط، أي الدرجة الأولى، أما جودة ما يفعله الوكيل بعد الاختيار فتحتاج قياساً ثانياً مثل التجربة الثانية، بفحوص آلية على المخرج، لأن المهارة التي تختار دائماً ثم لا تتبع لا تفيد.
أخطاء شائعة
- وصف عام مثل «Helps with releases»: المواصفة تضرب هذا المثال للوصف السيئ، والوكيل لا يعرف منه متى يختار المهارة.
- كل شيء في
SKILL.md: المهارة التي فيها عشرة آلاف توكن تدخل كاملة عند الاختيار، فانقل التفاصيل إلى ملفات فيreferences/. - اسم المجلد لا يطابق الاسم: الأداة المرجعية ترفضه، وبعض الأدوات قد لا تجده.
- مهارة تكرر ملف التعليمات: القواعد التي تنطبق على كل مهمة مكانها
AGENTS.md، والمهارة لخطوات مهمة معينة. - تثبيت مهارة من مستودع غريب دون قراءتها: سكربتاتها تعمل بصلاحياتك.
- الاعتماد على أن الوكيل سوف يختارها دائماً: النموذج قد لا يختار المهارة المناسبة، فإذا كانت المهمة مهمة فاطلب المهارة باسمها، مثل
/release-notesفي Claude Code أو$release-notesفي Codex.
قائمة تحقق قبل أن تضيف مهارة إلى المستودع
- هل الوصف يذكر متى تستعمل المهارة في أول جملة، وبكلمات المستخدم؟
- هل يمر المجلد بالأمر
agentskills validate؟ - هل
SKILL.mdأقل من 500 سطر، والتفاصيل في مراجع على مستوى واحد؟ - هل العمل الثابت سكربت، وهل قرأت كل سكربت فيها؟
- هل جربت طلبات يجب أن تختارها وطلبات يجب ألا تختارها؟
- هل الحقل
allowed-toolsفارغ أو لأدوات القراءة فقط؟ - هل المجلد في المسار الذي تقرؤه أدوات فريقك كلها؟
تدريب عملي
- اكتب مهارة رابعة من عملك اليومي، مثل كتابة وصف Pull Request بصيغة فريقك، وافحصها بالأمر
bash validate.sh، ثم أضف طلبين لها في02_activation.pyوشغله. - في
02_activation.pyاجعل وصفdb-migrationلا يذكر «Not for querying data»، وانظر هل يتغير اختيار النموذج لطلب عدد الفواتير. - في
03_follow.pyانقل قواعد التسمية من المرجع إلىSKILL.mdنفسه، وقارن عدد التوكنات وعدد الفحوص التي نجحت.
الخلاصة
- المهارة مجلد فيه
SKILL.mdبرأس فيه الاسم والوصف، وتعليمات، وملفات اختيارية فيscripts/وreferences/وassets/، والمواصفة مفتوحة منذ ديسمبر 2025 وتقرؤها Claude Code وCodex وCopilot وأدوات أخرى. - الإفصاح التدريجي ثلاث درجات: الوصف في كل طلب، والتعليمات عند الاختيار، والملفات عند الحاجة، وفي Codex CLI 0.170.0 كلفت كل مهارة من مهاراتنا حوالي 76 توكناً في كل طلب، ولم يصل نص أي مهارة حتى يفتحه النموذج.
- الأداة المرجعية
agentskills validateمن حزمة skills-ref 0.1.1 رفضت الاسم بحروف كبيرة وشرطة سفلية، والاسم الذي لا يطابق المجلد، والمهارة دون وصف. - سيرفر Ollama 0.40.13 أسقط استدعاءات الأداة الصحيحة التي كتبها نموذج qwen2.5:3b فرجع الرد فارغاً، والنص الخام كشف أن النموذج لم يخطئ.
- بأوصاف جيدة اختار النموذج المهارة الصحيحة في 8 طلبات من 10، وبأوصاف عامة في 6، والفرق كله في الطلبات القريبة التي يجب ألا تختار مهارة، والجملة التي تقول متى لا تستعمل المهارة هي ما منع الخطأ.
- النموذج استدعى مهارة النصوص العربية كأنها أداة غير موجودة واخترع ترجمة دون أن يقرأ الملف، فاجعل بيئة التشغيل ترفض الأدوات غير المعرفة برسالة واضحة.
- في طلب ترحيل واحد التزم النموذج بصفر قواعد من ست دون مهارة، وباثنتين مع
SKILL.md، وبثلاث مع المرجع، فالمهارة تحسن الاحتمال، والفحص هو الذي يضمن. - المهارات من مصادر غير موثوقة تعليمات وسكربتات تعمل بصلاحياتك، ودراسة في يناير 2026 وجدت ثغرة واحدة على الأقل في 26.1% من 31,132 مهارة حللتها.
وفي المقالات الأخرى من هذه المرحلة بإذن الله نتحدث عن ملف تعليمات المشروع الذي يحمل في كل طلب، وعن السياق كله، وعن ربط الوكيل بأنظمة الفريق عبر MCP، وعن كتابة المواصفة قبل الكود:
دليلملف تعليمات المشروع AGENTS.md وCLAUDE.md: ماذا تكتب فيهأين تضع ملف تعليمات الوكيل، وكيف تجمعه Codex وClaude Code وCopilot من المجلدات، ومتى يقطع دون أن يعرف النموذج، وماذا يتغير فعلاً عندما تكتبه.
دليلهندسة السياق Context Engineering: ما يراه الوكيل وما لا يراهما الذي يرسله الوكيل فعلاً مع طلبك، ولماذا يخطئ النموذج عندما يكون أمامه ملف لا يحتاجه أو سجل طويل أو جلسة قصت من أولها، مع تجارب على نموذج محلي تغير السياق وحده.
دليلMCP للمطورين: اربط وكيلك بقاعدة البيانات والتذاكر والتوثيقكيف تضيف سيرفر MCP إلى Codex وClaude Code وCursor، وكيف تكتب سيرفراً للفريق يقرأ قاعدة البيانات دون أن يكتب فيها، وكم يكلف كل سيرفر من سياق الوكيل.
دليلالتطوير من المواصفة Spec-driven Development: الخطة قبل الكودكيف تعمل Spec Kit من GitHub، وما الفرق بين المواصفة والخطة والمهام، وماذا حدث عندما بنى نموذج محلي صغير الميزة نفسها بثلاث طرق تحت اختبارات قبول لم يرها.سجل التحديثات
- 20 نوفمبر 2026: كتابة المقال، وفحص المهارات بالأداة المرجعية skills-ref 0.1.1، وقياس طلب حقيقي من Codex CLI 0.170.0، وتشغيل التجربتين على Ollama 0.40.13 بنموذج qwen2.5:3b.