Agent Skills і SKILL.md: прогресивне розкриття, виміряне

Розділ 14 встановив правило для другої половини цього курсу — підключення, повторні спроби й скасування пишуться на TypeScript — і оголосив п’ять винятків. Це один із них, і причина не в уподобанні.

Skill — це Markdown-файл. Не файл, який налаштовує програму, не файл, який програма компілює: це документ, який модель читає, так само, як читає повідомлення, яке ви ввели. Дати цьому розділу мову програмування означало б не зрозуміти формат, а саме це нерозуміння є найпоширенішим щодо skills. Усе нижче — Markdown і YAML, плюс один невеликий shell script, який існує саме для того, щоб показати, де код має і не має бути всередині skill.

Ось реальна інструкція: як одна компанія пише свої release notes. Це процедура, а не вподобання — вона має впорядкований набір кроків, таксономію, голос, шаблон і 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 стабільний і стоїть першим, що робить його найкращим кандидатом для cache; за $0.20 за мільйон cached input ті самі 68 640 token коштують $0.0168, а не $0.1373. Усе ще втричі більше за skill, але вже не інший порядок величини.

Гроші ніколи не були найсильнішим аргументом. Ось він:

Caching робить постійний префікс дешевшим. Він не робить його меншим.

На 40-му ході версія з system-prompt усе ще має 1 716 token політики release-note у вікні під час розмови про щось зовсім інше, конкуруючи за те, що розділ 24 назвав attention budget моделі. Версія зі skill має 46. Закешуйте не те — і ви купили знижку на відволікання.

Записано як формулу, де $n$ — ходи, $L_1$ — metadata, $L_2$ — body, $L_3$ — увесь bundle, а $R$ — набір bundled files, які фактично прочитано:

Увесь цей розділ — це різниця між множенням другого доданка на $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 для 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. Це не політика — це зміст із порядком операцій. Політика живе в трьох файлах, які він називає, але не включає. А перший крок передає роботу script, бо код script узагалі ніколи не потрапляє в context window: потрапляє лише його output.²

Модель завантаження має назву й три етапи. Специфікація подає їх із прив’язаним token budget:¹

1. Metadata, приблизно 100 token: name і description, завантажуються під час запуску для кожного встановленого skill.
2. Instructions, рекомендовано менше 5 000 token: body SKILL.md, завантажується, коли skill активовано.
3. Resources, за потреби: bundled files, завантажуються лише тоді, коли щось їх потребує.

Довідкова документація додає до тієї самої таблиці четвертий стовпець — коли завантажується, token cost, content — і рядок, який має значення, третій: нічого, доки не буде звернення.³ Речення, яке підсумовує весь розділ, також там:

Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.³

Виміряна таблиця на початку цього розділу — це перевірка цієї заяви на п’яти skill, які ніхто не писав для цієї статті. Два рядки варто читати один проти одного.

next-best-practices має body на 966 token, який посилається на дев’ятнадцять файлів із 19 374 token. Попросіть його виправити hydration error — і agent прочитає body плюс hydration-error.md: 1 409 token із 20 340, коефіцієнт чотирнадцять, а інші вісімнадцять файлів так і не відкриються.

next-cache-components має body на 2 334 token і взагалі не має bundled files. Це валідний skill і добре написаний skill, але в нього немає рівня 3 для розкриття. Це чесна межа техніки: progressive disclosure економить лише тоді, коли є що відкласти. Skill, знання якого не розкладається, платить увесь свій body під час активації, і єдиний важіль, що лишається, — не активувати його.

Рівень 1 — це рішення routing, ухвалене з одного речення. Ніщо інше про skill не впливає на те, чи його колись відкриють: ні якість body, ні приклади, ні scripts. Тому description — не документація. Це query surface, і вона може бути неправильною.

Специфікація каже це у формі гарного й поганого прикладу, і поганий приклад має чотири слова: description: Helps with PDFs.¹ Це варто виміряти, а не просто прийняти.

Шість skill, кожен із правдоподібним description, яке каже, що він робить і коли його використовувати. Двадцять чотири запити, по чотири на skill, сформульовані так, як їх сформулювала б людина, і ніколи не називаючи skill. Модель бачить шість рядків у своєму system prompt і має відповісти однією назвою або NONE. Greedy decoding, тож це відтворюється. Потім ті самі двадцять чотири запити з тими самими шістьма skill, але descriptions урізані до голої теми.

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: вони перекриваються, і двадцять чотири випадки не можуть ранжувати дві системи лише за їхніми агрегатами. Вирішує paired comparison, і це інструмент розділу 15: із десяти випадків, де дві гілки не збіглися, дев’ять пішли до багатих descriptions і один — до тонких. Це встановлено на звичному порозі.

Тепер читайте останній рядок — фактичну знахідку. З тонкими descriptions модель відповіла 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 інструмента підняла форматування дат із 2 правильних із 24 до 24 із 24. Тут зміна лише description skill піднімає активацію з 10 із 24 до 18. В обох випадках найдешевше виправлення в системі — речення, і в обох випадках це речення має називати trigger, а не лише тему: не що це за річ, а що користувач щойно сказав, коли вона застосовується.

Одне застереження, яке цей розділ винен власним стандартам. Це модель на пів мільярда parameter, а frontier model маршрутизує значно краще за 75 %. Читайте механізм, а не величину: routing signal має довжину одного речення незалежно від того, яка модель його читає, і жодна модель не може вибирати за інформацією, яку ви не внесли в це речення.

Друга помилка протилежна першій. Skill знайдено, рівні розділено правильно, і agent все одно читає все.

vercel-react-best-practices — справді добре зібраний skill. Його body на 1 670 token — це priority table з восьми категорій і quick reference, де названо 70 rule files, по одному рядку кожен. Правила лежать на диску поруч: 70 файлів, найменший 132 token, медіана 319, найбільший 1 052. Поставте йому одне питання про barrel imports — і чесна вартість буде 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 files, склеєних разом: їхня сума 25 784, а різниця — заголовки між ними. Тож skill пропонує agent вибір між читанням одного медіанного правила за 319 token і читанням того самого content, усього, за ціною у вісімдесят три рази вищою — і пропонує цей вибір реченням без зазначеної вартості й без умови, коли це варто робити.

Це не bug, і файл не неправильний; скомпільований документ справді корисний людині й agent, якого попросили проаудитити весь codebase. Це level-3 file with a level-2 invitation, і урок узагальнюється за межі цього одного skill: кожен шлях із SKILL.md має казати, скільки він коштує і коли вартий цього, бо модель не має способу знати, що одна назва файлу у вісімдесят три рази дорожча за назву файлу над нею.

Та сама папка несе менший урок про застарівання. Body каже «70 rules across 8 categories» і перелічує 70; директорія rules/ містить 72 файли, з яких два — scaffolding (_template.md і _sections.md); а sidecar metadata.json каже «40+ rules». Три підрахунки одного й того самого набору в одній папці: один правильний, один арифметичний, і один залишився від попередньої версії. Skill — це документ, а документи гниють точно так само, як comment у коді, що розійшовся з кодом поруч із ним, — з тією різницею, що цей читає машина, яка не підніме брову.

Відкрита специфікація визначає шість frontmatter fields. Reference implementation, Claude Code, приймає двадцять.² П’ять груп варто знати на ім’я, бо саме там формат перестає бути лише документом:

Arguments (arguments, argument-hint) дозволяють людині передавати значення, які підставляються в body, і саме це робить skill придатним як slash command. Scoping (paths) обмежує активацію файлами, що відповідають glob. А dynamic context injection — це те, що змінює mental model: рядок форми !`git diff HEAD` запускається до того, як body буде надіслано, і його output підставляється в текст. Документ — це template, і частина його обчислюється під час читання.

Тепер пастка, і вона сформульована в тій самій документації: поза Claude Code — у web product, через Skills API, у packaging — дозволено лише шість полів зі специфікації, а будь-яке інше поле є hard error під час upload.² Тож skill, який ідеально працює в одному продукті, не встановлюється в іншому продукті того самого постачальника, і ламається на frontmatter, а не на чомусь, що ви могли б перевірити, прочитавши prose. Якщо ви хочете, щоб skill був переносимим, шість полів — це весь budget. Якщо ні, скажіть про це в compatibility, яке існує саме для цього.

Чотири речі постійно плутають між собою, і ця плутанина — не словникова педантичність: неправильний вибір коштує грошей на кожному ході або коштує вам гарантії, яку ви думали, що маєте.

Два рядки жирним — це вся відмінність. Skill читають; інструмент викликають. Skill — це prose, який приходить у context window і конкурує за attention з усім іншим там; модель може йому слідувати, неправильно прочитати або проігнорувати, і ніщо в системі цього не помітить. Інструмент — це виклик, який повністю виходить із рук моделі: ваш код отримує arguments, validates їх, перевіряє permissions і вирішує. Розділ 18 сформулював це як модель пропонує, а ваш код розпоряджається, і саме цього поділу skill не має.

Отже, шість реальних випадків, розв’язаних:

Історія коротка, незвично добре датована, і це та частина, яку майже ніхто не розповідає.

Agent Skills було опубліковано 16 жовтня 2025 року як функцію одного vendor, визначену в тому оголошенні як «organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks», із трьома рівнями, описаними через аналогію, яку варто зберегти: «like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix».⁴

18 грудня 2025 року ту саму сторінку оновили, щоб оголосити формат open standard, із власною специфікацією на agentskills.io, governance, відкритим для contributions, і reference validator.³ Станом на 7 вересня 2026 року showcase клієнтів стандарту перелічує сорок шість продуктів — editors, terminals, cloud platforms і mobile runtimes, зокрема first-party coding agents від Anthropic, OpenAI, Google і Mistral — кожен із посиланням на власну setup documentation.¹

Зближення з MCP робиться відкрито, з числами, які можна перевірити:

Цікава частина — closure, а не proposals. SEP-2076 просив четвертий primitive поруч із tools, resources і prompts. Working group, що сформувалася з нього, вирішила, що відповідь — ні: skills їдуть на resources primitive, який уже існує, як opt-in extension.⁵ Розділ 26 виміряв той самий інстинкт у changelog самого protocol, де sampling, roots і logging були deprecated, а не збережені. Standards body, який прибирає proposal, authored ним самим, поводиться добре, і причина розповідати цю історію з числами попереду в тому, що summaries, які ви прочитаєте деінде, усе ще описують skills як MCP primitive.

Тепер ви можете написати SKILL.md, розділити його на три рівні, які окупають себе, прочитати frontmatter чужого skill і знати, які fields не переживуть upload кудись іще, а також відповісти на питання, довкола якого був побудований увесь розділ — system prompt, skill, tool чи server — із причиною, а не за звичкою.

Чого ви не можете зробити — це сказати, чи ваш працює.

Кожне твердження в цьому розділі, яке мало значення, було вимірюванням, і найважливіше з них було accuracy: 18 із 24 проти 10 із 24, з інтервалом на кожному і paired test між ними, бо два aggregates, що перекриваються, нічого не вирішують. Цей інструмент було позичено. Description skill — це routing key, його body — procedure, якої модель може дотриматися або ні, і обидві ці властивості можна з’ясувати лише запускаючи річ багато разів і scoring те, що повернулося, — тобто golden set, grader, який ви написали до запуску, і metric, яка питає, чи спрацювало це кожного разу, а не хоч раз.

Розділ 29 — саме про це, і він починається з числа, від якого залежить метод цього розділу: agent, який успішний сім разів із десяти, виглядає як 70 %, а його pass^10 — шанс успіху в усіх десяти — дорівнює нулю. Він також вимірює три graders на тих самих двохстах transcripts і отримує 0 %, 13 % і 26 %, не regenerating жодного token. Перш ніж довіряти реченню, яке ви щойно вписали в description, вам потрібен інструмент, який скаже, що воно гірше за те, яке ви замінили.

Кожен token count у цьому розділі було отримано локально за допомогою tiktoken 0.14.0 і encoding o200k_base, 7 вересня 2026 року: на п’яти third-party skill, перелічених на початку цього розділу, і на skill release-notes, написаному для цього розділу, повний текст якого частково відтворено вище. Level 1 вимірюється як один рядок - name: description, який host рендерить у system prompt; level 2 — це body SKILL.md після frontmatter; level 3 — кожен інший файл у папці. Costs використовують виміряні в розділі 16 тарифи для gpt-5.6-terra, $2.00 за мільйон input tokens і $0.20 за мільйон cached input tokens, застосовані до цих counts, — це арифметика на виміряних token, а не спостереження live bill. Жоден paid API не викликався для написання цього розділу.

Експеримент активації запускав Qwen/Qwen2.5-0.5B-Instruct у half precision на одній consumer GPU, greedy decoding, 24 запити на шість skill, двічі — один раз із descriptions, які зазначають, що skill робить і коли застосовується, один раз із descriptions, урізаними до голої теми в стилі власного «poor example» специфікації. Інтервали — Wilson на 95 %; paired comparison — двосторонній exact sign test на десяти discordant cases; Wilson interval — із розділу 4, а exact paired sign test — із розділу 15, обидва повторно використані без змін. Читайте magnitudes як властивість дуже малої моделі, а method — як переносимий.

П’ять skill, виміряних тут, — third-party packages, не написані для цього розділу: 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. Їхні internal counts — 70 rule files, AGENTS.md на 26 362 token, metadata.json dated January 2026 і claiming «40+ rules» — були прочитані з файлів на диску 7 вересня 2026 року й є properties тієї published version, а не criticism їхніх authors: кожен із них — саме той вид drift, який з’являється в будь-якому documentation tree, який редагують частіше, ніж рахують.