التطوير مع وكلاء الذكاء الاصطناعي الأدلة التقنية

المهارات Agent Skills: تعليمات يحملها الوكيل عند الحاجة

كيف تكتب مهارة حسب المواصفة المفتوحة، وكيف يعرضها Codex على النموذج، وهل يختار نموذج صغير المهارة الصحيحة من وصفها ويتبع ما فيها.

المهارات Agent Skills: تعليمات يحملها الوكيل عند الحاجة

في كل فريق مهام تتكرر بخطوات ثابتة لا يعرفها إلا من عمل في المشروع: كيف تكتب ملاحظات الإصدار 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، فالفرق يصبح بين ألفي توكن في كل طلب ومئة وأربعين ألفاً. والشكل التالي يبين الدرجات الثلاث بأرقام المختبر:

ثلاثة صناديق فوق بعضها: الأول بنفسجي برقم 1، الاسم والوصف فقط لكل المهارات من بداية الجلسة، وفي Codex زاد الطلب 229 توكناً بإضافة ثلاث مهارات أي حوالي 76 للمهارة، ومعه مثال رأس الملف name db-migration وdescription. ثم سهم الطلب يطابق الوصف إلى الصندوق الثاني الأزرق برقم 2، نص SKILL.md كاملاً عندما يقرر الوكيل أن المهارة تلزم، 212 توكناً والمواصفة تنصح بأقل من 5000، ومعه خطوات من الملف. ثم سهم التعليمات تشير إلى ملف إلى الصندوق الثالث الأخضر برقم 3، الملفات المرفقة عند الحاجة فقط، references/naming.md بـ 127 توكناً، والسكربت يشغل ولا يقرأ، ومعه مربعا references/naming.md وscripts/collect.sh
الدرجات الثلاث بأرقام المختبر: الوصف في كل طلب، والتعليمات عند الاختيار، والملفات المرفقة عند الحاجة.

ولاحظ أن السكربت في الدرجة الثالثة مختلف عن المرجع، فالمرجع يقرأ فيدخل السياق، أما السكربت فيشغل، ولا يدخل السياق إلا مخرجه، ولذلك فإن العمل الذي يمكن أن يكتب كوداً مرة واحدة، مثل استخراج بيانات من ملف أو تحويل صيغة، أرخص في السياق وأدق في النتيجة إذا كان سكربتاً.

الفحص بالأداة المرجعية 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&#x27;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 للمهارة، وهذا أقل من المئة التي تقدرها المواصفة لأن أوصافنا قصيرة.
نافذة داكنة فيها قسم skills_instructions من طلب Codex: جذران r0 للمهارات الخاصة بـ Codex وr1 للمجلد .agents/skills في المستودع، ثم قائمة المهارات وفيها imagegen وopenai-docs وskill-creator وskill-installer، ثم مهاراتنا الثلاث بالأخضر arabic-ui-text وdb-migration وrelease-notes بالوصف والمسار، وتحتها مستطيل أحمر فيه أول سطرين من تعليمات db-migration مع ملاحظة أنها ليست في الطلب، وتحت النافذة ثلاث بطاقات: الوصف كاملاً، والنص غائب، وميزانية محدودة 2% من النافذة أو 8,000 حرف
قسم المهارات كما وصل في طلب حقيقي: الاسم والوصف والمسار لكل مهارة، أما التعليمات نفسها فلا تصل حتى يفتح النموذج الملف.

وصفحة المهارات في توثيق 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، ولكنها لا تمنعه من أن يخترع أداة كاملة، ولذلك فإن بيئة التشغيل الجيدة ترفض استدعاء أي أداة غير معرفة وترجع للنموذج رسالة خطأ واضحة تذكر الأدوات الموجودة، بدل أن تتجاهله. وقد يتساءل البعض: لماذا حدث هذا مع مهارة النصوص العربية وحدها؟ ولا نعرف السبب يقيناً، ولكن الطلبين يطلبان فعلاً محدداً بمدخلات واضحة، ترجم هذه النصوص وراجع هذا الملف، فبدا للنموذج أن المهارة أداة تنفذه، وهذا يتكرر مع النماذج الصغيرة عندما يشبه اسم المهارة اسم فعل.

جدول من عشرة صفوف لعشرة طلبات، وعمودان للنتيجة بأوصاف SKILL.md وبأوصاف عامة: طلبات ملاحظات الإصدار الثلاثة وطلبا الترحيل ok في العمودين، وطلبا النصوص العربية بالأصفر استدعاها كأداة في العمودين، وطلب كم فاتورة الشهر الماضي ok بالأوصاف الجيدة وdb-migration بالأحمر بالأوصاف العامة، وخطأ إملائي في README ok وarabic-ui-text بالأحمر، واختبارات parse_date ok في العمودين، والنتيجة 8 من 10 مقابل 6 من 10 وطول التعليمات 442 توكناً مقابل 297
عشرة طلبات بوصفين: الوصف الجيد منع اختيارين خاطئين في الطلبات القريبة، وطلبا النصوص العربية فشلا في الحالتين لأن النموذج استدعى المهارة كأنها أداة.

التجربة الثانية: هل يتبع النموذج المهارة بعد أن يقرأها؟

الاختيار الصحيح نصف العمل، والنصف الثاني أن يتبع النموذج ما في المهارة. والسكربت 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، مع أن القواعد الثلاث كانت أمامه سطراً سطراً.
جدول من ست قواعد وثلاثة أعمدة: دون مهارة 72 توكناً كلها حمراء 0 من 6، وSKILL.md وحده 225 توكناً فيه علامتا صح لملفي up وdown والفهرس CONCURRENTLY والباقي أحمر 2 من 6، وSKILL.md مع naming.md 362 توكناً فيه ثلاث علامات صح بإضافة اسم ix_invoices_customer_id والباقي أحمر fk_invoice_notes_invoice_id وgenerated always as identity وcreated_at timestamptz، 3 من 6
الطلب نفسه بثلاث درجات من المهارة: كل درجة أضافت قواعد التزم بها النموذج، ولم تصل أي درجة إلى القواعد الست.

وفي الردود تفصيلان يستحقان الانتباه: الأول أن أسماء الملفات بدأت بتواريخ من أكتوبر 2023 مثل 202310101200، أي أن النموذج كتب «تاريخ اليوم» من ذاكرة تدريبه، لأن أحداً لم يعطه التاريخ، والثاني أن الرد الأخير أضاف ملاحظة تقول إن CREATE INDEX يجب أن ينفذ داخل معاملة Transaction، وهو عكس ما تقوله المهارة نفسها التي قرأها للتو، أي أن CREATE INDEX CONCURRENTLY لا يعمل داخل معاملة. أي أن المهارة حسنت النتيجة في كل درجة، من صفر إلى اثنتين إلى ثلاث، ولكنها لم تجعل النموذج الصغير يلتزم بكل قاعدة، وهذا يعيدنا إلى ما قلناه في مقال ملف التعليمات: التعليمات تحسن الاحتمال، والفحص هو الذي يضمن، ولذلك فإن المهارة الجيدة تحمل معها سكربت فحص إذا استطاعت، مثل سكربت يتأكد من أسماء الملفات والقيود قبل أن يقول الوكيل إنه انتهى.

كيف يدعم المضيف المهارات من الداخل؟

إذا كنت تبني وكيلك الخاص، أو تريد أن تفهم لماذا تتصرف أداتك بطريقة معينة، فإن موقع المواصفة فيه دليل لمن يضيف دعم المهارات إلى وكيل، وخطواته خمس، ورأينا أغلبها في طلب Codex المحفوظ:

  1. الاكتشاف Discovery: يبحث المضيف في مجلدات معروفة، مثل .agents/skills/ في المشروع وفي مجلد المستخدم، ويذكر الدليل أن بعض الأدوات تبحث أيضاً في .claude/skills/ لأن كثيراً من المهارات المنشورة موجودة هناك، وأن المهارة في المشروع تغلب المهارة التي بالاسم نفسه في مجلد المستخدم.
  2. القراءة Parsing: يقرأ رأس كل ملف، ويقترح الدليل أن يتسامح المضيف مع الأخطاء الصغيرة في YAML، مثل النقطتين في نص الوصف دون علامات تنصيص، بدل أن يرفض المهارة كلها.
  3. الإفصاح Disclosure: يضع قائمة الأسماء والأوصاف في تعليمات النظام، أو في وصف أداة مخصصة للتفعيل، ومعها جملة قصيرة تقول للنموذج متى وكيف يستعمل المهارة.
  4. التفعيل Activation: بطريقتين: أن يقرأ النموذج SKILL.md بأداة قراءة الملفات العادية، وهذا ما يفعله Codex، أو أن يستدعي أداة مخصصة مثل activate_skill تأخذ اسم المهارة وترجع نصها، والدليل ينصح في الحالة الثانية بأن يكون الاسم قيمة من قائمة ثابتة Enum حتى لا يخترع النموذج اسم مهارة غير موجودة، وهذه هي الطريقة التي استعملناها في التجربة الأولى.
  5. إدارة السياق: يحمي المضيف نص المهارة من الحذف عند ضغط المحادثة، لأن ضياعها في منتصف الجلسة يجعل الوكيل يكمل دون تعليماتها دون أي رسالة خطأ، ولا يضيف المهارة مرتين إذا فعلت مرتين.

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

ما تضيفه الأدوات فوق المواصفة

المواصفة تحدد الحد الأدنى الذي تفهمه كل الأدوات، وكل أداة تضيف فوقه، وتوثيق 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نافذة منفصلة، وتعود الخلاصة فقطمهمة فرعية تحتاج قراءة كثيرةالبحث في عشرين ملفاً لتجيب عن سؤال واحد
خط زمني من بداية الجلسة إلى عندما تناسب المهمة إلى عند الحاجة فقط، وتحته أربعة صفوف: AGENTS.md شريط أزرق كامل من أول الجلسة إلى آخرها، والمهارة Skill ثلاث قطع بنفسجية الاسم والوصف ثم SKILL.md عند الاختيار ثم المراجع والسكربتات، وأداة MCP قطعة خضراء لتعريف الأداة من البداية وقطعة لنتيجة الاستدعاء ببيانات حية، والوكيل الفرعي قطعة برتقالية صغيرة للخلاصة فقط وما قرأه يبقى في نافذته
الأربعة تعطي الوكيل معرفة، والفرق في متى تدخل السياق وكم تبقى فيه.

وتجتمع هذه الطرق في الغالب، فمهارة 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 الذي شرحناه في مقال بيئة تشغيل الوكيل هو الحد الحقيقي، وليس ما تقوله المهارة عن نفسها.

كيف تكتب مهارة جيدة؟

  1. ابدأ بالوصف: اكتب أولاً متى تستعمل المهارة، بالكلمات التي سوف يكتبها زملاؤك فعلاً، بالعربية والإنجليزية إذا كان الفريق يكتب بهما، ثم اكتب ماذا تفعل، ثم متى لا تستعمل إذا كان هناك التباس، مثل «Not for querying data» في مهارة الترحيل.
  2. اجعل التعليمات خطوات مرقمة: بمدخلات ومخرجات واضحة، والخطوة التي تتكرر دائماً بالطريقة نفسها اجعلها سكربتاً.
  3. ضع المهم في أول الملف: توثيق Claude Code يذكر أن المهارات التي استعملت تعود بعد ضغط المحادثة Compaction بحد 5,000 توكن لكل مهارة، وأن القطع يبقي أول الملف.
  4. انقل التفاصيل إلى المراجع: المواصفة تنصح بأقل من 500 سطر في SKILL.md، وبأن تكون الإشارات إلى الملفات الأخرى على مستوى واحد، أي أن SKILL.md يشير إلى المرجع، والمرجع لا يشير إلى مرجع آخر.
  5. اختبر الاختيار قبل التعليمات: اكتب عشرة طلبات يجب أن تختار المهارة وخمسة يجب ألا تختارها، كما فعلنا في التجربة الأولى، وتوثيق Codex نفسه ينصح باختبار الطلبات مقابل وصف المهارة.

كيف تقيس الوصف قبل أن تنشر المهارة؟

التجربة الأولى نسخة صغيرة من طريقة يشرحها دليل تحسين الأوصاف في موقع المواصفة، وإذا كانت المهارة ستستعمل في فريق كامل فإن الطريقة الكاملة تستحق ساعة من وقتك، وخطواتها كما يلي:

  1. اكتب حوالي عشرين طلباً: ثمانية إلى عشرة يجب أن تفعل المهارة، وثمانية إلى عشرة يجب ألا تفعلها، والدليل يقول إن أفيد الطلبات الإيجابية هي التي لا تذكر موضوع المهارة صراحة، وأفيد الطلبات السلبية هي القريبة التي تشترك مع المهارة في الكلمات وتطلب شيئاً آخر، مثل طلب الاستعلام من قاعدة البيانات في تجربتنا.
  2. شغل كل طلب أكثر من مرة: الدليل يقترح ثلاث مرات لكل طلب، ويعتبر الطلب الإيجابي ناجحاً إذا فعل المهارة في أكثر من نصف المرات، والسلبي ناجحاً إذا فعلها في أقل من النصف، لأن النتيجة تختلف من تشغيل إلى آخر مع النماذج التي تعمل بحرارة أكبر من صفر.
  3. اقسم الطلبات إلى مجموعتين: حوالي 60% للتدريب Train تستعملها لتعرف أين يفشل الوصف، و40% للتحقق Validation لا تنظر إليها أثناء التعديل، وتختار في النهاية الوصف الذي نجح أكثر في مجموعة التحقق، حتى لا تكتب وصفاً يناسب طلباتك العشرين فقط.
  4. عدل الوصف بالمفهوم لا بالكلمة: إذا لم تفعل المهارة في طلبات يجب أن تفعلها فالوصف ضيق، فوسع الحالات التي يذكرها، وإذا فعلت في طلبات قريبة يجب ألا تفعلها فالوصف واسع، فاكتب ما لا تفعله المهارة، والدليل يحذر من أن تضيف كلمات الطلب الذي فشل نفسها إلى الوصف، لأن هذا يحفظ الطلب ولا يحل المشكلة.
  5. توقف بعد خمس محاولات تقريباً: الدليل يقول إن خمس دورات تكفي في الغالب، وإن الوصف إذا لم يتحسن فقد تكون المشكلة في الطلبات نفسها.

ويقترح الدليل نفسه أن يكتب الوصف بصيغة الأمر للوكيل، مثل «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 فارغ أو لأدوات القراءة فقط؟
  • هل المجلد في المسار الذي تقرؤه أدوات فريقك كلها؟

تدريب عملي

  1. اكتب مهارة رابعة من عملك اليومي، مثل كتابة وصف Pull Request بصيغة فريقك، وافحصها بالأمر bash validate.sh، ثم أضف طلبين لها في 02_activation.py وشغله.
  2. في 02_activation.py اجعل وصف db-migration لا يذكر «Not for querying data»، وانظر هل يتغير اختيار النموذج لطلب عدد الفواتير.
  3. في 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.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.