Agent Skills und SKILL.md: Progressive Disclosure, gemessen

Kapitel 14 hat die Regel für die zweite Hälfte dieses Kurses festgelegt — Verbindungen, Retries und Abbruch sind TypeScript — und fünf Ausnahmen benannt. Dies ist eine davon, und der Grund ist keine Vorliebe.

Ein skill ist eine Markdown-Datei. Keine Datei, die ein Programm konfiguriert, keine Datei, die ein Programm kompiliert: ein Dokument, das das Modell liest, so wie es die Nachricht liest, die du getippt hast. Diesem Kapitel eine Programmiersprache zu geben, hieße, das Format nicht verstanden zu haben, und genau dieses Missverständnis ist das mit Abstand häufigste über Skills. Alles unten ist Markdown und YAML, plus ein kleines Shell-Skript, das gerade dazu dient zu zeigen, wo Code in einen skill gehört und wo nicht.

Hier ist eine echte Anweisung: wie ein Unternehmen seine Release Notes schreibt. Es ist ein Verfahren, keine Vorliebe — es hat eine geordnete Schrittfolge, eine Taxonomie, eine Stimme, ein Template und ein Skript, das das Rohmaterial sammelt.

Pack alles davon in den system prompt, wie es die meisten Teams tun, und die Arithmetik aus Kapitel 16 übernimmt. Ein system prompt ist ein Präfix, und ein Präfix wird bei jedem Aufruf bezahlt. Gemessen mit o200k_base über den für dieses Kapitel geschriebenen Ordner:

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

Vierundzwanzigmal günstiger, wenn es verwendet wird, siebenunddreißigmal günstiger, wenn nicht. Die Preise sind die aus Kapitel 16: $2,00 pro Million input token.

Nun der ehrliche Einwand, denn ein Kapitel, das ihn überspringt, wäre Werbung. prompt caching schließt die Kostenschere weitgehend. Ein system prompt ist stabil und steht am Anfang, was ihn zum besten Cache-Kandidaten überhaupt macht; bei $0,20 pro Million für cached input kosten dieselben 68.640 token $0,0168 statt $0,1373. Immer noch dreimal so viel wie der skill, aber keine andere Größenordnung mehr.

Das Geld war nie das stärkste Argument. Dieses hier ist es:

Caching macht ein dauerhaftes Präfix günstiger. Es macht es nicht kleiner.

Bei Turn 40 hat die system-prompt-Version immer noch 1.716 token Release-Note-Policy im Fenster sitzen, während es in der Unterhaltung um etwas völlig anderes geht, und konkurriert um das, was Kapitel 24 das attention budget des Modells nannte. Die skill-Version hat 46. Cache das Falsche, und du hast einen Rabatt auf eine Ablenkung gekauft.

Als Formel geschrieben, mit $n$ Turns, $L_1$ den Metadaten, $L_2$ dem Body, $L_3$ dem ganzen Bundle und $R$ der Menge der gebündelten Dateien, die tatsächlich gelesen werden:

Das ganze Kapitel ist der Unterschied zwischen dem Multiplizieren des zweiten Terms mit $n$ und dem Multiplizieren mit eins oder mit null.

Ein skill ist ein Verzeichnis. Die Spezifikation ist kurz genug, um sie vollständig wiederzugeben:

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 muss mit YAML-Frontmatter beginnen, und genau zwei Felder sind erforderlich: name und description.¹ Vier weitere sind optional, und keine anderen sind definiert:

Hier ist der Release-Notes-skill, vollständig, mit einem Body unter dreißig Zeilen:

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

Lies, was dieser Body ist. Er ist nicht die Policy — er ist ein Inhaltsverzeichnis mit einer Reihenfolge der Arbeitsschritte. Die Policy liegt in drei Dateien, die er benennt und nicht einbindet. Und Schritt eins übergibt Arbeit an ein Skript, weil der Code eines Skripts nie in die context window gelangt: nur seine Ausgabe.²

Das Lademodell hat einen Namen und drei Stufen. Die Spezifikation nennt sie mit einem angehängten token-Budget:¹

1. Metadaten, etwa 100 token: name und description, beim Start für jeden installierten skill geladen.
2. Anweisungen, empfohlen unter 5.000 token: der SKILL.md-Body, geladen, wenn der skill aktiviert wird.
3. Ressourcen, nach Bedarf: gebündelte Dateien, nur geladen, wenn etwas sie erfordert.

Die Referenzdokumentation setzt eine vierte Spalte auf dieselbe Tabelle — when loaded, token cost, content — und die entscheidende Zeile ist die dritte: none until accessed.³ Der Satz, der das ganze Kapitel zusammenfasst, steht dort ebenfalls:

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

Die gemessene Tabelle am Anfang dieses Kapitels ist diese Behauptung, geprüft an fünf Skills, die niemand für diesen Artikel geschrieben hat. Zwei Zeilen verdienen es, gegeneinander gelesen zu werden.

next-best-practices hat einen Body mit 966 token, der auf neunzehn Dateien mit 19.374 token verweist. Bitte ihn, einen Hydration-Fehler zu beheben, und der agent liest den Body plus hydration-error.md: 1.409 token von 20.340, ein Faktor von vierzehn, und die anderen achtzehn Dateien werden nie geöffnet.

next-cache-components hat einen Body mit 2.334 token und überhaupt keine gebündelten Dateien. Er ist ein gültiger skill und ein gut geschriebener, und er hat kein Level 3, das offengelegt werden könnte. Das ist die ehrliche Grenze der Technik: Progressive Disclosure spart nur, wenn es etwas gibt, das sich aufschieben lässt. Ein skill, dessen Wissen sich nicht zerlegen lässt, bezahlt bei Aktivierung seinen ganzen Body, und der einzige verbleibende Hebel ist, ihn nicht zu aktivieren.

Level 1 ist eine Routing-Entscheidung, die aus einem Satz getroffen wird. Nichts anderes an einem skill beeinflusst, ob er je geöffnet wird — nicht die Qualität des Bodys, nicht die Beispiele, nicht die Skripte. Die Beschreibung ist also keine Dokumentation. Sie ist die Query-Oberfläche, und sie kann falsch sein.

Die Spezifikation sagt das in Form eines guten und eines schlechten Beispiels, und das schlechte Beispiel besteht aus vier Wörtern: description: Helps with PDFs.¹ Das lohnt sich zu messen, statt es einfach hinzunehmen.

Sechs Skills, jeder mit einer plausiblen Beschreibung, die sagt, was er tut und wann er zu verwenden ist. Vierundzwanzig Anfragen, vier pro skill, so formuliert, wie ein Mensch sie formulieren würde, und ohne den skill je beim Namen zu nennen. Das Modell sieht die sechs Zeilen in seinem system prompt und muss mit einem Namen oder mit NONE antworten. Greedy decoding, damit es reproduzierbar ist. Dann dieselben vierundzwanzig Anfragen mit denselben sechs Skills, und die Beschreibungen auf ihr bloßes Thema zurückgeschnitten.

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

Lies zuerst die Intervalle, wie Kapitel 4 darauf bestand und Kapitel 29 wieder darauf bestehen wird: Sie überlappen, und vierundzwanzig Fälle können zwei Systeme nicht allein anhand ihrer Aggregate ranken. Der gepaarte Vergleich entscheidet es, und er ist das Instrument aus Kapitel 15: Von den zehn Fällen, in denen die beiden Arme sich unterschieden, gingen neun an die reichhaltigen Beschreibungen und einer an die dünnen. Das ist am üblichen Schwellenwert belegt.

Jetzt lies die letzte Zeile, denn sie ist der eigentliche Befund. Mit dünnen Beschreibungen antwortete das Modell bei neun von vierundzwanzig Anfragen mit NONE. Nicht der falsche skill: kein skill. Hier sind vier davon, wörtlich:

"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

Ein perfekter sql-review-skill war installiert, mit Body und Beispielen und einer Checkliste, und er wurde nie geöffnet, dreimal hintereinander, bei den drei Fragen, für die er geschrieben war. Level 2 und 3 sind irrelevant für einen skill, den Level 1 nie erreicht.

Die Kosten der Korrektur: 214 token, die Differenz zwischen 295 und 81, verteilt auf sechs Skills. Das ist der Befund aus Kapitel 18, von der anderen Seite kommend. Dort brachte die Änderung nur der Beschreibung eines Tools die Datumsformatierung von 2 korrekten von 24 auf 24 von 24. Hier bringt die Änderung nur der Beschreibung eines skills die Aktivierung von 10 von 24 auf 18. In beiden Fällen ist der günstigste Fix im System ein Satz, und in beiden Fällen muss der Satz den Trigger benennen und nicht nur das Thema: nicht, was das Ding ist, sondern was der Nutzer gerade gesagt haben wird, wenn es zutrifft.

Ein Vorbehalt, den dieses Kapitel seinen eigenen Standards schuldet. Dies ist ein Modell mit einer halben Milliarde Parametern, und ein Frontier-Modell routet deutlich besser als 75 %. Lies den Mechanismus, nicht die Größenordnung: Das Routing-Signal ist einen Satz lang, egal welches Modell es liest, und kein Modell kann nach Informationen auswählen, die du nicht in diesen Satz geschrieben hast.

Der zweite Fehler ist das Gegenteil des ersten. Der skill wird gefunden, die Level sind korrekt aufgeteilt, und der agent liest trotzdem alles.

vercel-react-best-practices ist ein wirklich gut gebauter skill. Sein 1.670-token-Body ist eine Prioritätstabelle aus acht Kategorien und eine Schnellreferenz, die 70 Regeldateien nennt, jeweils eine Zeile. Die Regeln liegen auf der Platte daneben: 70 Dateien, kleinste 132 token, Median 319, größte 1.052. Stell ihm eine Frage zu Barrel Imports, und die ehrlichen Kosten sind der Body plus eine Datei — unter 2.400 token gegenüber einem Bundle von 53.670.

Dann sagt die letzte Zeile des Bodys dies:

## Full Compiled Document

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

AGENTS.md hat 26.362 token. Es sind die 70 Regeldateien, aneinandergereiht: Ihre Summe ist 25.784, und die Differenz sind die Überschriften zwischen ihnen. Der skill bietet dem agent also die Wahl zwischen dem Lesen einer medianen Regel mit 319 token und dem Lesen desselben Inhalts, komplett, zum dreiundachtzigfachen Preis — und er bietet diese Wahl in einem Satz ohne angehängte Kosten und ohne Bedingung, wann sie zu treffen ist.

Das ist kein Bug, und die Datei ist nicht falsch; ein kompiliertes Dokument ist für einen Menschen wirklich nützlich, und für einen agent, der gebeten wurde, eine ganze Codebase zu auditieren. Es ist eine Level-3-Datei mit einer Level-2-Einladung, und die Lektion verallgemeinert sich über diesen einen skill hinaus: Jeder Pfad aus einer SKILL.md sollte sagen, was er kostet und wann er sich lohnt, weil das Modell nicht wissen kann, dass ein Dateiname dreiundachtzigmal teurer ist als der Dateiname darüber.

Derselbe Ordner enthält eine kleinere Lektion über Veralten. Der Body sagt „70 rules across 8 categories“ und listet 70 auf; das Verzeichnis rules/ enthält 72 Dateien, von denen zwei Scaffolding sind (_template.md und _sections.md); und die Sidecar-Datei metadata.json sagt „40+ rules“. Drei Zählungen derselben Menge in einem Ordner, eine davon richtig, eine davon arithmetisch, und eine davon aus einer früheren Version übrig geblieben. Ein skill ist ein Dokument, und Dokumente verrotten genauso wie ein Code-Kommentar, der vom Code daneben abgedriftet ist — mit dem Unterschied, dass dieses hier von einer Maschine gelesen wird, die keine Augenbraue hebt.

Die offene Spezifikation definiert sechs Frontmatter-Felder. Die Referenzimplementierung, Claude Code, akzeptiert zwanzig.² Fünf Gruppen sollte man namentlich kennen, weil an ihnen das Format aufhört, nur ein Dokument zu sein:

Argumente (arguments, argument-hint) lassen einen Menschen Werte übergeben, die in den Body eingesetzt werden, wodurch ein skill als Slash Command nutzbar wird. Scoping (paths) begrenzt die Aktivierung auf Dateien, die einem Glob entsprechen. Und dynamische context injection ist das, was das mentale Modell verändert: Eine Zeile der Form !`git diff HEAD` läuft bevor der Body gesendet wird, und ihre Ausgabe wird in den Text eingesetzt. Das Dokument ist ein Template, und ein Teil davon wird zur Lesezeit berechnet.

Nun die Falle, und sie steht in derselben Dokumentation: Außerhalb von Claude Code — im Webprodukt, über die Skills API, beim Packaging — sind nur die sechs spezifizierten Felder erlaubt, und jedes andere Feld ist ein harter Fehler beim Upload.² Ein skill, der in einem Produkt perfekt funktioniert, lässt sich also in einem anderen Produkt desselben Anbieters nicht installieren, und er scheitert am Frontmatter statt an irgendetwas, das du durch Lesen der Prosa testen könntest. Wenn dein skill portabel sein soll, sind die sechs Felder das gesamte Budget. Wenn nicht, sag es in compatibility, das genau dafür existiert.

Vier Dinge werden ständig miteinander verwechselt, und die Verwechslung ist keine Wortklauberei: Falsch zu wählen kostet bei jedem Turn Geld oder kostet dich eine Garantie, von der du dachtest, du hättest sie.

Die zwei fett markierten Zeilen sind der ganze Unterschied. Ein skill wird gelesen; ein Tool wird aufgerufen. Ein skill ist Prosa, die in der context window ankommt und mit allem anderen dort um attention konkurriert; das Modell kann ihr folgen, sie falsch lesen oder ignorieren, und nichts im System bemerkt es. Ein Tool ist ein Aufruf, der die Hände des Modells vollständig verlässt: Dein Code erhält Argumente, validiert sie, prüft Berechtigungen und entscheidet. Kapitel 18 formulierte es so, dass das Modell vorschlägt und dein Code verfügt, und genau diese Trennung hat ein skill nicht.

Also sechs echte Fälle, gelöst:

Die Geschichte ist kurz, ungewöhnlich gut datiert, und es ist der Teil, den fast niemand erzählt.

Agent Skills wurden am 16. Oktober 2025 als Feature eines Anbieters veröffentlicht, in dieser Ankündigung definiert als „organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks“, mit den drei Leveln beschrieben durch eine Analogie, die es wert ist, behalten zu werden: „like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix“.⁴

Am 18. Dezember 2025 wurde dieselbe Seite aktualisiert, um das Format als offenen Standard anzukündigen, mit eigener Spezifikation unter agentskills.io, Governance offen für Beiträge und einem Referenz-Validator.³ Gelesen am 7. September 2026 listet die Client-Showcase des Standards sechsundvierzig Produkte — Editoren, Terminals, Cloud-Plattformen und mobile Runtimes, einschließlich der First-Party-Coding-agents von Anthropic, OpenAI, Google und Mistral — jeweils mit Link auf die eigene Setup-Dokumentation.¹

Die Konvergenz mit MCP geschieht offen, mit Zahlen, die du prüfen kannst:

Der interessante Teil ist die Schließung, nicht die Vorschläge. SEP-2076 bat um ein viertes Primitive neben Tools, Resources und Prompts. Die daraus entstandene Working Group entschied, dass die Antwort nein lautet: Skills reiten auf dem bereits existierenden Resources-Primitive, als Opt-in-Extension.⁵ Kapitel 26 maß denselben Instinkt im eigenen Changelog des Protokolls, wo Sampling, Roots und Logging deprecated wurden, statt behalten zu werden. Ein Standardisierungsgremium, das einen eigenen Vorschlag entfernt, verhält sich gut, und der Grund, diese Geschichte mit den Zahlen davor zu erzählen, ist, dass die Zusammenfassungen, die du anderswo lesen wirst, Skills immer noch als MCP Primitive beschreiben.

Du kannst jetzt eine SKILL.md schreiben, sie in drei Level aufteilen, die sich bezahlt machen, das Frontmatter eines fremden skills lesen und wissen, welche Felder einen Upload anderswo nicht überleben werden, und die Frage beantworten, um die dieses ganze Kapitel gebaut wurde — system prompt, skill, Tool oder server — mit einem Grund statt aus Gewohnheit.

Was du nicht kannst: sagen, ob deiner funktioniert.

Jede Behauptung in diesem Kapitel, die wichtig war, war eine Messung, und die wichtigste war eine Accuracy: 18 von 24 gegen 10 von 24, mit einem Intervall auf beiden und einem gepaarten Test dazwischen, weil zwei überlappende Aggregate nichts entscheiden. Dieses Instrument war geliehen. Die Beschreibung eines skills ist ein Routing-Key, sein Body ist ein Verfahren, dem das Modell folgen kann oder nicht, und beide Eigenschaften findest du nur heraus, indem du das Ding viele Male laufen lässt und bewertest, was zurückkam — das heißt ein golden set, ein Grader, den du vor dem Lauf geschrieben hast, und die Metrik, die fragt, ob es jedes Mal funktioniert hat statt mindestens einmal.

Kapitel 29 ist genau das, und es beginnt mit der Zahl, von der die Methode dieses Kapitels abhängt: Ein agent, der sieben von zehn Malen erfolgreich ist, sieht aus wie 70 %, und sein pass^10 — die Wahrscheinlichkeit, dass er alle zehn schafft — ist null. Es misst außerdem drei Grader auf denselben zweihundert Transkripten und erhält 0 %, 13 % und 26 %, ohne ein einziges token neu zu generieren. Bevor du dem Satz vertraust, den du gerade in eine description geschrieben hast, brauchst du das Instrument, das dir sagen kann, dass er schlechter ist als der, den du ersetzt hast.

Jede token-Zählung in diesem Kapitel wurde lokal mit tiktoken 0.14.0 und dem o200k_base-Encoding am 7. September 2026 erzeugt: über die fünf Drittanbieter-Skills, die am Anfang dieses Kapitels aufgeführt sind, und über den für dieses Kapitel geschriebenen release-notes-skill, dessen vollständiger Text oben teilweise wiedergegeben ist. Level 1 wird als die einzelne Zeile - name: description gemessen, die ein Host in den system prompt rendert; Level 2 ist der SKILL.md-Body nach dem Frontmatter; Level 3 ist jede andere Datei im Ordner. Die Kosten verwenden die in Kapitel 16 gemessenen Preise für gpt-5.6-terra, $2,00 pro Million input token und $0,20 pro Million cached input token, angewandt auf diese Zählungen — sie sind Arithmetik auf gemessenen token, keine Beobachtungen einer Live-Rechnung. Zum Schreiben dieses Kapitels wurde keine bezahlte API aufgerufen.

Das Aktivierungsexperiment lief mit Qwen/Qwen2.5-0.5B-Instruct in halber Präzision auf einer Consumer-GPU, Greedy decoding, 24 Anfragen über sechs Skills, zweimal — einmal mit Beschreibungen, die sagen, was der skill tut und wann er zutrifft, einmal mit Beschreibungen, die im Stil des eigenen „poor example“ der Spezifikation auf ein bloßes Thema gekürzt wurden. Intervalle sind Wilson bei 95 %; der gepaarte Vergleich ist ein zweiseitiger exakter Vorzeichentest über die zehn diskordanten Fälle; das Wilson-Intervall ist das aus Kapitel 4 und der exakte gepaarte Vorzeichentest der aus Kapitel 15, beide unverändert wiederverwendet. Lies die Größenordnungen als Eigenschaft eines sehr kleinen Modells und die Methode als übertragbar.

Die fünf hier gemessenen Skills sind Drittanbieterpakete, nicht für dieses Kapitel geschrieben: next-best-practices und next-cache-components aus vercel-labs/next-skills, und vercel-composition-patterns, vercel-react-best-practices und vercel-react-native-skills aus vercel-labs/agent-skills. Ihre internen Zählungen — 70 Regeldateien, AGENTS.md mit 26.362 token, metadata.json datiert Januar 2026 und mit der Behauptung „40+ rules“ — wurden am 7. September 2026 aus den Dateien auf der Platte gelesen und sind Eigenschaften dieser veröffentlichten Version, keine Kritik an ihren Autoren: Jede einzelne davon ist genau die Art Drift, die in jedem Dokumentationsbaum auftritt, der häufiger bearbeitet als gezählt wird.