Agent Skills a SKILL.md: postupné odhalování, změřeno

Kapitola 14 stanovila pravidlo pro druhou polovinu tohoto kurzu — připojení, opakování a rušení jsou TypeScript — a vyhlásila pět výjimek. Tohle je jedna z nich a důvodem není preference.

Skill je soubor Markdown. Ne soubor, který konfiguruje program, ne soubor, který program kompiluje: dokument, který model čte, stejně jako čte zprávu, kterou jste napsali. Dát této kapitole programovací jazyk by znamenalo nepochopit formát, a právě toto nepochopení je u skillů ze všech nejběžnější. Všechno níže je Markdown a YAML, plus jeden malý shellový skript, který existuje přesně proto, aby ukázal, kam code uvnitř skillu patří a kam ne.

Tady je skutečná instrukce: jak jedna firma píše své poznámky k vydání. Je to postup, ne preference — má seřazenou sadu kroků, taxonomii, hlas, šablonu a skript, který sbírá surový materiál.

Vložte to celé do system promptu, jak to dělá většina týmů, a převezme řízení aritmetika kapitoly 16. System prompt je prefix a za prefix se platí při každém volání. Změřeno pomocí o200k_base nad složkou napsanou pro tuto kapitolu:

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

Dvacet čtyřikrát levnější, když se použije, třicet sedmkrát levnější, když se nepoužije. Sazby jsou z kapitoly 16: $2.00 za milion vstupních tokenů.

Teď poctivá námitka, protože kapitola, která by ji přeskočila, by byla reklama. Prompt caching většinou zavře finanční mezeru. System prompt je stabilní a sedí na začátku, což z něj dělá nejlepšího kandidáta na cache; při $0.20 za milion cachovaného vstupu stojí stejných 68 640 tokenů $0.0168 místo $0.1373. Pořád třikrát tolik co skill, ale už ne jiný řád.

Peníze nikdy nebyly nejsilnější argument. Tím je tohle:

Caching zlevní trvalý prefix. Nezmenší ho.

V tahu 40 má verze se system promptem stále 1 716 tokenů politiky poznámek k vydání v okně během konverzace o něčem úplně jiném, kde soutěží o to, čemu kapitola 24 říkala attention budget modelu. Verze se skill má 46. Cachujte špatnou věc a koupili jste si slevu na rozptýlení.

Zapsáno jako vzorec, s $n$ tahy, $L_1$ jako metadata, $L_2$ jako tělo, $L_3$ jako celý balík a $R$ jako množina přibalených souborů, které se skutečně přečtou:

Celá tato kapitola je rozdíl mezi násobením druhého členu $n$ a jeho násobením jedničkou nebo nulou.

Skill je adresář. Specifikace je dost krátká na to, aby šla uvést celá:

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 musí začínat YAML frontmatter a vyžadována jsou přesně dvě pole: name a description.¹ Čtyři další jsou volitelná a žádná jiná nejsou definována:

Tady je skill pro poznámky k vydání, celý, s tělem pod třicet řádků:

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

Přečtěte si, co to tělo je. Není to politika — je to obsah s pořadím operací. Politika žije ve třech souborech, které jmenuje a nevkládá. A krok jedna předává práci skriptu, protože code skriptu se do context window nikdy nedostane: pouze jeho výstup.²

Model načítání má jméno a tři fáze. Specifikace je uvádí s připojeným rozpočtem tokenů:¹

1. Metadata, asi 100 tokenů: name a description, načtené při startu pro každý nainstalovaný skill.
2. Instrukce, doporučeno pod 5 000 tokenů: tělo SKILL.md, načtené při aktivaci skillu.
3. Zdroje, podle potřeby: přibalené soubory, načtené jen tehdy, když je něco vyžaduje.

Referenční dokumentace přidává do stejné tabulky čtvrtý sloupec — kdy se načte, cena v tokenech, obsah — a řádek, na kterém záleží, je třetí: nic, dokud se k tomu nepřistoupí.³ Věta, která shrnuje celou kapitolu, je tam také:

Soubory nespotřebovávají context, dokud se k nim nepřistoupí, takže Skills mohou obsahovat rozsáhlou API dokumentaci, velké datasety nebo rozsáhlé příklady. Za přibalený obsah, který se nepoužije, nevzniká žádná context penalizace.³

Naměřená tabulka na začátku této kapitoly je ověřením tohoto tvrzení na pěti skillech, které nikdo nepsal pro tento článek. Dva řádky si zaslouží číst proti sobě.

next-best-practices má 966tokenové tělo, které odkazuje na devatenáct souborů obsahujících 19 374 tokenů. Požádejte ho, aby opravil hydration error, a agent přečte tělo plus hydration-error.md: 1 409 tokenů z 20 340, faktor čtrnáct, a ostatních osmnáct souborů se nikdy neotevře.

next-cache-components má 2 334tokenové tělo a vůbec žádné přibalené soubory. Je to platný skill a dobře napsaný skill, ale nemá žádnou úroveň 3 k odhalení. To je poctivý limit techniky: postupné odhalování šetří jen tehdy, když je co odložit. Skill, jehož znalost se nerozkládá, zaplatí při aktivaci celé své tělo a jedinou zbývající pákou je neaktivovat ho.

Úroveň 1 je směrovací rozhodnutí udělané z jedné věty. Nic jiného na skillu neovlivňuje, zda bude vůbec otevřen — ne kvalita těla, ne příklady, ne skripty. Popis tedy není dokumentace. Je to query surface a může být špatně.

Specifikace to říká formou dobrého a špatného příkladu a ten špatný má čtyři slova: description: Helps with PDFs.¹ To stojí za změření, ne za pouhé přijetí.

Šest skillů, každý s uvěřitelným popisem, který říká, co dělá a kdy ho použít. Dvacet čtyři požadavků, čtyři na skill, formulovaných tak, jak by je formuloval člověk, a nikdy nejmenujících skill. Model vidí šest řádků ve svém system promptu a musí odpovědět jedním názvem nebo NONE. Greedy decoding, takže je to reprodukovatelné. Potom stejných dvacet čtyři požadavků se stejnými šesti skilly a popisy zkrácenými na holý předmět.

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

Nejdřív čtěte intervaly, jak na tom trvala kapitola 4 a jak na tom bude znovu trvat kapitola 29: překrývají se a dvacet čtyři případů nemůže seřadit dva systémy jen podle jejich agregátů. Rozhoduje párové srovnání a tím je nástroj kapitoly 15: z deseti případů, kde se obě ramena neshodla, šlo devět k bohatým popisům a jeden k tenkým. To je prokázáno na obvyklém prahu.

Teď čtěte poslední řádek, což je skutečné zjištění. S tenkými popisy model odpověděl NONE u devíti z dvaceti čtyř požadavků. Ne špatný skill: žádný skill. Tady jsou čtyři z nich, doslova:

"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

Byl nainstalován dokonalý skill sql-review, s tělem, příklady a checklistem, a nikdy se neotevřel, třikrát po sobě, u tří otázek, pro které byl napsán. Úrovně 2 a 3 jsou pro skill, ke kterému se úroveň 1 nikdy nedostane, irelevantní.

Cena opravy: 214 tokenů, rozdíl mezi 295 a 81, rozložený přes šest skillů. Což je zjištění kapitoly 18 přicházející z druhé strany. Tam změna pouze popisu nástroje posunula formátování dat z 2 správných z 24 na 24 z 24. Tady změna pouze popisu skillu posune aktivaci z 10 z 24 na 18. V obou případech je nejlevnější opravou v systému věta a v obou případech musí věta pojmenovat trigger, nejen předmět: ne co ta věc je, ale co uživatel právě řekl, když se má použít.

Jedno upozornění, které tato kapitola dluží vlastním standardům. Toto je model s půl miliardou parametrů a frontier model směruje mnohem lépe než na 75 %. Čtěte mechanismus, ne velikost: směrovací signál má délku jedné věty bez ohledu na to, který model ho čte, a žádný model nemůže vybírat podle informace, kterou jste do té věty nevložili.

Druhé selhání je opakem prvního. Skill se najde, úrovně jsou správně rozdělené a agent si stejně přečte všechno.

vercel-react-best-practices je skutečně dobře postavený skill. Jeho 1 670tokenové tělo je prioritní tabulka osmi kategorií a stručná reference jmenující 70 souborů pravidel, každý na jednom řádku. Pravidla jsou na disku vedle něj: 70 souborů, nejmenší 132 tokenů, medián 319, největší 1 052. Zeptejte se ho na jednu otázku o barrel imports a poctivá cena je tělo plus jeden soubor — pod 2 400 tokenů proti balíku 53 670.

Pak poslední řádek těla říká toto:

## Full Compiled Document

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

AGENTS.md má 26 362 tokenů. Je to 70 souborů pravidel spojených dohromady: jejich součet je 25 784 a rozdíl jsou nadpisy mezi nimi. Skill tedy nabízí agentovi volbu mezi přečtením jednoho mediánového pravidla za 319 tokenů a přečtením stejného obsahu, celého, za třiaosmdesátinásobnou cenu — a nabízí tuto volbu ve větě bez připojené ceny a bez podmínky, kdy ji zvolit.

To není bug a soubor není špatně; zkompilovaný dokument je skutečně užitečný pro člověka i pro agent, který dostal za úkol auditovat celou codebase. Je to soubor úrovně 3 s pozvánkou úrovně 2 a poučení se zobecňuje i mimo tento jeden skill: každá cesta ven z SKILL.md by měla říkat, kolik stojí a kdy za to stojí, protože model nemá jak vědět, že jeden název souboru je třiaosmdesátkrát dražší než název souboru nad ním.

Stejná složka nese menší lekci o zastarávání. Tělo říká „70 pravidel napříč 8 kategoriemi“ a uvádí 70; adresář rules/ obsahuje 72 souborů, z nichž dva jsou scaffolding (_template.md a _sections.md); a doprovodný metadata.json říká „40+ pravidel“. Tři počty stejné množiny v jedné složce, jeden z nich správný, jeden aritmetický a jeden zbylý z dřívější verze. Skill je dokument a dokumenty hnijí přesně jako komentář v kódu, který se odchýlil od kódu vedle sebe — s tím rozdílem, že tento čte stroj, který nepozdvihne obočí.

Otevřená specifikace definuje šest frontmatter polí. Referenční implementace, Claude Code, jich přijímá dvacet.² Pět skupin stojí za to znát jménem, protože právě tam formát přestává být jen dokumentem:

Argumenty (arguments, argument-hint) umožňují člověku předat hodnoty, které se dosadí do těla, a právě to dělá skill použitelným jako slash command. Scoping (paths) omezuje aktivaci na soubory odpovídající globu. A dynamic context injection je to, co mění mentální model: řádek ve tvaru !`git diff HEAD` běží předtím, než se tělo odešle, a jeho výstup se dosadí do textu. Dokument je šablona a část se počítá v okamžiku čtení.

Teď past, a je uvedena ve stejné dokumentaci: mimo Claude Code — ve webovém produktu, přes Skills API, při balení — je povoleno jen šest specifikovaných polí a jakékoli jiné pole je tvrdá chyba při uploadu.² Skill, který dokonale funguje v jednom produktu, tedy selže při instalaci v jiném produktu stejného dodavatele, a selže na frontmatter, ne na něčem, co byste mohli otestovat čtením prózy. Pokud chcete, aby byl skill přenositelný, šest polí je celý rozpočet. Pokud ne, řekněte to v compatibility, které existuje přesně k tomu.

Čtyři věci se neustále pletou dohromady a zmatek není slovíčkaření: špatná volba stojí peníze v každém tahu nebo vás stojí záruku, o které jste si mysleli, že ji máte.

Dva řádky tučně jsou celý rozdíl. Skill se čte; nástroj se vyvolává. Skill je próza, která přijde do context window a soutěží o attention se vším ostatním, co tam je; model ji může následovat, špatně přečíst nebo ignorovat a nic v systému si toho nevšimne. Nástroj je volání, které modelu úplně opustí ruce: váš code přijme argumenty, ověří je, zkontroluje oprávnění a rozhodne. Kapitola 18 to formulovala jako model navrhuje a váš code rozhoduje, a přesně toto dělení skill nemá.

Tedy šest reálných případů, vyřešených:

Historie je krátká, neobvykle dobře datovaná, a je to část, kterou téměř nikdo nevypráví.

Agent Skills byly zveřejněny 16. října 2025 jako funkce jednoho dodavatele, v oznámení definované jako „organizované složky instrukcí, skriptů a zdrojů, které agenti mohou objevovat a dynamicky načítat, aby lépe plnili konkrétní úlohy“, se třemi úrovněmi popsanými pomocí analogie, kterou stojí za to zachovat: „jako dobře uspořádaný manuál, který začíná obsahem, pokračuje konkrétními kapitolami a končí podrobnou přílohou“.⁴

Dne 18. prosince 2025 byla stejná stránka aktualizována oznámením formátu jako otevřeného standardu, s vlastní specifikací na agentskills.io, governance otevřenou příspěvkům a referenčním validátorem.³ Při čtení 7. září 2026 uvádí klientská přehlídka standardu čtyřicet šest produktů — editory, terminály, cloudové platformy a mobilní runtimes, včetně first-party coding agentů od Anthropic, OpenAI, Google a Mistral — každý s odkazem na vlastní dokumentaci nastavení.¹

Konvergence s MCP probíhá otevřeně, s čísly, která si můžete ověřit:

Zajímavé je uzavření, ne návrhy. SEP-2076 žádal čtvrtý primitive vedle tools, resources a prompts. Pracovní skupina, která z něj vznikla, rozhodla, že odpověď je ne: skills jedou na resource primitive, který už existuje, jako opt-in extension.⁵ Kapitola 26 změřila stejný instinkt ve vlastním changelogu protokolu, kde sampling, roots a logging byly deprecated místo toho, aby zůstaly. Standardizační orgán, který odstraní návrh, jehož je autorem, se chová dobře, a důvodem vyprávět tento příběh s čísly před očima je to, že shrnutí, která budete číst jinde, stále popisují skills jako MCP primitive.

Teď umíte napsat SKILL.md, rozdělit ho do tří úrovní, které si na sebe vydělají, přečíst frontmatter cizího skillu a vědět, která pole nepřežijí upload někam jinam, a odpovědět na otázku, kolem které byla celá kapitola postavená — system prompt, skill, nástroj nebo server — s důvodem místo zvyku.

Co neumíte, je říct, zda ten váš funguje.

Každé tvrzení v této kapitole, na kterém záleželo, bylo měření, a to nejdůležitější byla přesnost: 18 z 24 proti 10 z 24, s intervalem u každého a párovým testem mezi nimi, protože dva agregáty, které se překrývají, nerozhodují nic. Tento nástroj byl vypůjčen. Popis skillu je routing key, jeho tělo je postup, který model může, ale nemusí následovat, a obě tyto vlastnosti zjistíte jen tak, že věc spustíte mnohokrát a ohodnotíte, co se vrátilo — což znamená golden set, grader napsaný před během a metriku, která se ptá, zda to fungovalo pokaždé, ne alespoň jednou.

Kapitola 29 je o tom a začíná číslem, na kterém metoda této kapitoly závisí: agent, který uspěje sedmkrát z deseti, vypadá jako 70 %, a jeho pass^10 — šance, že uspěje ve všech deseti — je nula. Také měří tři graders na stejných dvou stech transcripts a dostane 0 %, 13 % a 26 %, aniž by znovu vygenerovala jediný token. Než začnete věřit větě, kterou jste právě napsali do description, potřebujete nástroj, který vám řekne, že je horší než ta, kterou jste nahradili.

Každý počet tokenů v této kapitole byl vytvořen lokálně pomocí tiktoken 0.14.0 a encoding o200k_base, 7. září 2026: nad pěti skilly třetích stran uvedenými na začátku této kapitoly a nad skill release-notes napsaným pro tuto kapitolu, jehož kompletní text je výše částečně reprodukován. Úroveň 1 je měřena jako jeden řádek - name: description, který host vykreslí do system promptu; úroveň 2 je tělo SKILL.md po frontmatter; úroveň 3 je každý další soubor ve složce. Náklady používají naměřené sazby kapitoly 16 pro gpt-5.6-terra, $2.00 za milion vstupních tokenů a $0.20 za milion cachovaných vstupních tokenů, aplikované na tyto počty — jde o aritmetiku nad změřenými tokeny, ne o pozorování živé faktury. Při psaní této kapitoly nebylo voláno žádné placené API.

Aktivační experiment spustil Qwen/Qwen2.5-0.5B-Instruct v half precision na jedné spotřebitelské GPU, greedy decoding, 24 požadavků přes šest skillů, dvakrát — jednou s popisy, které uvádějí, co skill dělá a kdy se použije, jednou s popisy seříznutými na holý předmět ve stylu vlastního „poor example“ specifikace. Intervaly jsou Wilsonovy na 95 %; párové srovnání je oboustranný exact sign test nad deseti discordant cases; Wilsonův interval je z kapitoly 4 a exact paired sign test z kapitoly 15, oba znovu použité beze změny. Velikosti čtěte jako vlastnost velmi malého modelu a metodu jako přenositelnou.

Pět skillů měřených zde jsou balíčky třetích stran, ne napsané pro tuto kapitolu: next-best-practices a next-cache-components z vercel-labs/next-skills a vercel-composition-patterns, vercel-react-best-practices a vercel-react-native-skills z vercel-labs/agent-skills. Jejich interní počty — 70 souborů pravidel, AGENTS.md s 26 362 tokeny, metadata.json datovaný lednem 2026 a tvrdící „40+ rules“ — byly přečteny ze souborů na disku 7. září 2026 a jsou vlastnostmi této publikované verze, ne kritikou jejích autorů: každý z nich je druh driftu, který se objeví v každém dokumentačním stromu, jenž se upravuje častěji, než se počítá.