Agent Skills och SKILL.md: stegvis exponering, mätt

Kapitel 14 satte regeln för kursens andra halva — anslutningar, återförsök och avbrytning är TypeScript — och deklarerade fem undantag. Det här är ett av dem, och skälet är inte en preferens.

En skill är en Markdown-fil. Inte en fil som konfigurerar ett program, inte en fil som ett program kompilerar: ett dokument som modellen läser, på samma sätt som den läser meddelandet du skrev. Att ge det här kapitlet ett programmeringsspråk skulle betyda att man inte har förstått formatet, och det missförståndet är det enskilt vanligaste om skills. Allt nedan är Markdown och YAML, plus ett litet shell script som finns just för att visa var kod hör hemma och inte hör hemma inuti en skill.

Här är en verklig instruktion: hur ett företag skriver sina release notes. Det är en procedur, inte en preferens — den har en ordnad uppsättning steg, en taxonomi, en röst, en mall och ett script som samlar in råmaterialet.

Lägg allt i system prompt, som de flesta team gör, och kapitel 16:s aritmetik tar över. En system prompt är ett prefix, och ett prefix betalas vid varje call. Mätt med o200k_base över mappen som skrevs för det här kapitlet:

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

Tjugofyra gånger billigare när den används, trettiosju gånger billigare när den inte används. Priserna är kapitel 16:s: $2.00 per miljon input tokens.

Nu den ärliga invändningen, eftersom ett kapitel som hoppade över den vore reklam. Prompt caching stänger i stort sett pengagapet. En system prompt är stabil och ligger först, vilket gör den till den bästa cache-kandidaten som finns; vid $0.20 per miljon för cached input kostar samma 68 640 tokens $0.0168 i stället för $0.1373. Fortfarande tre gånger så mycket som skillen, men inte längre en annan storleksordning.

Pengarna var aldrig det starkaste argumentet. Det här är det:

Caching gör ett permanent prefix billigare. Det gör det inte mindre.

Vid tur 40 har system-prompt-versionen fortfarande 1 716 tokens release-note-policy liggande i fönstret under en konversation om något helt annat, där den konkurrerar om det kapitel 24 kallade modellens attention-budget. Skill-versionen har 46. Cachea fel sak och du har köpt rabatt på en distraktion.

Skrivet som en formel, med $n$ turer, $L_1$ metadata, $L_2$ body, $L_3$ hela paketet och $R$ mängden buntade filer som faktiskt läses:

Hela det här kapitlet är skillnaden mellan att multiplicera den andra termen med $n$ och att multiplicera den med ett eller med noll.

En skill är en katalog. Specifikationen är kort nog för att återges i sin helhet:

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 måste börja med YAML-frontmatter, och exakt två fält krävs: name och description.¹ Fyra till är valfria och inga andra definieras:

Här är release-notes-skillen, komplett, med sin body under trettio rader:

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

Läs vad den bodyn är. Den är inte policyn — den är en innehållsförteckning med en operationsordning. Policyn bor i tre filer som den namnger och inte inkluderar. Och steg ett lämnar arbete till ett script, eftersom ett scripts kod aldrig hamnar i context window alls: bara dess output gör det.²

Laddningsmodellen har ett namn och tre steg. Specifikationen anger dem med en token-budget kopplad till varje steg:¹

1. Metadata, ungefär 100 tokens: name och description, laddas vid start för varje installerad skill.
2. Instruktioner, rekommenderat under 5 000 tokens: SKILL.md-bodyn, laddas när skillen aktiveras.
3. Resurser, efter behov: buntade filer, laddas bara när något kräver dem.

Referensdokumentationen sätter en fjärde kolumn på samma tabell — när laddad, token-kostnad, innehåll — och raden som spelar roll är den tredje: ingen förrän den nås.³ Meningen som sammanfattar hela kapitlet finns där också:

Filer konsumerar inte context förrän de nås, så Skills kan innehålla omfattande API-dokumentation, stora dataset eller utförliga exempel. Det finns ingen context-straffavgift för buntat innehåll som inte används.³

Den uppmätta tabellen i början av det här kapitlet är det påståendet kontrollerat mot fem skills som ingen skrev för den här artikeln. Två rader förtjänar att läsas mot varandra.

next-best-practices har en body på 966 tokens som länkar till nitton filer med 19 374 tokens. Be den fixa ett hydration-fel och agent läser bodyn plus hydration-error.md: 1 409 tokens av 20 340, en faktor fjorton, och de andra arton filerna öppnas aldrig.

next-cache-components har en body på 2 334 tokens och inga buntade filer alls. Den är en giltig skill och en välskriven sådan, och den har ingen nivå 3 att exponera. Det är teknikens ärliga gräns: stegvis exponering är bara en besparing om det finns något att skjuta upp. En skill vars kunskap inte går att bryta ned betalar hela sin body vid aktivering, och den enda hävstången som återstår är att inte aktivera den.

Nivå 1 är ett routing-beslut gjort utifrån en mening. Inget annat med en skill påverkar om den någonsin öppnas — inte kvaliteten på bodyn, inte exemplen, inte scripten. Så beskrivningen är inte dokumentation. Den är query-ytan, och den kan vara fel.

Specifikationen säger det i form av ett bra exempel och ett dåligt, och det dåliga är fyra ord: description: Helps with PDFs.¹ Det är värt att mäta i stället för att bara acceptera.

Sex skills, var och en med en rimlig beskrivning som säger vad den gör och när den ska användas. Tjugofyra requests, fyra per skill, formulerade som en person skulle formulera dem och utan att någonsin namnge skillen. Modellen ser de sex raderna i sin system prompt och måste svara med ett namn eller med NONE. Greedy decoding, så den reproducerar. Sedan samma tjugofyra requests med samma sex skills, och beskrivningarna nedskurna till sitt nakna ämne.

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

Läs intervallen först, som kapitel 4 insisterade på och kapitel 29 kommer att insistera på igen: de överlappar, och tjugofyra fall kan inte rangordna två system enbart på deras aggregat. Den parade jämförelsen är det som avgör, och det är kapitel 15:s instrument: av de tio fall där de två armarna var oense gick nio till de rika beskrivningarna och ett till de tunna. Det är fastställt vid den vanliga tröskeln.

Läs nu den sista raden, som är det faktiska fyndet. Med tunna beskrivningar svarade modellen NONE på nio av tjugofyra requests. Inte fel skill: ingen skill. Här är fyra av dem, ordagrant:

"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

En perfekt sql-review-skill var installerad, med body och exempel och en checklista, och den öppnades aldrig, tre gånger i rad, på de tre frågor den var skriven för. Nivå 2 och 3 är irrelevanta för en skill som nivå 1 aldrig når.

Kostnaden för att fixa det: 214 tokens, skillnaden mellan 295 och 81, utspridd över sex skills. Det är kapitel 18:s fynd som kommer från andra hållet. Där tog en ändring av enbart ett tools beskrivning datumformatering från 2 korrekta av 24 till 24 av 24. Här tar en ändring av enbart en skills beskrivning aktivering från 10 av 24 till 18. I båda fallen är den billigaste fixen i systemet en mening, och i båda fallen måste meningen namnge triggern och inte bara ämnet: inte vad saken är, utan vad användaren precis kommer att ha sagt när den gäller.

En brasklapp som det här kapitlet är skyldigt sina egna standarder. Det här är en modell med en halv miljard parametrar, och en frontier-modell routar mycket bättre än 75 %. Läs mekanismen, inte storleken: routing-signalen är en mening lång oavsett vilken modell som läser den, och ingen modell kan välja baserat på information du inte lade in i den meningen.

Det andra felet är motsatsen till det första. Skillen hittas, nivåerna är korrekt uppdelade, och agent läser ändå alltihop.

vercel-react-best-practices är en genuint välbyggd skill. Dess body på 1 670 tokens är en prioritetstabell med åtta kategorier och en snabbreferens som namnger 70 regelfiler, en rad per fil. Reglerna ligger på disk bredvid den: 70 filer, minsta 132 tokens, median 319, största 1 052. Ställ en fråga om barrel imports och den ärliga kostnaden är bodyn plus en fil — under 2 400 tokens mot ett paket på 53 670.

Sedan säger sista raden i bodyn detta:

## Full Compiled Document

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

AGENTS.md är 26 362 tokens. Det är de 70 regelfilerna sammanfogade: deras summa är 25 784, och skillnaden är rubrikerna mellan dem. Så skillen erbjuder agent ett val mellan att läsa en medianregel på 319 tokens och att läsa samma innehåll, alltihop, till åttiotre gånger priset — och den erbjuder det valet i en mening utan kostnad angiven och utan villkor för när den ska tas.

Det är inte en bug och filen är inte fel; ett kompilerat dokument är genuint användbart för en människa, och för en agent som har blivit ombedd att granska en hel codebase. Det är en nivå 3-fil med en nivå 2-inbjudan, och lärdomen generaliserar bortom just den här skillen: varje väg ut ur en SKILL.md bör säga vad den kostar och när den är värd det, eftersom modellen inte har något sätt att veta att ett filnamn är åttiotre gånger dyrare än filnamnet ovanför.

Samma mapp bär på en mindre läxa om staleness. Bodyn säger "70 rules across 8 categories" och listar 70; katalogen rules/ innehåller 72 filer, varav två är scaffolding (_template.md och _sections.md); och sidecar-filen metadata.json säger "40+ rules". Tre räkningar av samma mängd i en mapp, en av dem rätt, en av dem aritmetisk, och en av dem kvar från en tidigare version. En skill är ett dokument, och dokument ruttnar precis som en kodkommentar som har driftat bort från koden bredvid den — med skillnaden att den här läses av en maskin som inte kommer att höja på ögonbrynen.

Den öppna specifikationen definierar sex frontmatter-fält. Referensimplementationen, Claude Code, accepterar tjugo.² Fem grupper är värda att kunna vid namn, eftersom det är där formatet slutar vara bara ett dokument:

Argument (arguments, argument-hint) låter en person skicka värden som substitueras in i bodyn, vilket är vad som gör en skill användbar som slash command. Scoping (paths) begränsar aktivering till filer som matchar en glob. Och dynamic context injection är den som ändrar den mentala modellen: en rad på formen !`git diff HEAD` körs innan bodyn skickas, och dess output substitueras in i texten. Dokumentet är en template, och en del av det beräknas vid lästid.

Nu fällan, och den anges i samma dokumentation: utanför Claude Code — i webbprodukten, genom Skills API, i paketering — är endast de sex specificerade fälten tillåtna, och alla andra fält är ett hårt fel vid upload.² Så en skill som fungerar perfekt i en produkt misslyckas med att installeras i en annan från samma vendor, och den misslyckas i frontmatter snarare än i något du skulle kunna testa genom att läsa prosan. Om du vill att en skill ska vara portabel är de sex fälten hela budgeten. Om du inte vill det, säg det i compatibility, som finns just för detta.

Fyra saker förväxlas ständigt med varandra, och förvirringen är inte vokabulärpedanteri: väljer du fel kostar det pengar vid varje tur, eller kostar dig en garanti du trodde att du hade.

De två raderna i fetstil är hela distinktionen. En skill läses; ett tool anropas. En skill är prosa som hamnar i context window och konkurrerar om attention med allt annat där; modellen kan följa den, läsa fel eller ignorera den, och inget i systemet märker det. Ett tool är ett call som lämnar modellens händer helt: din kod tar emot argument, validerar dem, kontrollerar behörigheter och beslutar. Kapitel 18 uttryckte det som att modellen föreslår och din kod avgör, och den uppdelningen är exakt vad en skill inte har.

Så sex verkliga fall, avgjorda:

Historien är kort, ovanligt väldaterad, och det är den del nästan ingen berättar.

Agent Skills publicerades den 16 oktober 2025 som en vendors funktion, definierad i det tillkännagivandet som "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks", med de tre nivåerna beskrivna genom en analogi som är värd att behålla: "like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix".⁴

Den 18 december 2025 uppdaterades samma sida för att annonsera formatet som en öppen standard, med en egen specifikation på agentskills.io, governance öppen för bidrag och en referensvalidator.³ Läst den 7 september 2026 listar standardens client showcase fyrtiosex produkter — editors, terminals, cloud platforms och mobile runtimes, inklusive Anthropic, OpenAI, Google och Mistrals first-party coding agents — var och en med länk till sin egen setup-dokumentation.¹

Konvergensen med MCP görs öppet, med siffror du kan kontrollera:

Det intressanta är stängningen, inte förslagen. SEP-2076 bad om en fjärde primitive bredvid tools, resources och prompts. Working group som bildades ur det beslutade att svaret var nej: skills åker på den resources-primitive som redan finns, som en opt-in extension.⁵ Kapitel 26 mätte samma instinkt i protokollets egen changelog, där sampling, roots och logging deprecierades i stället för att behållas. Ett standards body som tar bort ett förslag det själv författat beter sig väl, och skälet att berätta den här historien med siffrorna framme är att sammanfattningarna du kommer att läsa på andra håll fortfarande beskriver skills som en MCP primitive.

Du kan nu skriva en SKILL.md, dela upp den i tre nivåer som betalar för sig, läsa frontmatter i någon annans skill och veta vilka fält som inte överlever en upload någon annanstans, och besvara frågan som hela kapitlet byggdes kring — system prompt, skill, tool eller server — med ett skäl snarare än en vana.

Vad du inte kan göra är att säga om din fungerar.

Varje påstående i det här kapitlet som spelade roll var en mätning, och det som spelade störst roll var en accuracy: 18 av 24 mot 10 av 24, med ett intervall på vardera och ett parat test mellan dem, eftersom två överlappande aggregat inte avgör något. Det instrumentet var lånat. En skills beskrivning är en routing key, dess body är en procedur som modellen kanske eller kanske inte följer, och båda är egenskaper du bara kan ta reda på genom att köra saken många gånger och poängsätta vad som kom tillbaka — vilket är ett golden set, en grader du skrev före körningen, och metriken som frågar om det fungerade varje gång snarare än minst en gång.

Kapitel 29 är det, och det öppnar med siffran som det här kapitlets metod beror på: en agent som lyckas sju gånger av tio ser ut som 70 %, och dess pass^10 — chansen att den lyckas med alla tio — är noll. Det mäter också tre graders på samma tvåhundra transcripts och får 0 %, 13 % och 26 % utan att regenerera en enda token. Innan du litar på meningen du just skrev in i en description behöver du instrumentet som kan säga att den är sämre än den du ersatte.

Varje token-räkning i det här kapitlet producerades lokalt med tiktoken 0.14.0 och o200k_base-encoding, den 7 september 2026: över de fem tredjeparts-skills som listas i början av det här kapitlet, och över release-notes-skillen som skrevs för det här kapitlet, vars fullständiga text delvis återges ovan. Nivå 1 mäts som den enda raden - name: description som en host renderar in i system prompt; nivå 2 är SKILL.md-bodyn efter frontmatter; nivå 3 är alla andra filer i mappen. Kostnaderna använder kapitel 16:s uppmätta priser för gpt-5.6-terra, $2.00 per miljon input tokens och $0.20 per miljon cached input tokens, applicerade på dessa räkningar — de är aritmetik på uppmätta tokens, inte observationer av en livefaktura. Inget betalt API anropades för att skriva det här kapitlet.

Aktiveringsexperimentet körde Qwen/Qwen2.5-0.5B-Instruct i half precision på en konsument-GPU, greedy decoding, 24 requests över sex skills, två gånger — en gång med beskrivningar som anger vad skillen gör och när den gäller, en gång med beskrivningarna nedskurna till ett naket ämne i stil med specifikationens eget "poor example". Intervallen är Wilson på 95 %; den parade jämförelsen är ett tvåsidigt exakt sign test över de tio discordant cases; Wilson-intervallet är kapitel 4:s och det exakta parade sign test är kapitel 15:s, båda återanvända oförändrade. Läs magnituderna som en egenskap hos en mycket liten modell och metoden som överförbar.

De fem skills som mäts här är tredjepartspaket, inte skrivna för det här kapitlet: next-best-practices och next-cache-components från vercel-labs/next-skills, och vercel-composition-patterns, vercel-react-best-practices och vercel-react-native-skills från vercel-labs/agent-skills. Deras interna räkningar — 70 regelfiler, AGENTS.md på 26 362 tokens, metadata.json daterad januari 2026 och med påståendet "40+ rules" — lästes från filerna på disk den 7 september 2026 och är egenskaper hos den publicerade versionen, inte kritik av dess författare: varenda en är den sorts drift som uppstår i vilket dokumentationsträd som helst som redigeras oftare än det räknas.