Agent Skills en SKILL.md: Progressive Disclosure, gemeten

Hoofdstuk 14 stelde de regel voor de tweede helft van deze cursus — verbindingen, retries en annulering zijn TypeScript — en noemde vijf uitzonderingen. Dit is er één, en de reden is geen voorkeur.

Een skill is een Markdown-bestand. Geen bestand dat een programma configureert, geen bestand dat een programma compileert: een document dat het model leest, op dezelfde manier waarop het het bericht leest dat je typte. Dit hoofdstuk een programmeertaal geven zou betekenen dat je het format niet hebt begrepen, en dat misverstand is het allermeest voorkomende misverstand over skills. Alles hieronder is Markdown en YAML, plus één klein shellscript dat juist bestaat om te laten zien waar code wel en niet thuishoort binnen een skill.

Hier is een echte instructie: hoe één bedrijf zijn release notes schrijft. Het is een procedure, geen voorkeur — het heeft een geordende set stappen, een taxonomie, een stem, een template en een script dat het ruwe materiaal verzamelt.

Zet alles in de system prompt, zoals de meeste teams doen, en de rekenkunde van hoofdstuk 16 neemt het over. Een system prompt is een prefix, en voor een prefix betaal je bij elke call. Gemeten met o200k_base over de map die voor dit hoofdstuk is geschreven:

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

Vierentwintig keer goedkoper wanneer het wordt gebruikt, zevenendertig keer goedkoper wanneer het niet wordt gebruikt. De tarieven zijn die van hoofdstuk 16: $2,00 per miljoen input tokens.

Nu het eerlijke bezwaar, want een hoofdstuk dat dat oversloeg zou reclame zijn. Prompt caching dicht het geldgat grotendeels. Een system prompt is stabiel en staat vooraan, waardoor het de beste cachekandidaat is die er bestaat; bij $0,20 per miljoen voor cached input kosten dezelfde 68.640 tokens $0,0168 in plaats van $0,1373. Nog steeds drie keer de skill, maar niet langer een andere orde van grootte.

Geld was nooit het sterkste argument. Dit wel:

Caching maakt een permanente prefix goedkoper. Het maakt hem niet kleiner.

Bij turn 40 heeft de system-prompt-versie nog steeds 1.716 tokens aan release-notesbeleid in het window zitten tijdens een gesprek over iets totaal anders, concurrerend om wat hoofdstuk 24 het attention budget van het model noemde. De skillversie heeft er 46. Cache het verkeerde ding en je hebt korting gekocht op afleiding.

Als formule geschreven, met $n$ turns, $L_1$ de metadata, $L_2$ de body, $L_3$ de volledige bundel en $R$ de set gebundelde bestanden die daadwerkelijk worden gelezen:

Het hele hoofdstuk is het verschil tussen de tweede term vermenigvuldigen met $n$ en hem vermenigvuldigen met één of met nul.

Een skill is een directory. De specificatie is kort genoeg om volledig te citeren:

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 moet beginnen met YAML frontmatter, en precies twee velden zijn verplicht: name en description.¹ Vier andere zijn optioneel en er zijn geen andere gedefinieerd:

Hier is de release-notes-skill, volledig, met een body van minder dan dertig regels:

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

Lees wat die body is. Het is niet het beleid — het is een inhoudsopgave met een volgorde van bewerkingen. Het beleid staat in drie bestanden die het noemt en niet opneemt. En stap één geeft werk door aan een script, omdat de code van een script nooit het context window binnenkomt: alleen de output ervan.²

Het laadmodel heeft een naam en drie fasen. De specificatie beschrijft ze met een tokenbudget erbij:¹

1. Metadata, ongeveer 100 tokens: name en description, geladen bij startup voor elke geïnstalleerde skill.
2. Instructies, aanbevolen onder 5.000 tokens: de SKILL.md body, geladen wanneer de skill wordt geactiveerd.
3. Resources, naar behoefte: gebundelde bestanden, alleen geladen wanneer iets ze vereist.

De referentiedocumentatie zet een vierde kolom op dezelfde tabel — wanneer geladen, tokenkost, inhoud — en de rij die ertoe doet is de derde: geen tot benaderd.³ De zin die het hele hoofdstuk samenvat staat er ook:

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

De meettabel bovenaan dit hoofdstuk is die claim gecontroleerd op vijf skills die niemand voor dit artikel heeft geschreven. Twee rijen verdienen het naast elkaar gelezen te worden.

next-best-practices heeft een body van 966 tokens die linkt naar negentien bestanden met 19.374 tokens. Vraag hem een hydration error te fixen en de agent leest de body plus hydration-error.md: 1.409 tokens van 20.340, een factor veertien, en de andere achttien bestanden worden nooit geopend.

next-cache-components heeft een body van 2.334 tokens en helemaal geen gebundelde bestanden. Het is een geldige skill en een goed geschreven skill, en hij heeft geen level 3 om te onthullen. Dat is de eerlijke grens van de techniek: progressive disclosure levert alleen besparing op als er iets is om uit te stellen. Een skill waarvan de kennis niet uiteenvalt, betaalt bij activatie zijn hele body, en de enige hendel die overblijft is hem niet activeren.

Level 1 is een routingbeslissing op basis van één zin. Niets anders aan een skill beïnvloedt of hij ooit wordt geopend — niet de kwaliteit van de body, niet de voorbeelden, niet de scripts. De description is dus geen documentatie. Het is het query surface, en het kan fout zijn.

De specificatie zegt dat in de vorm van een goed voorbeeld en een slecht voorbeeld, en het slechte voorbeeld is vier woorden: description: Helps with PDFs.¹ Dat is de moeite waard om te meten in plaats van zomaar te accepteren.

Zes skills, elk met een plausibele description die zegt wat hij doet en wanneer je hem gebruikt. Vierentwintig requests, vier per skill, geformuleerd zoals een mens ze zou formuleren en zonder de skill ooit te noemen. Het model ziet de zes regels in zijn system prompt en moet antwoorden met één naam of met NONE. Greedy decoding, zodat het reproduceert. Daarna dezelfde vierentwintig requests met dezelfde zes skills, en de descriptions teruggesnoeid tot hun kale onderwerp.

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

Lees eerst de intervallen, zoals hoofdstuk 4 erop stond en hoofdstuk 29 opnieuw zal doen: ze overlappen, en vierentwintig gevallen kunnen twee systemen niet alleen op hun totalen rangschikken. De gepaarde vergelijking beslist het, en dat is het instrument van hoofdstuk 15: van de tien gevallen waarin de twee armen het oneens waren, gingen er negen naar de rijke descriptions en één naar de dunne. Dat staat vast op de gebruikelijke drempel.

Lees nu de laatste regel, de echte bevinding. Met dunne descriptions antwoordde het model NONE op negen van vierentwintig requests. Niet de verkeerde skill: geen skill. Hier zijn er vier, letterlijk:

"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

Er was een perfecte sql-review skill geïnstalleerd, met een body en voorbeelden en een checklist, en hij werd nooit geopend, drie keer op rij, op de drie vragen waarvoor hij was geschreven. Levels 2 en 3 zijn irrelevant voor een skill die level 1 nooit bereikt.

De kost om het te fixen: 214 tokens, het verschil tussen 295 en 81, verdeeld over zes skills. Dat is de bevinding van hoofdstuk 18 van de andere kant. Daar bracht alleen de description van een tool wijzigen datumformattering van 2 correct uit 24 naar 24 uit 24. Hier brengt alleen de description van een skill wijzigen activatie van 10 uit 24 naar 18. In beide gevallen is de goedkoopste fix in het systeem een zin, en in beide gevallen moet die zin de trigger noemen en niet alleen het onderwerp: niet wat het ding is, maar wat de gebruiker net gezegd zal hebben wanneer het van toepassing is.

Eén kanttekening die dit hoofdstuk aan zijn eigen standaarden verschuldigd is. Dit is een model met een half miljard parameters, en een frontier model route veel beter dan 75%. Lees het mechanisme, niet de grootte: het routing signal is één zin lang, welk model hem ook leest, en geen enkel model kan selecteren op informatie die je niet in die zin hebt gezet.

De tweede failure is het tegenovergestelde van de eerste. De skill wordt gevonden, de levels zijn correct gesplitst, en de agent leest toch alles.

vercel-react-best-practices is een werkelijk goed gebouwde skill. Zijn body van 1.670 tokens is een prioriteitentabel van acht categorieën en een quick reference die 70 regelbestanden noemt, elk op één regel. De regels staan ernaast op schijf: 70 bestanden, kleinste 132 tokens, mediaan 319, grootste 1.052. Stel één vraag over barrel imports en de eerlijke kost is de body plus één bestand — minder dan 2.400 tokens tegenover een bundel van 53.670.

Dan zegt de laatste regel van de body dit:

## Full Compiled Document

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

AGENTS.md is 26.362 tokens. Het zijn de 70 regelbestanden samengevoegd: hun som is 25.784, en het verschil zijn de koppen ertussen. Dus de skill biedt de agent een keuze tussen één mediane regel van 319 tokens lezen en dezelfde content, alles ervan, lezen tegen drieëntachtig keer de prijs — en hij biedt die keuze aan in een zin zonder kost erbij en zonder voorwaarde wanneer je hem moet nemen.

Dat is geen bug en het bestand is niet fout; een gecompileerd document is echt nuttig voor een mens, en voor een agent die is gevraagd een hele codebase te auditen. Het is een level-3-bestand met een level-2-uitnodiging, en de les generaliseert voorbij deze ene skill: elk pad uit een SKILL.md moet zeggen wat het kost en wanneer het de moeite waard is, omdat het model niet kan weten dat een bestandsnaam drieëntachtig keer duurder is dan de bestandsnaam erboven.

Dezelfde map bevat een kleinere les over veroudering. De body zegt ‘70 regels over 8 categorieën’ en somt er 70 op; de rules/ directory bevat 72 bestanden, waarvan twee scaffolding zijn (_template.md en _sections.md); en de sidecar metadata.json zegt ‘40+ regels’. Drie tellingen van dezelfde set in één map, één ervan correct, één ervan rekenkundig, en één ervan overgebleven uit een eerdere versie. Een skill is een document, en documenten rotten precies zoals een comment die ten opzichte van de code ernaast is verschoven — met het verschil dat deze wordt gelezen door een machine die geen wenkbrauw zal optrekken.

De open specificatie definieert zes frontmatter-velden. De referentie-implementatie, Claude Code, accepteert er twintig.² Vijf groepen zijn de moeite waard om bij naam te kennen, omdat daar het format ophoudt alleen een document te zijn:

Argumenten (arguments, argument-hint) laten een mens waarden meegeven die in de body worden gesubstitueerd, waardoor een skill bruikbaar wordt als slash command. Scoping (paths) beperkt activatie tot bestanden die matchen met een glob. En dynamic context injection is degene die het mentale model verandert: een regel in de vorm !`git diff HEAD` draait voordat de body wordt verzonden, en de output ervan wordt in de tekst gesubstitueerd. Het document is een template, en een deel ervan wordt berekend op leestijd.

Nu de valkuil, en die staat in dezelfde documentatie: buiten Claude Code — in het webproduct, via de Skills API, in packaging — zijn alleen de zes gespecificeerde velden toegestaan, en elk ander veld is een hard error bij upload.² Dus een skill die perfect werkt in één product faalt bij installatie in een ander product van dezelfde vendor, en hij faalt op de frontmatter in plaats van op iets dat je zou kunnen testen door de prose te lezen. Als je wilt dat een skill portable is, zijn de zes velden je hele budget. Als je dat niet wilt, zeg dat dan in compatibility, dat precies hiervoor bestaat.

Vier dingen worden voortdurend met elkaar verward, en die verwarring is geen woordenschatpedanterie: verkeerd kiezen kost geld bij elke turn, of kost je een garantie die je dacht te hebben.

De twee vetgedrukte rijen zijn het hele onderscheid. Een skill wordt gelezen; een tool wordt aangeroepen. Een skill is prose die in het context window arriveert en om attention concurreert met alles wat daar verder staat; het model kan hem volgen, verkeerd lezen of negeren, en niets in het systeem merkt het. Een tool is een call die de handen van het model volledig verlaat: jouw code ontvangt argumenten, valideert ze, controleert permissions en beslist. Hoofdstuk 18 formuleerde het als het model dat voorstelt en jouw code die beschikt, en die scheiding is precies wat een skill niet heeft.

Dus zes echte gevallen, opgelost:

De geschiedenis is kort, ongewoon goed gedateerd, en het is het deel dat bijna niemand vertelt.

Agent Skills werden gepubliceerd op 16 oktober 2025 als feature van één vendor, in die aankondiging gedefinieerd als ‘organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks’, met de drie levels beschreven via een analogie die het bewaren waard is: ‘like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix’.⁴

Op 18 december 2025 werd dezelfde pagina bijgewerkt om het format aan te kondigen als een open standaard, met een eigen specificatie op agentskills.io, governance open voor bijdragen, en een referentievalidator.³ Gelezen op 7 september 2026 vermeldt de client showcase van de standaard zesenveertig producten — editors, terminals, cloudplatforms en mobile runtimes, inclusief de first-party coding agents van Anthropic, OpenAI, Google en Mistral — elk met een link naar zijn eigen setupdocumentatie.¹

De convergentie met MCP gebeurt in het openbaar, met cijfers die je kunt controleren:

Het interessante is de sluiting, niet de voorstellen. SEP-2076 vroeg om een vierde primitive naast tools, resources en prompts. De working group die eruit ontstond besloot dat het antwoord nee was: skills rijden mee op de resources primitive die al bestaat, als opt-in extension.⁵ Hoofdstuk 26 mat hetzelfde instinct in de eigen changelog van het protocol, waar sampling, roots en logging werden deprecated in plaats van behouden. Een standards body die een voorstel verwijdert dat het zelf heeft geschreven gedraagt zich goed, en de reden om dit verhaal met de cijfers ervoor te vertellen is dat de samenvattingen die je elders leest skills nog steeds beschrijven als een MCP primitive.

Je kunt nu een SKILL.md schrijven, hem splitsen in drie levels die zichzelf terugbetalen, de frontmatter van de skill van iemand anders lezen en weten welke velden het uploaden naar ergens anders niet zullen overleven, en de vraag beantwoorden waaromheen het hele hoofdstuk is gebouwd — system prompt, skill, tool of server — met een reden in plaats van een gewoonte.

Wat je niet kunt, is zeggen of de jouwe werkt.

Elke claim in dit hoofdstuk die ertoe deed was een meting, en de belangrijkste was een accuracy: 18 uit 24 tegenover 10 uit 24, met een interval op elk en een paired test ertussen, omdat twee overlappende totalen niets beslissen. Dat instrument was geleend. De description van een skill is een routing key, zijn body is een procedure die het model wel of niet kan volgen, en beide eigenschappen kun je alleen achterhalen door het ding vaak te draaien en te scoren wat terugkwam — dat is een golden set, een grader die je vóór de run schreef, en de metric die vraagt of het elke keer werkte in plaats van minstens één keer.

Hoofdstuk 29 is dat, en het opent met het getal waarvan de methode van dit hoofdstuk afhangt: een agent die zeven van de tien keer slaagt ziet eruit als 70%, en zijn pass^10 — de kans dat hij op alle tien slaagt — is nul. Het meet ook drie graders op dezelfde tweehonderd transcripts en krijgt 0%, 13% en 26% zonder één token opnieuw te genereren. Voordat je de zin vertrouwt die je net in een description schreef, heb je het instrument nodig dat je kan vertellen dat hij slechter is dan degene die je verving.

Elke token telling in dit hoofdstuk is lokaal geproduceerd met tiktoken 0.14.0 en de o200k_base encoding, op 7 september 2026: over de vijf third-party skills die aan het begin van dit hoofdstuk zijn opgesomd, en over de release-notes skill die voor dit hoofdstuk is geschreven, waarvan de volledige tekst hierboven gedeeltelijk is gereproduceerd. Level 1 wordt gemeten als de enkele regel - name: description die een host in de system prompt rendert; level 2 is de SKILL.md body na de frontmatter; level 3 is elk ander bestand in de map. De kosten gebruiken de in hoofdstuk 16 gemeten tarieven voor gpt-5.6-terra, $2,00 per miljoen input tokens en $0,20 per miljoen cached input tokens, toegepast op die tellingen — het is rekenkunde op gemeten tokens, geen observatie van een live factuur. Er is geen betaalde API aangeroepen om dit hoofdstuk te schrijven.

Het activatie-experiment draaide Qwen/Qwen2.5-0.5B-Instruct in half precision op één consumer-GPU, greedy decoding, 24 requests over zes skills, twee keer — één keer met descriptions die aangeven wat de skill doet en wanneer hij van toepassing is, één keer met de descriptions teruggesnoeid tot een kaal onderwerp in de stijl van het eigen ‘poor example’ van de specificatie. Intervallen zijn Wilson op 95%; de gepaarde vergelijking is een two-sided exact sign test over de tien discordante gevallen; het Wilson-interval is dat van hoofdstuk 4 en de exact paired sign test die van hoofdstuk 15, beide ongewijzigd hergebruikt. Lees de groottes als eigenschap van een zeer klein model en de methode als overdraagbaar.

De vijf skills die hier zijn gemeten zijn third-party packages, niet geschreven voor dit hoofdstuk: next-best-practices en next-cache-components uit vercel-labs/next-skills, en vercel-composition-patterns, vercel-react-best-practices en vercel-react-native-skills uit vercel-labs/agent-skills. Hun interne tellingen — 70 regelbestanden, AGENTS.md op 26.362 tokens, metadata.json gedateerd januari 2026 en met de claim ‘40+ rules’ — zijn op 7 september 2026 gelezen uit de bestanden op schijf en zijn eigenschappen van die gepubliceerde versie, geen kritiek op de auteurs: elk ervan is het soort drift dat ontstaat in elke documentatieboom die vaker wordt bewerkt dan geteld.