Agent Skills و SKILL.md: الإفصاح التدريجي، بالأرقام

وضع الفصل 14 قاعدة النصف الثاني من هذا المساق — الاتصالات، وإعادة المحاولة، والإلغاء هي TypeScript — وأعلن خمسة استثناءات. هذا واحد منها، والسبب ليس تفضيلًا.

الـ skill ملف Markdown. ليس ملفًا يهيّئ برنامجًا، ولا ملفًا يترجمه برنامج: بل مستند يقرأه النموذج، بالطريقة نفسها التي يقرأ بها الرسالة التي كتبتها. إعطاء هذا الفصل لغة برمجة يعني أن التنسيق لم يُفهم، وهذا سوء الفهم هو الأشيع حول skills. كل ما يلي هو Markdown وYAML، إضافة إلى shell script صغير موجود تحديدًا ليوضح أين ينتمي الكود وأين لا ينتمي داخل skill.

هذه تعليمة حقيقية: كيف تكتب شركة ما ملاحظات الإصدار لديها. إنها إجراء، لا تفضيل — لها مجموعة خطوات مرتبة، وتصنيف، وصوت، وقالب، وscript يجمع المادة الخام.

ضع كل ذلك في system prompt، كما تفعل معظم الفرق، وسيتولى حساب الفصل 16 الأمر. system prompt بادئة، والبادئة يُدفع ثمنها في كل استدعاء. قيس ذلك باستخدام o200k_base على المجلد المكتوب لهذا الفصل:

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

أرخص بأربع وعشرين مرة عند استخدامه، وأرخص بسبع وثلاثين مرة عند عدم استخدامه. الأسعار هي أسعار الفصل 16: $2.00 لكل مليون token إدخال.

والآن الاعتراض الصادق، لأن فصلًا يتجاوزه سيكون إعلانًا. prompt caching يغلق فجوة المال في معظمها. system prompt ثابت ويوضع أولًا، مما يجعله أفضل مرشح للتخزين المؤقت على الإطلاق؛ وعند $0.20 لكل مليون token إدخال مخزن مؤقتًا، تكلف الـ 68,640 token نفسها $0.0168 بدلًا من $0.1373. ما زالت ثلاثة أضعاف الـ skill، لكنها لم تعد رتبة مقدار مختلفة.

لم يكن المال أقوى حجة قط. هذه هي:

التخزين المؤقت يجعل البادئة الدائمة أرخص. لكنه لا يجعلها أصغر.

عند الدور 40، لا تزال نسخة system-prompt تحمل 1,716 token من سياسة ملاحظات الإصدار داخل النافذة أثناء محادثة عن شيء آخر تمامًا، لتنافس على ما سماه الفصل 24 ميزانية attention لدى النموذج. نسخة skill تحمل 46. خزّن الشيء الخاطئ مؤقتًا، وستكون قد اشتريت خصمًا على مشتّت.

مكتوبة كصيغة، مع $n$ للأدوار، و$L_1$ للبيانات الوصفية، و$L_2$ للمتن، و$L_3$ للحزمة كلها، و$R$ لمجموعة الملفات المجمعة التي قُرئت فعلًا:

كل هذا الفصل هو الفرق بين ضرب الحد الثاني في $n$ وضربه في واحد أو في صفر.

الـ skill هي دليل. المواصفة قصيرة بما يكفي لذكرها كاملة:

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

يجب أن يبدأ SKILL.md بـ YAML frontmatter، ولا يلزم إلا حقلان بالضبط: name وdescription.¹ أربعة أخرى اختيارية ولا تُعرّف أي حقول غيرها:

هذه هي skill ملاحظات الإصدار، كاملة، ومتنها أقل من ثلاثين سطرًا:

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

اقرأ ما يكونه ذلك المتن. ليس هو السياسة — بل جدول محتويات مع ترتيب عمليات. السياسة تعيش في ثلاثة ملفات يسميها ولا يضمّنها. والخطوة الأولى تسلّم العمل إلى script، لأن كود الـ script لا يدخل context window إطلاقًا: مخرجه فقط هو الذي يدخل.²

لنموذج التحميل اسم وثلاث مراحل. تذكرها المواصفة مع ميزانية token ملحقة:¹

1. البيانات الوصفية، نحو 100 token: name وdescription، تُحمّل عند بدء التشغيل لكل skill مثبتة.
2. التعليمات، يوصى بأن تكون دون 5,000 token: متن SKILL.md، يُحمّل عندما تُفعّل الـ skill.
3. الموارد، عند الحاجة: ملفات مضمّنة، لا تُحمّل إلا عندما يتطلبها شيء ما.

تضع الوثائق المرجعية عمودًا رابعًا على الجدول نفسه — متى تُحمّل، تكلفة token، المحتوى — والصف المهم هو الثالث: لا شيء حتى الوصول.³ والجملة التي تلخص الفصل كله موجودة هناك أيضًا:

لا تستهلك الملفات context حتى يُوصل إليها، لذلك يمكن أن تتضمن Skills وثائق API شاملة، أو مجموعات بيانات كبيرة، أو أمثلة موسعة. لا توجد عقوبة context على المحتوى المضمّن غير المستخدم.³

الجدول المقاس في أعلى هذا الفصل هو فحص لتلك الدعوى على خمس skills لم يكتبها أحد من أجل هذه المقالة. يستحق صفان أن يُقرآ أحدهما مقابل الآخر.

يملك next-best-practices متنًا من 966 token يربط بتسعة عشر ملفًا تحتوي 19,374 token. اطلب منه إصلاح خطأ hydration فيقرأ agent المتن زائد hydration-error.md: 1,409 token من أصل 20,340، عامل أربعة عشر، ولا تُفتح الملفات الثمانية عشر الأخرى أبدًا.

يملك next-cache-components متنًا من 2,334 token ولا يملك أي ملفات مضمّنة إطلاقًا. إنها skill صالحة ومكتوبة جيدًا، ولا تملك مستوى 3 تكشفه. هذا هو الحد الصادق للتقنية: الإفصاح التدريجي لا يوفّر إلا إذا كان هناك شيء يمكن تأجيله. الـ skill التي لا تتفكك معرفتها تدفع متنها كله عند التفعيل، والرافعة الوحيدة المتبقية هي عدم تفعيلها.

المستوى 1 قرار توجيه يُتخذ من جملة واحدة. لا يؤثر أي شيء آخر في skill على ما إذا كانت ستُفتح أصلًا — لا جودة المتن، ولا الأمثلة، ولا scripts. لذلك ليس الوصف توثيقًا. إنه سطح الاستعلام، ويمكن أن يكون خاطئًا.

تقول المواصفة ذلك في صورة مثال جيد وآخر سيئ، والمثال السيئ أربع كلمات: description: Helps with PDFs.¹ وهذا يستحق القياس لا القبول.

ست skills، لكل منها وصف معقول يذكر ما تفعله ومتى تُستخدم. أربعة وعشرون طلبًا، أربعة لكل skill، مصاغة كما سيصوغها شخص حقيقي ولا تسمي الـ skill أبدًا. يرى النموذج الأسطر الستة في system prompt ويجب أن يجيب باسم واحد أو بـ NONE. Greedy decoding، كي يعيد الإنتاج. ثم الطلبات الأربعة والعشرون نفسها مع skills الست نفسها، لكن الأوصاف اختُصرت إلى موضوعها العاري.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

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

والآن اقرأ السطر الأخير، فهو النتيجة الفعلية. مع الأوصاف النحيفة أجاب النموذج بـ NONE في تسعة من أربعة وعشرين طلبًا. ليس skill خاطئة: لا skill. هذه أربعة منها، حرفيًا:

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

كانت skill sql-review كاملة مثبتة، بمتن وأمثلة وقائمة تحقق، ولم تُفتح أبدًا، ثلاث مرات متتالية، على الأسئلة الثلاثة التي كُتبت لأجلها. المستويان 2 و3 لا صلة لهما بـ skill لا يصل إليها المستوى 1 قط.

تكلفة إصلاح ذلك: 214 token، الفرق بين 295 و81، موزعة على ست skills. وهذا هو اكتشاف الفصل 18 آتيًا من الجهة الأخرى. هناك، أدى تغيير وصف أداة فقط إلى نقل تنسيق التاريخ من 2 صحيح من 24 إلى 24 من 24. هنا، يؤدي تغيير وصف skill فقط إلى نقل التفعيل من 10 من 24 إلى 18. في الحالتين، أرخص إصلاح في النظام هو جملة، وفي الحالتين يجب أن تسمي الجملة trigger لا الموضوع فقط: ليس ما الشيء، بل ما الذي سيكون المستخدم قد قاله للتو عندما ينطبق.

تحفظ واحد يدين به هذا الفصل لمعاييره هو. هذا نموذج بنصف مليار parameter، ونموذج frontier يوجّه أفضل بكثير من 75 %. اقرأ الآلية لا المقدار: إشارة التوجيه طولها جملة واحدة أيًا كان النموذج الذي يقرأها، ولا يستطيع أي نموذج أن يختار بناءً على معلومات لم تضعها في تلك الجملة.

الفشل الثاني عكس الأول. تُعثر الـ skill، وتقسّم المستويات بشكل صحيح، ثم يقرأ agent كل شيء على أي حال.

vercel-react-best-practices skill مبنية جيدًا حقًا. متنها البالغ 1,670 token جدول أولويات من ثماني فئات ومرجع سريع يسمي 70 ملف قواعد، سطرًا لكل واحد. القواعد على القرص بجانبه: 70 ملفًا، أصغرها 132 token، والوسيط 319، وأكبرها 1,052. اسألها سؤالًا واحدًا عن barrel imports والتكلفة الصادقة هي المتن زائد ملف واحد — أقل من 2,400 token مقابل حزمة من 53,670.

ثم يقول السطر الأخير من المتن هذا:

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md هو 26,362 token. إنه ملفات القواعد السبعون مضمومة: مجموعها 25,784، والفرق هو العناوين بينها. لذا تعرض الـ skill على agent اختيارًا بين قراءة قاعدة وسيطة واحدة عند 319 token وقراءة المحتوى نفسه، كله، بثلاثة وثمانين ضعف السعر — وتعرض ذلك الاختيار في جملة بلا تكلفة مرفقة وبلا شرط يحدد متى يستحق.

هذا ليس خطأ برمجيًا والملف ليس خاطئًا؛ فالمستند المجمّع مفيد حقًا لإنسان، ولـ agent طُلب منه تدقيق codebase كامل. إنه ملف مستوى 3 بدعوة مستوى 2، والدرس يتعمم خارج هذه skill الواحدة: كل مسار خارج SKILL.md ينبغي أن يقول ما تكلفته ومتى يستحق، لأن النموذج لا يملك طريقة لمعرفة أن اسم ملف أغلى بثلاثة وثمانين ضعفًا من اسم الملف الذي فوقه.

يحمل المجلد نفسه درسًا أصغر في التقادم. يقول المتن «70 قاعدة عبر 8 فئات» ويسرد 70؛ ويحتوي دليل rules/ على 72 ملفًا، اثنان منها scaffolding (_template.md و_sections.md)؛ ويقول الملف الجانبي metadata.json «40+ rules». ثلاثة أعداد للمجموعة نفسها في مجلد واحد، واحد منها صحيح، وواحد حسابي، وواحد باقٍ من نسخة سابقة. الـ skill مستند، والمستندات تتعفن تمامًا مثل تعليق في الكود انجرف بعيدًا عن الكود الذي بجانبه — مع فارق أن هذا تقرؤه آلة لن ترفع حاجبًا.

تعرّف المواصفة المفتوحة ستة حقول frontmatter. يقبل التنفيذ المرجعي، Claude Code، عشرين.² تستحق خمس مجموعات أن تعرفها بالاسم، لأنها مواضع يتوقف فيها التنسيق عن كونه مستندًا فقط:

المعاملات (arguments، argument-hint) تتيح للشخص تمرير قيم تُستبدل داخل المتن، وهذا ما يجعل skill قابلة للاستخدام كأمر slash. النطاق (paths) يقيّد التفعيل بملفات تطابق glob. وdynamic context injection هو ما يغيّر النموذج الذهني: سطر على هيئة !`git diff HEAD` يعمل قبل إرسال المتن، ويُستبدل خرجه داخل النص. المستند قالب، وجزء منه يُحسب وقت القراءة.

والآن الفخ، وهو مذكور في الوثائق نفسها: خارج Claude Code — في المنتج الويب، عبر Skills API، في التغليف — لا يُسمح إلا بالحقول الستة المحددة، وأي حقل آخر خطأ صارم عند الرفع.² لذلك تفشل skill تعمل بإتقان في منتج ما عند تثبيتها في منتج آخر للبائع نفسه، وتفشل عند frontmatter لا عند شيء تستطيع اختباره بقراءة النثر. إذا أردت أن تكون skill قابلة للنقل، فالحقول الستة هي الميزانية كلها. وإن لم ترد ذلك، فقل هذا في compatibility، الذي وُجد لهذا السبب بالضبط.

تختلط أربعة أشياء بعضها ببعض باستمرار، وليس الخلط تدقيقًا لغويًا: الاختيار الخاطئ يكلف مالًا في كل دور، أو يكلفك ضمانًا ظننت أنك تملكه.

الصفان بالخط العريض هما التمييز كله. الـ skill تُقرأ؛ والأداة تُستدعى. الـ skill نثر يصل إلى context window وينافس على attention مع كل ما هناك؛ يمكن للنموذج اتباعه، أو إساءة قراءته، أو تجاهله، ولا يلاحظ النظام شيئًا. الأداة استدعاء يخرج من يدي النموذج بالكامل: يتلقى كودك المعاملات، ويتحقق منها، ويفحص الأذونات، ويقرر. صاغ الفصل 18 الأمر على أن النموذج يقترح وكودك يحسم، وهذا التقسيم هو بالضبط ما لا تملكه skill.

إذًا ست حالات حقيقية، محلولة:

التاريخ قصير، مؤرخ على نحو غير معتاد، وهو الجزء الذي لا يرويه أحد تقريبًا.

نُشرت Agent Skills في 16 أكتوبر 2025 كميزة لبائع واحد، وعُرّفت في ذلك الإعلان بأنها «مجلدات منظمة من التعليمات وscripts والموارد التي يستطيع agents اكتشافها وتحميلها ديناميكيًا ليؤدوا مهام محددة بشكل أفضل»، مع وصف المستويات الثلاثة عبر تشبيه يستحق الاحتفاظ به: «مثل دليل منظم جيدًا يبدأ بجدول محتويات، ثم فصول محددة، وأخيرًا ملحق مفصل».⁴

في 18 ديسمبر 2025 حُدثت الصفحة نفسها لإعلان التنسيق كـ معيار مفتوح، بمواصفة خاصة به عند agentskills.io، وحوكمة مفتوحة للمساهمات، ومدقق مرجعي.³ عند القراءة في 7 سبتمبر 2026، تعرض واجهة عملاء المعيار ستة وأربعين منتجًا — محررات، وterminals، ومنصات سحابية، وبيئات تشغيل محمولة، بما في ذلك agents البرمجة الأولى من Anthropic وOpenAI وGoogle وMistral — يربط كل منها إلى وثائق الإعداد الخاصة به.¹

يُنجز التقارب مع MCP في العلن، بأرقام يمكنك فحصها:

الجزء المثير هو الإغلاق، لا المقترحات. طلب SEP-2076 primitive رابعًا بجانب الأدوات والموارد وprompts. قررت working group التي تشكلت منه أن الجواب لا: تركب skills على primitive الموارد الموجود أصلًا، كامتداد اختياري.⁵ قاس الفصل 26 الغريزة نفسها في changelog البروتوكول ذاته، حيث أُهملت sampling وroots وlogging بدل الإبقاء عليها. هيئة معايير تزيل مقترحًا ألّفته تتصرف جيدًا، وسبب سرد هذه القصة مع الأرقام أمامك هو أن الملخصات التي ستقرؤها في أماكن أخرى ما زالت تصف skills كـ MCP primitive.

يمكنك الآن كتابة SKILL.md، وتقسيمه إلى ثلاثة مستويات تدفع تكلفتها بنفسها، وقراءة frontmatter لـ skill كتبها شخص آخر ومعرفة أي الحقول لن تنجو من رفعها في مكان آخر، والإجابة عن السؤال الذي بُني الفصل كله حوله — system prompt، أو skill، أو tool، أو server — بسبب لا بعادة.

ما لا يمكنك فعله هو معرفة هل تعمل skill لديك.

كل دعوى مهمة في هذا الفصل كانت قياسًا، وأهمها كان دقة: 18 من 24 مقابل 10 من 24، مع فاصل لكل منهما واختبار مزدوج بينهما، لأن مجموعين متداخلين لا يحسمان شيئًا. هذه الأداة كانت مستعارة. وصف الـ skill مفتاح توجيه، ومتنها إجراء قد يتبعه النموذج أو لا، وكلاهما خاصيتان لا يمكنك معرفتهما إلا بتشغيل الشيء مرات عديدة وتسجيل ما عاد — وهذا هو golden set، وgrader كتبته قبل التشغيل، وmetric تسأل هل نجح كل مرة لا مرة واحدة على الأقل.

الفصل 29 هو ذلك، ويفتتح بالرقم الذي تعتمد عليه طريقة هذا الفصل: agent ينجح سبع مرات من عشر يبدو مثل 70 %، وpass^10 الخاص به — احتمال أن ينجح في العشر كلها — هو صفر. كما يقيس ثلاثة graders على المئتي transcript نفسها ويحصل على 0 % و13 % و26 % دون إعادة توليد token واحدة. قبل أن تثق بالجملة التي كتبتها للتو داخل description، تحتاج إلى الأداة التي تستطيع إخبارك أنها أسوأ من التي استبدلتها.

أُنتج كل عد token في هذا الفصل محليًا باستخدام tiktoken 0.14.0 وترميز o200k_base، في 7 سبتمبر 2026: على skills الخمس التابعة لطرف ثالث المدرجة في بداية هذا الفصل، وعلى skill release-notes المكتوبة لهذا الفصل، والتي أُعيد إنتاج نصها الكامل أعلاه جزئيًا. يقاس المستوى 1 كسطر واحد هو - name: description الذي يعرضه مضيف داخل system prompt؛ والمستوى 2 هو متن SKILL.md بعد frontmatter؛ والمستوى 3 هو كل ملف آخر في المجلد. تستخدم التكاليف أسعار الفصل 16 المقاسة لـ gpt-5.6-terra، $2.00 لكل مليون token إدخال و$0.20 لكل مليون token إدخال مخزن مؤقتًا، مطبقة على تلك الأعداد — إنها حساب على tokens مقاسة، لا ملاحظات لفاتورة حية. لم يُستدعَ أي API مدفوع لكتابة هذا الفصل.

شغلت تجربة التفعيل Qwen/Qwen2.5-0.5B-Instruct بنصف الدقة على GPU استهلاكي واحد، مع greedy decoding، و24 طلبًا على ست skills، مرتين — مرة بأوصاف تذكر ما تفعله skill ومتى تنطبق، ومرة بأوصاف مختصرة إلى موضوع عارٍ على أسلوب «المثال السيئ» في المواصفة نفسها. الفواصل Wilson عند 95 %؛ والمقارنة المزدوجة اختبار sign دقيق ثنائي الطرف على الحالات العشر المتخالفة؛ وفاصل Wilson من الفصل 4 واختبار sign المزدوج الدقيق من الفصل 15، كلاهما أُعيد استخدامه بلا تغيير. اقرأ المقادير كخاصية لنموذج صغير جدًا، والمنهج كشيء قابل للنقل.

skills الخمس المقاسة هنا حزم طرف ثالث، وليست مكتوبة لهذا الفصل: next-best-practices وnext-cache-components من vercel-labs/next-skills، وvercel-composition-patterns وvercel-react-best-practices وvercel-react-native-skills من vercel-labs/agent-skills. قُرئت أعدادها الداخلية — 70 ملف قواعد، وAGENTS.md عند 26,362 token، وmetadata.json المؤرخ يناير 2026 ويدعي «40+ rules» — من الملفات على القرص في 7 سبتمبر 2026، وهي خصائص لتلك النسخة المنشورة لا انتقادات لمؤلفيها: كل واحدة منها هي نوع الانجراف الذي يظهر في أي شجرة توثيق تُحرر أكثر مما تُعد.