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

Глава 14 зададе правилото за втората половина на този курс — връзките, повторните опити и отмяната са TypeScript — и обяви пет изключения. Това е едно от тях, и причината не е предпочитание.

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

Ето реална инструкция: как една компания пише release notes. Това е процедура, не предпочитание — има подреден набор от стъпки, таксономия, voice, template и script, който събира суровия материал.

Сложете всичко това в system prompt, както правят повечето екипи, и аритметиката от Глава 16 поема управлението. System prompt е prefix, а prefix се плаща при всяко извикване. Измерено с 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 за милион cached input същите 68 640 token струват $0.0168 вместо $0.1373. Все още три пъти повече от skill, но вече не е различен порядък.

Парите никога не са били най-силният аргумент. Ето го него:

Caching прави постоянния prefix по-евтин. Не го прави по-малък.

На ход 40 версията със system-prompt все още има 1 716 token политика за release notes, седяща в window по време на разговор за нещо съвсем друго, конкурирайки се за онова, което Глава 24 нарече attention budget на модела. Версията със skill има 46. Cache-нете грешното нещо и сте купили отстъпка за разсейване.

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

Цялата тази глава е разликата между това да умножите втория член по $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, защото code на script никога не влиза в context window: влиза само неговият output.²

Моделът на зареждане има име и три етапа. Спецификацията ги описва с приложен token бюджет:¹

1. Metadata, около 100 token: name и description, зареждани при старт за всеки инсталиран skill.
2. Instructions, препоръчително под 5 000 token: body на SKILL.md, зареждан, когато skill се активира.
3. Resources, според нуждата: bundle файлове, зареждани само когато нещо ги изисква.

Референтната документация поставя четвърта колона в същата таблица — кога се зарежда, 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 и изобщо няма bundle файлове. Това е валиден skill и добре написан такъв, и няма ниво 3 за разкриване. Това е честният предел на техниката: progressive disclosure спестява само ако има нещо за отлагане. Skill, чието знание не се разлага, плаща целия си body при активация, а единственият оставащ лост е да не се активира.

Ниво 1 е routing решение, взето от едно изречение. Нищо друго за skill не влияе дали той някога ще бъде отворен — нито качеството на body, нито примерите, нито scripts. Затова описанието не е документация. То е query surface, и може да бъде грешно.

Спецификацията го казва под формата на добър и лош пример, а лошият е четири думи: 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

Перфектен sql-review skill беше инсталиран, с body, примери и checklist, и той никога не беше отворен, три пъти поред, по трите въпроса, за които беше написан. Нива 2 и 3 са без значение за skill, до който ниво 1 никога не стига.

Цената да го поправите: 214 token, разликата между 295 и 81, разпределена върху шест skill. Което е откритието от Глава 18, идващо от другата страна. Там промяна само в описанието на инструмент изведе date formatting от 2 правилни от 24 до 24 от 24. Тук промяна само в описанието на skill вдига активацията от 10 от 24 до 18. И в двата случая най-евтината поправка в системата е изречение, и в двата случая изречението трябва да назове trigger, а не само предмета: не какво е нещото, а какво потребителят току-що ще е казал, когато то се прилага.

Една уговорка, която тази глава дължи на собствените си стандарти. Това е модел с половин милиард параметри, а frontier model route-ва далеч по-добре от 75 %. Четете механизма, не величината: routing сигналът е дълъг едно изречение, който и модел да го чете, и никой модел не може да избира по информация, която не сте сложили в това изречение.

Вторият провал е обратното на първия. Skill е намерен, нивата са правилно разделени, и agent така или иначе прочита всичко.

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

Това не е bug и файлът не е грешен; compiled документ е наистина полезен за човек и за 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 е документ, а документите гният точно като code comment, който се е отдалечил от кода до себе си — с разликата, че този се чете от машина, която няма да повдигне вежда.

Отворената спецификация дефинира шест frontmatter полета. Референтната имплементация, Claude Code, приема двадесет.² Пет групи си струва да знаете по име, защото те са мястото, където форматът спира да бъде само документ:

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

Сега капанът, и той е заявен в същата документация: извън Claude Code — в web продукта, през Skills API, при packaging — разрешени са само шестте специфицирани полета, а всяко друго поле е hard error при upload.² Така skill, който работи перфектно в един продукт, не успява да се инсталира в друг на същия vendor, и се проваля във frontmatter, а не в нещо, което бихте могли да тествате, като прочетете прозата. Ако искате skill да бъде преносим, шестте полета са целият бюджет. Ако не искате, кажете го в compatibility, което съществува точно за това.

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

Двата реда в bold са цялото разграничение. Skill се чете; инструмент се извиква. Skill е проза, която пристига в context window и се конкурира за attention с всичко останало там; моделът може да я следва, да я прочете погрешно или да я игнорира, и нищо в системата не забелязва. Инструментът е call, който напълно излиза от ръцете на модела: вашият code получава аргументи, валидира ги, проверява permissions и решава. Глава 18 го формулира като моделът предлага, а вашият code разпорежда, и това разделение е точно онова, което 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 г. същата страница беше обновена, за да обяви формата като отворен стандарт, със собствена спецификация на agentskills.io, governance отворено за contributions и референтен validator.³ Прочетен на 7 септември 2026 г., showcase на clients на стандарта изброява четиридесет и шест продукта — editors, terminals, cloud platforms и mobile runtimes, включително first-party coding agents на Anthropic, OpenAI, Google и Mistral — всеки с линк към собствената си setup документация.¹

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

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

Вече можете да напишете SKILL.md, да го разделите на три нива, които се изплащат сами, да прочетете frontmatter на чужд skill и да знаете кои полета няма да преживеят upload някъде другаде, и да отговорите на въпроса, около който е изградена цялата глава — system prompt, skill, tool или server — с причина, а не по навик.

Това, което не можете, е да кажете дали вашият работи.

Всяко твърдение в тази глава, което имаше значение, беше измерване, а най-важното беше accuracy: 18 от 24 срещу 10 от 24, с интервал за всяко и paired test между тях, защото два агрегата, които се припокриват, не решават нищо. Този инструмент беше зает. Описанието на skill е routing key, неговият body е процедура, която моделът може или не може да следва, и двете са свойства, за които можете да разберете само като пуснете нещото много пъти и оцените какво се е върнало — което е golden set, grader, който сте написали преди run, и metric, който пита дали е сработило всеки път, а не поне веднъж.

Глава 29 е това, и тя започва с числото, от което зависи методът на тази глава: agent, който успява седем пъти от десет, изглежда като 70 %, а неговото pass^10 — шансът да успее и в десетте — е нула. Тя също измерва три graders върху същите двеста transcripts и получава 0 %, 13 % и 26 %, без да регенерира нито един token. Преди да се доверите на изречението, което току-що сте написали в description, ви трябва инструментът, който може да ви каже, че то е по-лошо от онова, което сте заменили.

Всеки token count в тази глава беше произведен локално с tiktoken 0.14.0 и encoding o200k_base, на 7 септември 2026 г.: върху петте third-party skill, изброени в началото на тази глава, и върху skill release-notes, написан за тази глава, чийто пълен текст е възпроизведен частично по-горе. Ниво 1 се измерва като единичния ред - name: description, който host render-ва в system prompt; ниво 2 е body на SKILL.md след frontmatter; ниво 3 е всеки друг файл в папката. Разходите използват измерените в Глава 16 тарифи за gpt-5.6-terra, $2.00 за милион input token и $0.20 за милион cached input token, приложени към тези counts — те са аритметика върху измерени token, не наблюдения на жива сметка. Не е извикан платен API за написването на тази глава.

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

Петте 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. Техните вътрешни counts — 70 rule files, AGENTS.md на 26 362 token, metadata.json с дата януари 2026 г. и твърдение „40+ rules“ — бяха прочетени от файловете на диска на 7 септември 2026 г. и са свойства на тази публикувана версия, не критики към авторите ѝ: всяко от тях е вид drift, който се появява във всяко documentation tree, което се редактира по-често, отколкото се брои.