Agent Skills و SKILL.md: افشای تدریجی، با اندازه‌گیری

فصل 14 قانون نیمه دوم این دوره را تعیین کرد — connectionها، retryها و cancellation با TypeScript هستند — و پنج استثنا اعلام کرد. این یکی از آن‌هاست، و دلیلش سلیقه نیست.

یک skill یک فایل Markdown است. نه فایلی که یک برنامه را پیکربندی کند، نه فایلی که برنامه آن را کامپایل کند: سندی است که مدل می‌خواند، همان‌طور که پیامی را که شما تایپ کرده‌اید می‌خواند. اگر به این فصل زبان برنامه‌نویسی بدهیم یعنی قالب را نفهمیده‌ایم، و همین بدفهمی رایج‌ترین بدفهمی درباره skillهاست. هرچه در ادامه می‌آید Markdown و YAML است، به‌علاوه یک shell script کوچک که دقیقاً برای نشان دادن این وجود دارد که کد کجا داخل skill جا دارد و کجا ندارد.

این یک دستورالعمل واقعی است: اینکه یک شرکت release noteهایش را چطور می‌نویسد. این یک رویه است، نه ترجیح — مجموعه‌ای مرتب از گام‌ها، یک taxonomy، یک صدا، یک template و scriptی دارد که مواد خام را جمع می‌کند.

همه‌اش را مثل بیشتر تیم‌ها در system prompt بگذارید، و حسابِ فصل 16 شروع می‌شود. system prompt یک پیشوند است، و پیشوند در هر call پرداخت می‌شود. اندازه‌گیری‌شده با 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 به‌ازای هر میلیون input token.

حالا اعتراض صادقانه، چون فصلی که از آن بگذرد تبلیغ است. prompt caching تقریباً شکاف پولی را می‌بندد. یک system prompt پایدار است و اول می‌نشیند، که آن را به بهترین نامزد cache تبدیل می‌کند؛ با $0.20 به‌ازای هر میلیون ورودی cacheشده، همان 68,640 token به‌جای $0.1373، $0.0168 هزینه دارد. هنوز سه برابر skill، اما دیگر از یک مرتبه بزرگی متفاوت نیست.

پول هیچ‌وقت قوی‌ترین استدلال نبود. این بود:

Caching یک پیشوند دائمی را ارزان‌تر می‌کند. کوچک‌ترش نمی‌کند.

در نوبت 40، نسخه system-prompt هنوز 1,716 token سیاست release-note را در context window نگه داشته، در گفت‌وگویی که درباره چیز کاملاً دیگری است، و با چیزی رقابت می‌کند که فصل 24 آن را بودجه attention مدل نامید. نسخه skill فقط 46 دارد. اگر چیز اشتباه را cache کنید، فقط برای یک حواس‌پرتی تخفیف خریده‌اید.

به‌صورت فرمول، با $n$ نوبت، $L_1$ metadata، $L_2$ body، $L_3$ کل بسته و $R$ مجموعه فایل‌های bundled که واقعاً خوانده شده‌اند:

کل این فصل تفاوت میان ضرب کردن جمله دوم در $n$ و ضرب کردنش در یک یا صفر است.

یک skill یک directory است. مشخصات آن آن‌قدر کوتاه است که می‌شود کامل بیانش کرد:

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 شروع شود، و دقیقاً دو field الزامی است: name و description.¹ چهار مورد دیگر اختیاری‌اند و هیچ مورد دیگری تعریف نشده است:

این هم skill مربوط به release-notes، کامل، با body کمتر از سی خط:

---
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.

بخوانید این body چیست. policy نیست — فهرست مطالبی با ترتیب عملیات است. policy در سه فایلی زندگی می‌کند که نامشان را می‌آورد و در خود وارد نمی‌کند. و گام اول کار را به یک script می‌سپارد، چون کدِ script اصلاً وارد context window نمی‌شود: فقط خروجی‌اش وارد می‌شود.²

مدل بارگذاری یک نام و سه مرحله دارد. مشخصات، آن‌ها را همراه با بودجه token بیان می‌کند:¹

1. Metadata، حدود 100 token: name و description، هنگام startup برای هر skill نصب‌شده بارگذاری می‌شود.
2. Instructions، توصیه‌شده زیر 5,000 token: bodyِ SKILL.md، وقتی skill فعال می‌شود بارگذاری می‌شود.
3. Resources، در صورت نیاز: فایل‌های bundled، فقط وقتی چیزی به آن‌ها نیاز دارد بارگذاری می‌شوند.

مستندات مرجع یک ستون چهارم هم روی همان جدول می‌گذارد — زمان بارگذاری، هزینه token، محتوا — و سطری که مهم است سطر سوم است: هیچ، تا وقتی accessed شود.³ جمله‌ای که کل فصل را خلاصه می‌کند هم همان‌جاست:

فایل‌ها تا وقتی accessed نشوند context مصرف نمی‌کنند، بنابراین Skills می‌توانند مستندات جامع API، datasetهای بزرگ یا مثال‌های گسترده را شامل شوند. برای محتوای bundled که استفاده نمی‌شود، جریمه context وجود ندارد.³

جدول اندازه‌گیری‌شده ابتدای این فصل همان ادعاست که در برابر پنج skill که هیچ‌کس برای این مقاله ننوشته بررسی شده. دو ردیف ارزش دارند کنار هم خوانده شوند.

next-best-practices یک body 966-token دارد که به نوزده فایل با 19,374 token لینک می‌دهد. از آن بخواهید یک خطای hydration را درست کند و agent، body به‌علاوه hydration-error.md را می‌خواند: 1,409 token از 20,340، ضریب چهارده، و هجده فایل دیگر هرگز باز نمی‌شوند.

next-cache-components یک body 2,334-token دارد و هیچ فایل bundledی ندارد. skill معتبر و خوش‌نوشتی است، و سطح 3ی برای disclose کردن ندارد. این حد صادقانه تکنیک است: progressive disclosure فقط وقتی صرفه‌جویی است که چیزی برای به‌تعویق‌انداختن وجود داشته باشد. skillی که دانشش تجزیه نمی‌شود، هنگام فعال‌سازی کل body خود را می‌پردازد، و تنها اهرم باقی‌مانده فعال نکردنش است.

سطح 1 یک تصمیم routing است که از یک جمله گرفته می‌شود. هیچ چیز دیگری درباره یک skill روی اینکه اصلاً باز شود یا نه اثر ندارد — نه کیفیت body، نه مثال‌ها، نه scriptها. پس description مستندات نیست. query surface است، و می‌تواند غلط باشد.

مشخصات این را در قالب یک مثال خوب و یک مثال بد می‌گوید، و مثال بد چهار کلمه است: description: Helps with PDFs.¹ ارزش دارد به‌جای پذیرفتن، اندازه‌گیری شود.

شش skill، هرکدام با descriptionی قابل‌قبول که می‌گوید چه می‌کند و چه زمانی باید استفاده شود. بیست‌وچهار درخواست، چهار مورد برای هر skill، با phrasingی که یک آدم به کار می‌برد و بدون نام بردن از skill. مدل شش خط را در system prompt خود می‌بیند و باید با یک نام یا با NONE پاسخ دهد. greedy decoding، پس بازتولیدپذیر است. سپس همان بیست‌وچهار درخواست با همان شش skill، و descriptionها کوتاه‌شده تا موضوع عریانشان.

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

اول intervalها را بخوانید، همان‌طور که فصل 4 اصرار کرد و فصل 29 دوباره اصرار خواهد کرد: آن‌ها هم‌پوشانی دارند، و بیست‌وچهار case نمی‌تواند دو system را فقط بر اساس aggregateهایشان رتبه‌بندی کند. مقایسه paired چیزی است که تکلیف را روشن می‌کند، و ابزار فصل 15 است: از ده caseی که دو arm با هم اختلاف داشتند، نه‌تا به descriptionهای غنی رسید و یکی به descriptionهای نازک. این در آستانه معمول established است.

حالا خط آخر را بخوانید، که یافته واقعی است. با descriptionهای نازک، مدل در نه درخواست از بیست‌وچهار درخواست پاسخ 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 نصب شده بود، با body و مثال‌ها و checklist، و هرگز باز نشد، سه بار پشت سر هم، روی سه پرسشی که برایشان نوشته شده بود. سطح‌های 2 و 3 برای skillی که سطح 1 هرگز به آن نمی‌رسد بی‌اهمیت‌اند.

هزینه درست کردنش: 214 token، تفاوت بین 295 و 81، پخش‌شده روی شش skill. این همان یافته فصل 18 است که از سوی دیگر می‌رسد. آنجا، فقط تغییر description یک tool، date formatting را از 2 درست از 24 به 24 درست از 24 رساند. اینجا، فقط تغییر description یک skill، activation را از 10 از 24 به 18 می‌رساند. در هر دو مورد ارزان‌ترین fix در system یک جمله است، و در هر دو مورد آن جمله باید trigger را نام ببرد و نه فقط موضوع را: نه اینکه چیز چیست، بلکه اینکه کاربر درست قبل از کاربردش چه گفته خواهد بود.

یک caveat که این فصل به استانداردهای خودش بدهکار است. این یک مدل نیم‌میلیارد-پارامتری است، و یک frontier model خیلی بهتر از 75٪ route می‌کند. سازوکار را بخوانید، نه بزرگی عدد را: سیگنال routing هر مدلی که آن را بخواند یک جمله طول دارد، و هیچ مدلی نمی‌تواند بر اساس اطلاعاتی که در آن جمله نگذاشته‌اید انتخاب کند.

شکست دوم برعکس اولی است. skill پیدا می‌شود، سطح‌ها درست جدا شده‌اند، و agent بااین‌حال همه‌اش را می‌خواند.

vercel-react-best-practices واقعاً skill خوش‌ساختی است. bodyِ 1,670-token آن یک جدول اولویت از هشت category و یک quick reference است که 70 فایل rule را، هرکدام در یک خط، نام می‌برد. ruleها کنار آن روی disk هستند: 70 فایل، کوچک‌ترین 132 token، میانه 319، بزرگ‌ترین 1,052. یک سؤال درباره barrel importها بپرسید و هزینه صادقانه body به‌علاوه یک فایل است — زیر 2,400 token در برابر bundleی با 53,670.

بعد خط آخر body این را می‌گوید:

## Full Compiled Document

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

AGENTS.md 26,362 token است. همان 70 فایل rule به‌هم‌چسبیده است: جمعشان 25,784 است، و تفاوت از headingهای بینشان می‌آید. بنابراین skill به agent انتخابی می‌دهد میان خواندن یک rule میانه با 319 token و خواندن همان محتوا، همه‌اش، با هشتادوسه برابر قیمت — و این انتخاب را در جمله‌ای عرضه می‌کند که هیچ هزینه‌ای به آن وصل نیست و هیچ شرطی برای اینکه چه زمانی باید سراغش رفت ندارد.

این bug نیست و فایل غلط نیست؛ یک سند کامپایل‌شده واقعاً برای انسان مفید است، و برای agentی که از او خواسته شده یک codebase کامل را audit کند. این یک فایل سطح 3 با دعوت سطح 2 است، و درس از این یک skill فراتر می‌رود: هر مسیر خروجی از SKILL.md باید بگوید چه هزینه‌ای دارد و چه زمانی ارزشش را دارد، چون مدل هیچ راهی ندارد بفهمد یک filename هشتادوسه برابر گران‌تر از filename بالای خودش است.

همان پوشه درس کوچک‌تری هم درباره کهنگی دارد. body می‌گوید «70 rule در 8 category» و 70 تا را فهرست می‌کند؛ directoryِ rules/ شامل 72 فایل است که دوتایش scaffolding هستند (_template.md و _sections.md)؛ و sidecarِ metadata.json می‌گوید «40+ rule». سه شمارش از یک مجموعه در یک پوشه، یکی درست، یکی حسابی، و یکی باقی‌مانده از نسخه‌ای قدیمی‌تر. skill یک سند است، و سندها دقیقاً مثل commentی در کد که از کدِ کنار خودش منحرف شده می‌پوسند — با این تفاوت که این یکی را ماشینی می‌خواند که ابرو بالا نمی‌اندازد.

مشخصات open شش field frontmatter تعریف می‌کند. reference implementation، یعنی Claude Code، بیست‌تا را می‌پذیرد.² پنج گروه ارزش دارد با نام بشناسید، چون همان‌جاهاست که قالب دیگر فقط یک سند نیست:

Arguments (arguments، argument-hint) به انسان اجازه می‌دهند valueهایی بدهد که در body جایگزین می‌شوند، و همین است که skill را به‌عنوان slash command قابل‌استفاده می‌کند. Scoping (paths) activation را به فایل‌هایی محدود می‌کند که با یک glob match می‌شوند. و dynamic context injection همان موردی است که mental model را تغییر می‌دهد: خطی به شکل !`git diff HEAD` پیش از فرستادن body اجرا می‌شود، و خروجی‌اش در متن جایگزین می‌شود. سند یک template است، و بخشی از آن هنگام خواندن محاسبه می‌شود.

حالا تله، و در همان مستندات بیان شده: بیرون از Claude Code — در محصول وب، از طریق Skills API، در packaging — فقط همان شش field مشخص‌شده مجازند، و هر field دیگری هنگام upload یک hard error است.² پس skillی که در یک محصول کاملاً درست کار می‌کند، در محصول دیگری از همان vendor نصب نمی‌شود، و شکست در frontmatter رخ می‌دهد نه در چیزی که بتوانید با خواندن نثر test کنید. اگر قصد دارید skill قابل‌حمل باشد، شش field کل budget هستند. اگر ندارید، در compatibility بگویید، که دقیقاً برای همین وجود دارد.

چهار چیز مدام با هم اشتباه گرفته می‌شوند، و این سردرگمی وسواس واژگانی نیست: انتخاب اشتباه یا در هر نوبت برایتان پول هزینه دارد، یا تضمینی را از شما می‌گیرد که فکر می‌کردید دارید.

دو ردیف bold کل تمایزند. skill خوانده می‌شود؛ tool invoke می‌شود. skill نثری است که وارد context window می‌شود و با هر چیز دیگری که آنجاست بر سر attention رقابت می‌کند؛ مدل می‌تواند آن را دنبال کند، بد بخواند، یا نادیده بگیرد، و هیچ چیز در system متوجه نمی‌شود. tool callی است که کاملاً از دست مدل خارج می‌شود: کد شما argumentها را دریافت می‌کند، validate می‌کند، permissionها را بررسی می‌کند و تصمیم می‌گیرد. فصل 18 این را این‌طور گفت که مدل پیشنهاد می‌دهد و کد شما تکلیف را مشخص می‌کند، و این تقسیم دقیقاً چیزی است که skill ندارد.

پس شش مورد واقعی، حل‌شده:

تاریخچه کوتاه است، به‌طور غیرمعمولی خوب تاریخ‌گذاری شده، و همان بخشی است که تقریباً هیچ‌کس تعریف نمی‌کند.

Agent Skills در 16 October 2025 به‌عنوان feature یک vendor منتشر شد، و در آن announcement به‌صورت «پوشه‌های سازمان‌یافته‌ای از دستورالعمل‌ها، scriptها و resourceها که agentها می‌توانند discover و به‌صورت dynamic load کنند تا در taskهای مشخص بهتر عمل کنند» تعریف شد، با سه سطحی که از طریق analogy ارزشمندی توضیح داده شدند: «مثل manualی خوش‌سازمان که با فهرست مطالب شروع می‌شود، بعد chapterهای مشخص، و در نهایت appendix مفصل».⁴

در 18 December 2025 همان صفحه update شد تا قالب را به‌عنوان open standard اعلام کند، با specification خودش در agentskills.io، governance باز برای contributionها، و reference validator.³ هنگام خواندن در 7 September 2026، showcaseِ clientهای استاندارد چهل‌وشش محصول را فهرست می‌کند — editorها، terminalها، cloud platformها و mobile runtimeها، از جمله coding agentهای first-party متعلق به Anthropic، OpenAI، Google و Mistral — که هرکدام به مستندات setup خودشان لینک می‌دهند.¹

همگرایی با MCP به‌صورت open انجام می‌شود، با اعدادی که می‌توانید بررسی کنید:

بخش جالب closure است، نه proposalها. SEP-2076 خواستار primitive چهارمی کنار tools، resources و prompts شد. working groupی که از دل آن شکل گرفت تصمیم گرفت پاسخ نه است: skillها بر primitiveِ resources که از قبل وجود دارد سوار می‌شوند، به‌عنوان extensionی opt-in.⁵ فصل 26 همین instinct را در changelog خود protocol اندازه گرفت، جایی که sampling، roots و logging به‌جای نگه‌داشتن deprecated شدند. standards bodyای که proposalی را که خودش authored کرده حذف می‌کند، خوب رفتار می‌کند، و دلیل تعریف کردن این داستان با اعداد پیش رو این است که summaryهایی که جاهای دیگر می‌خوانید هنوز skillها را به‌عنوان MCP primitive توصیف می‌کنند.

حالا می‌توانید یک SKILL.md بنویسید، آن را به سه سطحی split کنید که هزینه خودشان را درمی‌آورند، frontmatter skill شخص دیگری را بخوانید و بدانید کدام fieldها از upload شدن در جای دیگر جان سالم به در نمی‌برند، و پرسشی را که کل فصل حول آن ساخته شده — system prompt، skill، tool، یا server — با دلیل پاسخ دهید نه از روی عادت.

کاری که نمی‌توانید بکنید این است که بفهمید مال شما کار می‌کند یا نه.

هر claim مهم در این فصل یک measurement بود، و مهم‌ترینش یک accuracy بود: 18 از 24 در برابر 10 از 24، با interval برای هرکدام و paired test بینشان، چون دو aggregate که هم‌پوشانی دارند هیچ چیز را تعیین نمی‌کنند. آن ابزار قرضی بود. description یک skill، routing key آن است، body آن procedureی است که مدل ممکن است follow کند یا نکند، و هر دو ویژگی‌هایی هستند که فقط با اجرای آن چیز بارها و امتیاز دادن به خروجی می‌توانید بفهمید — یعنی golden set، graderی که پیش از run نوشته‌اید، و metricی که می‌پرسد آیا هر بار کار کرد، نه اینکه حداقل یک بار.

فصل 29 همان است، و با عددی باز می‌شود که روش این فصل به آن وابسته است: agentی که از ده بار هفت بار موفق می‌شود شبیه 70٪ است، و pass^10 آن — احتمال اینکه در هر ده‌تا موفق شود — صفر است. همچنین سه grader را روی همان دویست transcript اندازه می‌گیرد و بدون بازتولید حتی یک token، 0٪، 13٪ و 26٪ می‌گیرد. پیش از آنکه به جمله‌ای که همین حالا در description نوشتید اعتماد کنید، به ابزاری نیاز دارید که بتواند به شما بگوید از جمله‌ای که جایگزینش کرده‌اید بدتر است.

هر token count در این فصل به‌صورت local با tiktoken 0.14.0 و encodingِ o200k_base، در 7 September 2026 تولید شد: روی پنج skillِ third-party که در ابتدای این فصل فهرست شدند، و روی skillِ release-notes که برای این فصل نوشته شد و متن کاملش تا حدی در بالا بازتولید شده است. سطح 1 به‌صورت خط واحد - name: description اندازه‌گیری شده که host در system prompt render می‌کند؛ سطح 2 bodyِ SKILL.md پس از frontmatter است؛ سطح 3 هر فایل دیگر در پوشه است. costها از نرخ‌های اندازه‌گیری‌شده فصل 16 برای gpt-5.6-terra استفاده می‌کنند، $2.00 به‌ازای هر میلیون input token و $0.20 به‌ازای هر میلیون cached input token، اعمال‌شده به آن countها — آن‌ها حساب روی tokenهای اندازه‌گیری‌شده‌اند، نه مشاهده bill زنده. هیچ API پولی برای نوشتن این فصل call نشد.

آزمایش activation، Qwen/Qwen2.5-0.5B-Instruct را با half precision روی یک consumer GPU، greedy decoding، 24 درخواست روی شش skill، دو بار اجرا کرد — یک‌بار با descriptionهایی که می‌گویند skill چه می‌کند و چه زمانی apply می‌شود، یک‌بار با descriptionهایی که به موضوع عریان در سبک «poor example» خود specification کوتاه شده بودند. intervalها Wilson در 95٪ هستند؛ مقایسه paired یک exact sign test دوسویه روی ده case discordant است؛ Wilson interval از فصل 4 و exact paired sign test از فصل 15 است، هر دو بدون تغییر reuse شده‌اند. بزرگی‌ها را property یک مدل بسیار کوچک بخوانید و method را قابل‌انتقال.

پنج skill اندازه‌گیری‌شده اینجا packageهای third-party هستند، نه نوشته‌شده برای این فصل: 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. countهای داخلی آن‌ها — 70 فایل rule، AGENTS.md با 26,362 token، metadata.json مورخ January 2026 و با claim «40+ rule» — از فایل‌های روی disk در 7 September 2026 خوانده شدند و ویژگی‌های همان نسخه منتشرشده‌اند، نه نقد نویسندگانشان: هرکدامشان همان نوع driftی است که در هر documentation tree که بیشتر از شمارش شدن ویرایش می‌شود ظاهر می‌شود.