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

Глава 14 установила правило для второй половины этого курса — подключения, повторы и отмена пишутся на TypeScript — и объявила пять исключений. Это одно из них, и причина не во вкусе.

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

Вот реальная инструкция: как одна компания пишет release notes. Это процедура, а не предпочтение — у неё есть упорядоченный набор шагов, таксономия, голос, шаблон и скрипт, который собирает сырой материал.

Положите всё это в 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 политики release notes во время разговора о чём-то совершенно другом, конкурируя за то, что глава 24 назвала бюджетом attention модели. В версии со 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. Это не политика — это оглавление с порядком операций. Политика живёт в трёх файлах, которые он называет и не включает. А первый шаг передаёт работу скрипту, потому что code скрипта вообще никогда не попадает в context window: попадает только его вывод.²

У модели загрузки есть имя и три стадии. Спецификация формулирует их с привязанным бюджетом token:¹

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

Справочная документация добавляет к той же таблице четвёртую колонку — когда загружается, стоимость в token, содержимое — и важная строка третья: ничего до обращения.³ Там же есть фраза, которая резюмирует всю главу:

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, ни примеры, ни скрипты. Поэтому описание — не документация. Это поверхность запроса, и она может быть неправильной.

Спецификация говорит об этом через хороший и плохой пример, и плохой — это четыре слова: description: Helps with PDFs.¹ Это стоит измерить, а не просто принять.

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

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, с body, примерами и чек-листом, и он ни разу не был открыт — три раза подряд, на трёх вопросах, ради которых был написан. Уровни 2 и 3 не имеют значения для skill, до которого уровень 1 никогда не доходит.

Стоимость исправления: 214 token, разница между 295 и 81, распределённая по шести skill. Это вывод главы 18, пришедший с другой стороны. Там изменение только описания инструмента подняло форматирование дат с 2 правильных из 24 до 24 из 24. Здесь изменение только описания skill поднимает активацию с 10 из 24 до 18. В обоих случаях самое дешёвое исправление в системе — предложение, и в обоих случаях предложение должно называть trigger, а не только предмет: не что это такое, а что пользователь только что сказал, когда это применимо.

Одна оговорка, которую эта глава должна собственным стандартам. Это модель с половиной миллиарда параметров, и frontier model маршрутизирует намного лучше, чем 75 %. Читайте механизм, а не величину: routing-сигнал имеет длину в одно предложение независимо от того, какая модель его читает, и ни одна модель не может выбирать по информации, которую вы не вложили в это предложение.

Вторая поломка противоположна первой. Skill найден, уровни правильно разделены, и agent всё равно читает всё.

vercel-react-best-practices — действительно хорошо построенный skill. Его body на 1 670 token — это таблица приоритетов из восьми категорий и краткий справочник, называющий 70 файлов правил, по одной строке на каждый. Правила лежат на диске рядом: 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 файлов правил: их сумма — 25 784, а разница — заголовки между ними. Значит, skill предлагает agent выбор между чтением одного медианного правила на 319 token и чтением того же содержимого, целиком, по цене в восемьдесят три раза выше — и предлагает этот выбор в предложении без указания стоимости и без условия, когда его делать.

Это не bug, и файл не неправильный; скомпилированный документ действительно полезен человеку и agent, которого попросили провести аудит всей codebase. Это файл уровня 3 с приглашением уровня 2, и урок обобщается дальше этого одного skill: каждый путь из SKILL.md должен говорить, сколько он стоит и когда он того стоит, потому что у модели нет способа узнать, что имя файла в восемьдесят три раза дороже имени файла над ним.

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

Открытая спецификация определяет шесть полей frontmatter. Эталонная реализация, Claude Code, принимает двадцать.² Пять групп стоит знать по именам, потому что именно там формат перестаёт быть только документом:

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

Теперь ловушка, и она сформулирована в той же документации: вне Claude Code — в веб-продукте, через Skills API, при упаковке — разрешены только шесть указанных полей, а любое другое поле является жёсткой ошибкой при загрузке.² Поэтому skill, который идеально работает в одном продукте, не устанавливается в другом продукте того же поставщика, и ломается он на frontmatter, а не на чём-то, что можно было бы проверить чтением прозы. Если вы хотите, чтобы skill был переносимым, шесть полей — весь ваш бюджет. Если нет, скажите это в compatibility, который существует ровно для этого.

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

Две строки жирным — всё различие. Skill читают; инструмент вызывают. Skill — это проза, которая попадает в context window и конкурирует за attention со всем остальным там; модель может ей следовать, неверно её прочитать или проигнорировать, и ничто в системе этого не заметит. Инструмент — это вызов, который полностью покидает руки модели: ваш code получает аргументы, валидирует их, проверяет разрешения и принимает решение. Глава 18 сформулировала это как «модель предлагает, а ваш code распоряжается», и именно этого разделения у skill нет.

Итак, шесть реальных случаев, с решениями:

История короткая, необычно хорошо датированная, и именно эту часть почти никто не рассказывает.

Agent Skills были опубликованы 16 октября 2025 года как функция одного поставщика, определённая в том анонсе как «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 года та же страница была обновлена и объявила формат открытым стандартом, с собственной спецификацией по адресу agentskills.io, governance, открытым для contributions, и reference validator.³ При чтении 7 сентября 2026 года витрина клиентов стандарта перечисляла сорок шесть продуктов — редакторы, терминалы, облачные платформы и мобильные runtimes, включая first-party coding agents Anthropic, OpenAI, Google и Mistral, — каждый со ссылкой на собственную документацию по настройке.¹

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

Интересны не предложения, а закрытие. SEP-2076 просил четвёртый primitive рядом с tools, resources и prompts. Working group, выросшая из него, решила, что ответ — нет: skills едут на уже существующем primitive resources как opt-in extension.⁵ Глава 26 измерила тот же инстинкт в собственном changelog протокола, где sampling, roots и logging были deprecated, а не сохранены. Standards body, которое удаляет собственное предложение, ведёт себя правильно, и причина рассказывать эту историю с числами перед глазами в том, что summaries, которые вы прочитаете в других местах, всё ещё описывают skills как MCP primitive.

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

Чего вы не можете сделать — так это сказать, работает ли ваш.

Каждое важное утверждение в этой главе было измерением, а самое важное — точностью: 18 из 24 против 10 из 24, с интервалом у каждого и парным тестом между ними, потому что два перекрывающихся агрегата ничего не решают. Этот инструмент был заимствован. Описание skill — это routing key, его body — процедура, которой модель может следовать или не следовать, и обе эти свойства можно выяснить только запустив вещь много раз и оценив то, что вернулось, — а это golden set, grader, который вы написали до запуска, и метрика, которая спрашивает, сработало ли это каждый раз, а не хотя бы один раз.

Глава 29 — об этом, и она начинается с числа, от которого зависит метод этой главы: agent, который добивается успеха семь раз из десяти, выглядит как 70 %, а его pass^10 — шанс добиться успеха во всех десяти — равен нулю. Она также измеряет три grader на одних и тех же двухстах транскриптах и получает 0 %, 13 % и 26 %, не регенерируя ни одного token. Прежде чем доверять предложению, которое вы только что записали в description, вам нужен инструмент, способный сказать, что оно хуже того, которое вы заменили.

Каждый подсчёт token в этой главе был произведён локально с tiktoken 0.14.0 и encoding o200k_base, 7 сентября 2026 года: по пяти сторонним skill, перечисленным в начале этой главы, и по skill release-notes, написанному для этой главы, чей полный текст частично воспроизведён выше. Уровень 1 измеряется как единственная строка - name: description, которую host рендерит в system prompt; уровень 2 — body SKILL.md после frontmatter; уровень 3 — любой другой файл в папке. Стоимости используют измеренные в главе 16 тарифы для gpt-5.6-terra: $2.00 за миллион входных token и $0.20 за миллион кэшированных входных token, применённые к этим counts — это арифметика по измеренным token, а не наблюдения живого счёта. Ни один платный API не был вызван для написания этой главы.

Activation experiment запускал Qwen/Qwen2.5-0.5B-Instruct в half precision на одном потребительском GPU, greedy decoding, 24 запроса по шести skill, дважды — один раз с описаниями, которые говорят, что skill делает и когда применяется, один раз с описаниями, сокращёнными до голой темы в стиле собственного «poor example» спецификации. Интервалы — Wilson на 95 %; парное сравнение — двухсторонний exact sign test по десяти discordant cases; Wilson interval взят из главы 4, exact paired sign test — из главы 15, оба использованы без изменений. Читайте величины как свойство очень маленькой модели, а метод — как переносимый.

Пять skill, измеренных здесь, — сторонние пакеты, а не написанные для этой главы: 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. Их внутренние counts — 70 файлов правил, AGENTS.md на 26 362 token, metadata.json с датой январь 2026 и утверждением «40+ rules» — были прочитаны из файлов на диске 7 сентября 2026 года и являются свойствами этой опубликованной версии, а не критикой её авторов: каждый из них — тот самый drift, который появляется в любом documentation tree, редактируемом чаще, чем его пересчитывают.