Agent Skills og SKILL.md: gradvis disclosure, målt

Kapitel 14 satte reglen for anden halvdel af dette kursus — forbindelser, retries og cancellation er TypeScript — og erklærede fem undtagelser. Dette er en af dem, og grunden er ikke en præference.

En skill er en Markdown-fil. Ikke en fil, der konfigurerer et program, ikke en fil et program compiler: et dokument modellen læser, på samme måde som den læser den besked, du skrev. At give dette kapitel et programmeringssprog ville betyde, at man ikke havde forstået formatet, og den misforståelse er den mest almindelige om skills. Alt nedenfor er Markdown og YAML, plus ét lille shell-script, der findes præcis for at vise, hvor code hører og ikke hører hjemme inde i en skill.

Her er en reel instruktion: hvordan en virksomhed skriver sine release notes. Det er en procedure, ikke en præference — den har en ordnet række trin, en taksonomi, en stemme, en template og et script, der samler råmaterialet.

Læg det hele i system prompt, som de fleste teams gør, og Kapitel 16's aritmetik tager over. En system prompt er et prefix, og et prefix betales ved hvert kald. Målt med o200k_base over mappen skrevet til dette kapitel:

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

Fireogtyve gange billigere, når den bruges, syvogtredive gange billigere, når den ikke bruges. Satserne er Kapitel 16's: $2.00 per million input-tokens.

Nu den ærlige indvending, for et kapitel der sprang den over, ville være reklame. Prompt caching lukker det meste af pengespændet. En system prompt er stabil, og den ligger først, hvilket gør den til den bedste cache-kandidat der findes; til $0.20 per million for cached input koster de samme 68.640 tokens $0.0168 i stedet for $0.1373. Stadig tre gange så meget som skillen, men ikke længere en anden størrelsesorden.

Pengene var aldrig det stærkeste argument. Det er dette:

Caching gør et permanent prefix billigere. Det gør det ikke mindre.

Ved tur 40 har system-prompt-versionen stadig 1.716 tokens release-note-politik siddende i vinduet under en samtale om noget helt andet, hvor de konkurrerer om det Kapitel 24 kaldte modellens attention budget. Skill-versionen har 46. Cache den forkerte ting, og du har købt rabat på en distraktion.

Skrevet som en formel, med $n$ ture, $L_1$ metadata, $L_2$ body, $L_3$ hele bundtet og $R$ mængden af bundtede filer, der faktisk læses:

Hele dette kapitel er forskellen mellem at gange det andet led med $n$ og at gange det med én eller med nul.

En skill er en mappe. Specifikationen er kort nok til at gengive fuldstændigt:

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 skal begynde med YAML frontmatter, og præcis to felter er påkrævet: name og description.¹ Fire mere er valgfrie, og ingen andre er defineret:

Her er release-notes-skillen, komplet, med dens body på under tredive linjer:

---
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, hvad den body er. Den er ikke politikken — den er en indholdsfortegnelse med en rækkefølge af operationer. Politikken bor i tre filer, den navngiver og ikke inkluderer. Og trin ét sender arbejde videre til et script, fordi et scripts code aldrig kommer ind i context window overhovedet: kun dets output gør.²

Loading-modellen har et navn og tre trin. Specifikationen beskriver dem med et tilknyttet token-budget:¹

1. Metadata, cirka 100 tokens: name og description, loaded ved opstart for hver installeret skill.
2. Instruktioner, anbefalet under 5.000 tokens: SKILL.md body, loaded når skillen aktiveres.
3. Ressourcer, efter behov: bundtede filer, loaded kun når noget kræver dem.

Referencedokumentationen sætter en fjerde kolonne på samme tabel — hvornår loaded, token-omkostning, indhold — og rækken der betyder noget, er den tredje: ingen før adgang.³ Sætningen der opsummerer hele kapitlet, står der også:

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

Den målte tabel øverst i dette kapitel er den påstand tjekket mod fem skills, som ingen skrev til denne artikel. To rækker fortjener at blive læst op mod hinanden.

next-best-practices har en body på 966 tokens, der linker til nitten filer med 19.374 tokens. Bed den om at rette en hydration error, og agent læser body plus hydration-error.md: 1.409 tokens ud af 20.340, en faktor fjorten, og de andre atten filer bliver aldrig åbnet.

next-cache-components har en body på 2.334 tokens og slet ingen bundtede filer. Det er en gyldig skill og en velskrevet en, og den har intet niveau 3 at disclose. Det er teknikkens ærlige grænse: progressive disclosure er kun en besparelse, hvis der er noget at udskyde. En skill hvis viden ikke kan dekomponeres, betaler hele sin body ved aktivering, og den eneste løftestang der er tilbage, er ikke at aktivere den.

Niveau 1 er en routing-beslutning truffet ud fra én sætning. Intet andet ved en skill påvirker, om den nogensinde åbnes — ikke bodyens kvalitet, ikke eksemplerne, ikke scripts. Så beskrivelsen er ikke dokumentation. Den er query surface, og den kan være forkert.

Specifikationen siger det i form af et godt eksempel og et dårligt, og det dårlige er fire ord: description: Helps with PDFs.¹ Det er værd at måle i stedet for bare at acceptere.

Seks skills, hver med en plausibel beskrivelse, der siger hvad den gør, og hvornår den skal bruges. Fireogtyve requests, fire per skill, formuleret som et menneske ville formulere dem og uden nogensinde at nævne skillen. Modellen ser de seks linjer i sin system prompt og skal svare med ét navn eller med NONE. Greedy decoding, så den reproducerer. Derefter de samme fireogtyve requests med de samme seks skills, og beskrivelserne skåret ned til deres blotte emne.

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 intervallerne først, som Kapitel 4 insisterede på, og Kapitel 29 vil insistere på igen: de overlapper, og fireogtyve cases kan ikke rangordne to systemer alene på deres aggregater. Den parrede sammenligning er det, der afgør det, og den er Kapitel 15's instrument: Af de ti cases hvor de to arme var uenige, gik ni til de rige beskrivelser og én til de tynde. Det er etableret ved den sædvanlige tærskel.

Læs nu den sidste linje, som er det faktiske fund. Med tynde beskrivelser svarede modellen NONE på ni af fireogtyve requests. Ikke den forkerte skill: ingen skill. Her er fire af dem, ordret:

"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 installeret, med en body og eksempler og en checklist, og den blev aldrig åbnet, tre gange i træk, på de tre spørgsmål den var skrevet til. Niveau 2 og 3 er irrelevante for en skill, som niveau 1 aldrig når.

Prisen for at rette det: 214 tokens, forskellen mellem 295 og 81, fordelt over seks skills. Det er Kapitel 18's fund, der ankommer fra den anden side. Der tog ændring af kun et værktøjs beskrivelse date formatting fra 2 korrekte ud af 24 til 24 ud af 24. Her tager ændring af kun en skills beskrivelse aktivering fra 10 ud af 24 til 18. I begge tilfælde er den billigste rettelse i systemet en sætning, og i begge tilfælde skal sætningen navngive triggeren og ikke kun emnet: ikke hvad tingen er, men hvad brugeren netop vil have sagt, når den gælder.

Ét forbehold skylder dette kapitel sine egne standarder. Dette er en model med en halv milliard parametre, og en frontier model router langt bedre end 75 %. Læs mekanismen, ikke størrelsen: routing-signalet er én sætning langt, uanset hvilken model der læser det, og ingen model kan vælge på information, du ikke lagde i den sætning.

Den anden fejl er det modsatte af den første. Skillen findes, niveauerne er korrekt delt op, og agent læser alligevel det hele.

vercel-react-best-practices er en reelt velbygget skill. Dens body på 1.670 tokens er en prioritetstabel med otte kategorier og en hurtig reference, der navngiver 70 regelfiler, én linje hver. Reglerne ligger på disk ved siden af den: 70 filer, den mindste 132 tokens, median 319, den største 1.052. Stil den ét spørgsmål om barrel imports, og den ærlige pris er body plus én fil — under 2.400 tokens mod et bundle på 53.670.

Så siger den sidste linje i bodyen dette:

## Full Compiled Document

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

AGENTS.md er 26.362 tokens. Det er de 70 regelfiler sat sammen: deres sum er 25.784, og forskellen er overskrifterne mellem dem. Så skillen tilbyder agent et valg mellem at læse én medianregel på 319 tokens og at læse det samme indhold, det hele, til treogfirs gange prisen — og den tilbyder det valg i en sætning uden tilknyttet pris og uden betingelse for, hvornår det er værd at gøre.

Det er ikke en bug, og filen er ikke forkert; et compiled dokument er reelt nyttigt for et menneske og for en agent, der er blevet bedt om at auditere en hel codebase. Det er en niveau-3-fil med en niveau-2-invitation, og læren generaliserer ud over denne ene skill: hver sti ud af en SKILL.md bør sige, hvad den koster, og hvornår den er det værd, fordi modellen ikke har nogen måde at vide, at et filnavn er treogfirs gange dyrere end filnavnet ovenover.

Den samme mappe rummer en mindre lære om staleness. Bodyen siger "70 rules across 8 categories" og oplister 70; rules/-mappen rummer 72 filer, hvoraf to er scaffolding (_template.md og _sections.md); og sidecar-filen metadata.json siger "40+ rules". Tre optællinger af den samme mængde i én mappe, én af dem rigtig, én af dem aritmetisk, og én efterladt fra en tidligere version. En skill er et dokument, og dokumenter rådner præcis som en kodekommentar, der er driftet væk fra koden ved siden af den — med den forskel at denne her læses af en maskine, som ikke løfter et øjenbryn.

Den åbne specifikation definerer seks frontmatter-felter. Referenceimplementeringen, Claude Code, accepterer tyve.² Fem grupper er værd at kende ved navn, fordi det er dér formatet holder op med kun at være et dokument:

Argumenter (arguments, argument-hint) lader et menneske sende værdier, der substitueres ind i bodyen, hvilket er det, der gør en skill brugbar som en slash command. Scoping (paths) begrænser aktivering til filer, der matcher et glob. Og dynamic context injection er den, der ændrer den mentale model: en linje på formen !`git diff HEAD` kører før bodyen sendes, og dens output substitueres ind i teksten. Dokumentet er en template, og en del af det beregnes ved læsetid.

Nu fælden, og den står i den samme dokumentation: uden for Claude Code — i webproduktet, gennem Skills API, i packaging — er kun de seks specificerede felter tilladt, og ethvert andet felt er en hård fejl ved upload.² Så en skill, der virker perfekt i ét produkt, fejler ved installation i et andet fra samme leverandør, og den fejler i frontmatter i stedet for i noget, du kunne teste ved at læse prosaen. Hvis du vil have en skill til at være portabel, er de seks felter hele budgettet. Hvis du ikke vil, så sig det i compatibility, som findes præcis til det.

Fire ting forveksles konstant med hinanden, og forvirringen er ikke ordkløveri: vælger du forkert, koster det penge ved hver tur, eller det koster dig en garanti, du troede du havde.

De to rækker med fed er hele skellet. En skill læses; et værktøj invoked. En skill er prosa, der ankommer i context window og konkurrerer om attention med alt andet derinde; modellen kan følge den, mislæse den eller ignorere den, og intet i systemet opdager det. Et værktøj er et kald, der helt forlader modellens hænder: din code modtager argumenter, validerer dem, tjekker tilladelser og beslutter. Kapitel 18 formulerede det som at modellen foreslår, og din code afgør, og den opdeling er præcis det en skill ikke har.

Så seks reelle cases, afgjort:

Historien er kort, usædvanligt vel dateret, og det er den del næsten ingen fortæller.

Agent Skills blev offentliggjort den 16. oktober 2025 som én leverandørs feature, defineret i den announcement som "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks", med de tre niveauer beskrevet gennem en analogi, der er værd at beholde: "like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix".⁴

Den 18. december 2025 blev den samme side opdateret for at annoncere formatet som en åben standard, med sin egen specifikation på agentskills.io, governance åben for bidrag og en reference-validator.³ Læst den 7. september 2026 oplister standardens client showcase seksogfyrre produkter — editors, terminals, cloud-platforme og mobile runtimes, inklusive first-party coding agents fra Anthropic, OpenAI, Google og Mistral — hver med link til sin egen setup-dokumentation.¹

Konvergensen med MCP bliver lavet åbent, med tal du kan tjekke:

Det interessante er lukningen, ikke forslagene. SEP-2076 bad om en fjerde primitive ved siden af tools, resources og prompts. Working group, der opstod ud af det, besluttede at svaret var nej: skills rider på den resources primitive, der allerede findes, som en opt-in extension.⁵ Kapitel 26 målte den samme instinkt i protocolens egen changelog, hvor sampling, roots og logging blev deprecated i stedet for bevaret. Et standardiseringsorgan, der fjerner et forslag, det selv har forfattet, opfører sig godt, og grunden til at fortælle historien med tallene foran er, at de resuméer du læser andre steder, stadig beskriver skills som en MCP primitive.

Du kan nu skrive en SKILL.md, dele den op i tre niveauer, der betaler sig selv, læse frontmatter i en andens skill og vide, hvilke felter der ikke overlever upload et andet sted, og besvare spørgsmålet hele kapitlet blev bygget omkring — system prompt, skill, værktøj eller server — med en begrundelse i stedet for en vane.

Det du ikke kan, er at sige, om din virker.

Hver påstand i dette kapitel, der betød noget, var en måling, og den der betød mest, var en accuracy: 18 ud af 24 mod 10 ud af 24, med et interval på hver og en parret test mellem dem, fordi to aggregater der overlapper, intet afgør. Det instrument var lånt. En skills beskrivelse er en routing-nøgle, dens body er en procedure, modellen måske eller måske ikke følger, og begge egenskaber kan du kun finde ud af ved at køre tingen mange gange og score, hvad der kom tilbage — hvilket er et golden set, en grader du skrev før kørslen, og den metric der spørger, om det virkede hver gang snarere end mindst én gang.

Kapitel 29 er det, og det åbner med det tal, dette kapitels metode afhænger af: en agent der lykkes syv ud af ti gange, ligner 70 %, og dens pass^10 — chancen for at den lykkes på alle ti — er nul. Det måler også tre graders på de samme to hundrede transcripts og får 0 %, 13 % og 26 % uden at regenerere en eneste token. Før du stoler på sætningen, du lige skrev ind i en description, har du brug for instrumentet, der kan fortælle dig, at den er dårligere end den, du erstattede.

Hver token-optælling i dette kapitel blev produceret lokalt med tiktoken 0.14.0 og o200k_base encoding, den 7. september 2026: over de fem tredjeparts-skills, der er oplistet øverst i dette kapitel, og over release-notes-skillen skrevet til dette kapitel, hvis komplette tekst er gengivet delvist ovenfor. Niveau 1 måles som den enkelte linje - name: description, som en host renderer ind i system prompt; niveau 2 er SKILL.md body efter frontmatter; niveau 3 er hver anden fil i mappen. Omkostningerne bruger Kapitel 16's målte satser for gpt-5.6-terra, $2.00 per million input-tokens og $0.20 per million cached input-tokens, anvendt på de optællinger — de er aritmetik på målte tokens, ikke observationer af en live-regning. Ingen betalt API blev kaldt for at skrive dette kapitel.

Aktiveringseksperimentet kørte Qwen/Qwen2.5-0.5B-Instruct i half precision på én consumer-GPU, greedy decoding, 24 requests over seks skills, to gange — én gang med beskrivelser der siger, hvad skillen gør, og hvornår den gælder, én gang med beskrivelserne skåret ned til et blottet emne i stil med specifikationens egen "poor example". Intervaller er Wilson ved 95 %; den parrede sammenligning er en tosidet exact sign test over de ti discordant cases; Wilson-intervallet er Kapitel 4's og den præcise parrede sign test er Kapitel 15's, begge genbrugt uændret. Læs størrelserne som en egenskab ved en meget lille model og metoden som overførbar.

De fem skills målt her er tredjepartspakker, ikke skrevet til dette kapitel: next-best-practices og next-cache-components fra vercel-labs/next-skills, og vercel-composition-patterns, vercel-react-best-practices og vercel-react-native-skills fra vercel-labs/agent-skills. Deres interne optællinger — 70 regelfiler, AGENTS.md på 26.362 tokens, metadata.json dateret januar 2026 og med påstanden "40+ rules" — blev læst fra filerne på disk den 7. september 2026 og er egenskaber ved den publicerede version, ikke kritik af dens forfattere: hver eneste af dem er den slags drift, der opstår i ethvert dokumentationstræ, som redigeres oftere, end det tælles.