Agent Skills and SKILL.md: Progressive Disclosure, Measured

Chapter 14 set the rule for the second half of this course — connections, retries and cancellation are TypeScript — and declared five exceptions. This is one of them, and the reason is not a preference.

A skill is a Markdown file. Not a file that configures a program, not a file a program compiles: a document the model reads, in the same way it reads the message you typed. Giving this chapter a programming language would mean not having understood the format, and that misunderstanding is the single most common one about skills. Everything below is Markdown and YAML, plus one small shell script that exists precisely to show where code does and does not belong inside a skill.

Here is a real instruction: how one company writes its release notes. It is a procedure, not a preference — it has an ordered set of steps, a taxonomy, a voice, a template and a script that collects the raw material.

Put all of it in the system prompt, the way most teams do, and Chapter 16's arithmetic takes over. A system prompt is a prefix, and a prefix is paid on every call. Measured with o200k_base over the folder written for this chapter:

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

Twenty-four times cheaper when it is used, thirty-seven times cheaper when it is not. The rates are Chapter 16's: $2.00 per million input tokens.

Now the honest objection, because a chapter that skipped it would be advertising. Prompt caching mostly closes the money gap. A system prompt is stable and it sits first, which makes it the best cache candidate there is; at $0.20 per million for cached input, the same 68,640 tokens cost $0.0168 rather than $0.1373. Still three times the skill, but no longer a different order of magnitude.

The money was never the strongest argument. This is:

Caching makes a permanent prefix cheaper. It does not make it smaller.

At turn 40 the system-prompt version still has 1,716 tokens of release-note policy sitting in the window during a conversation about something else entirely, competing for what Chapter 24 called the model's attention budget. The skill version has 46. Cache the wrong thing and you have bought a discount on a distraction.

Written as a formula, with $n$ turns, $L_1$ the metadata, $L_2$ the body, $L_3$ the whole bundle and $R$ the set of bundled files actually read:

The whole of this chapter is the difference between multiplying the second term by $n$ and multiplying it by one or by zero.

A skill is a directory. The specification is short enough to state completely:

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 must begin with YAML frontmatter, and exactly two fields are required: name and description.¹ Four more are optional and no others are defined:

Here is the release-notes skill, complete, with its body under thirty lines:

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

Read what that body is. It is not the policy — it is a table of contents with an order of operations. The policy lives in three files it names and does not include. And step one hands work to a script, because a script's code never enters the context window at all: only its output does.²

The loading model has a name and three stages. The specification states them with a token budget attached:¹

1. Metadata, about 100 tokens: name and description, loaded at startup for every installed skill.
2. Instructions, recommended under 5,000 tokens: the SKILL.md body, loaded when the skill is activated.
3. Resources, as needed: bundled files, loaded only when something requires them.

The reference documentation puts a fourth column on the same table — when loaded, token cost, content — and the row that matters is the third: none until accessed.³ The sentence that summarises the whole chapter is there too:

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

The measured table at the top of this chapter is that claim checked against five skills nobody wrote for this article. Two rows deserve reading against each other.

next-best-practices has a 966-token body that links to nineteen files holding 19,374 tokens. Ask it to fix a hydration error and the agent reads the body plus hydration-error.md: 1,409 tokens out of 20,340, a factor of fourteen, and the other eighteen files are never opened.

next-cache-components has a 2,334-token body and no bundled files at all. It is a valid skill and a well-written one, and it has no level 3 to disclose. That is the honest limit of the technique: progressive disclosure is only a saving if there is something to defer. A skill whose knowledge does not decompose pays its whole body on activation, and the only lever left is not activating it.

Level 1 is a routing decision made from one sentence. Nothing else about a skill influences whether it is ever opened — not the quality of the body, not the examples, not the scripts. So the description is not documentation. It is the query surface, and it can be wrong.

The specification says so in the form of a good example and a bad one, and the bad one is four words: description: Helps with PDFs.¹ That is worth measuring rather than accepting.

Six skills, each with a plausible description that says what it does and when to use it. Twenty-four requests, four per skill, phrased the way a person would phrase them and never naming the skill. The model sees the six lines in its system prompt and must answer with one name or with NONE. Greedy decoding, so it reproduces. Then the same twenty-four requests with the same six skills, and the descriptions cut back to their bare subject.

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

Read the intervals first, as Chapter 4 insisted and Chapter 29 will insist again: they overlap, and twenty-four cases cannot rank two systems on their aggregates alone. The paired comparison is what settles it, and it is Chapter 15's instrument: of the ten cases where the two arms disagreed, nine went to the rich descriptions and one to the thin ones. That is established at the usual threshold.

Now read the last line, which is the actual finding. With thin descriptions the model answered NONE on nine of twenty-four requests. Not the wrong skill: no skill. Here are four of them, verbatim:

"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

A perfect sql-review skill was installed, with a body and examples and a checklist, and it was never opened, three times in a row, on the three questions it was written for. Levels 2 and 3 are irrelevant to a skill that level 1 never reaches.

The cost of fixing it: 214 tokens, the difference between 295 and 81, spread over six skills. Which is Chapter 18's finding arriving from the other side. There, changing only a tool's description took date formatting from 2 correct out of 24 to 24 out of 24. Here, changing only a skill's description takes activation from 10 out of 24 to 18. In both cases the cheapest fix in the system is a sentence, and in both cases the sentence has to name the trigger and not just the subject: not what the thing is, but what the user will have just said when it applies.

One caveat this chapter owes its own standards. This is a half-billion-parameter model, and a frontier model routes far better than 75 %. Read the mechanism, not the magnitude: the routing signal is one sentence long whatever model reads it, and no model can select on information you did not put in that sentence.

The second failure is the opposite of the first. The skill is found, the levels are correctly split, and the agent reads all of it anyway.

vercel-react-best-practices is a genuinely well-built skill. Its 1,670-token body is a priority table of eight categories and a quick reference naming 70 rule files, one line each. The rules are on disk beside it: 70 files, smallest 132 tokens, median 319, largest 1,052. Ask it one question about barrel imports and the honest cost is the body plus one file — under 2,400 tokens against a bundle of 53,670.

Then the last line of the body says this:

## Full Compiled Document

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

AGENTS.md is 26,362 tokens. It is the 70 rule files concatenated: their sum is 25,784, and the difference is the headings between them. So the skill offers the agent a choice between reading one median rule at 319 tokens and reading the same content, all of it, at eighty-three times the price — and it offers that choice in a sentence with no cost attached and no condition on when to take it.

That is not a bug and the file is not wrong; a compiled document is genuinely useful to a human, and to an agent that has been asked to audit an entire codebase. It is a level-3 file with a level-2 invitation, and the lesson generalises past this one skill: every path out of a SKILL.md should say what it costs and when it is worth it, because the model has no way to know that a filename is eighty-three times more expensive than the filename above it.

The same folder carries a smaller lesson in staleness. The body says "70 rules across 8 categories" and lists 70; the rules/ directory holds 72 files, of which two are scaffolding (_template.md and _sections.md); and the sidecar metadata.json says "40+ rules". Three counts of the same set in one folder, one of them right, one of them arithmetic, and one of them left over from an earlier version. A skill is a document, and documents rot exactly like a code comment that has drifted away from the code beside it — with the difference that this one is read by a machine that will not raise an eyebrow.

The open specification defines six frontmatter fields. The reference implementation, Claude Code, accepts twenty.² Five groups are worth knowing by name, because they are where the format stops being only a document:

Arguments (arguments, argument-hint) let a person pass values that are substituted into the body, which is what makes a skill usable as a slash command. Scoping (paths) limits activation to files matching a glob. And dynamic context injection is the one that changes the mental model: a line of the form !`git diff HEAD` runs before the body is sent, and its output is substituted into the text. The document is a template, and part of it is computed at read time.

Now the trap, and it is stated in the same documentation: outside Claude Code — on the web product, through the Skills API, in packaging — only the six specified fields are allowed, and any other field is a hard error on upload.² So a skill that works perfectly in one product fails to install in another belonging to the same vendor, and it fails at the frontmatter rather than at anything you could test by reading the prose. If you intend a skill to be portable, the six fields are the whole budget. If you do not, say so in compatibility, which exists for exactly this.

Four things get confused with each other constantly, and the confusion is not vocabulary pedantry: choosing wrong costs money on every turn, or costs you a guarantee you thought you had.

The two rows in bold are the whole distinction. A skill is read; a tool is invoked. A skill is prose that arrives in the context window and competes for attention with everything else there; the model can follow it, misread it, or ignore it, and nothing in the system notices. A tool is a call that leaves the model's hands entirely: your code receives arguments, validates them, checks permissions and decides. Chapter 18 put it as the model proposing and your code disposing, and that division is exactly what a skill does not have.

So six real cases, resolved:

The history is short, unusually well dated, and it is the part almost nobody tells.

Agent Skills were published on 16 October 2025 as one vendor's feature, defined in that announcement as "organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks", with the three levels described through an analogy worth keeping: "like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix".⁴

On 18 December 2025 the same page was updated to announce the format as an open standard, with a specification of its own at agentskills.io, governance open to contributions, and a reference validator.³ Read on 7 September 2026, the standard's client showcase lists forty-six products — editors, terminals, cloud platforms and mobile runtimes, including the first-party coding agents of Anthropic, OpenAI, Google and Mistral — each linking to its own setup documentation.¹

The convergence with MCP is being done in the open, with numbers you can check:

The interesting part is the closure, not the proposals. SEP-2076 asked for a fourth primitive beside tools, resources and prompts. The working group that formed out of it decided the answer was no: skills ride on the resources primitive that already exists, as an opt-in extension.⁵ Chapter 26 measured the same instinct in the protocol's own changelog, where sampling, roots and logging were deprecated rather than kept. A standards body that removes a proposal it authored is behaving well, and the reason to tell this story with the numbers in front is that the summaries you will read elsewhere still describe skills as an MCP primitive.

You can now write a SKILL.md, split it into three levels that pay for themselves, read the frontmatter of somebody else's skill and know which fields will not survive being uploaded somewhere else, and answer the question the whole chapter was built around — system prompt, skill, tool, or server — with a reason rather than a habit.

What you cannot do is tell whether yours works.

Every claim in this chapter that mattered was a measurement, and the one that mattered most was an accuracy: 18 out of 24 against 10 out of 24, with an interval on each and a paired test between them, because two aggregates that overlap decide nothing. That instrument was borrowed. A skill's description is a routing key, its body is a procedure the model may or may not follow, and both of those are properties you can only find out about by running the thing many times and scoring what came back — which is a golden set, a grader you wrote before the run, and the metric that asks whether it worked every time rather than at least once.

Chapter 29 is that, and it opens with the number this chapter's method depends on: an agent that succeeds seven times out of ten looks like 70 %, and its pass^10 — the chance it succeeds on all ten — is zero. It also measures three graders on the same two hundred transcripts and gets 0 %, 13 % and 26 % without regenerating a single token. Before you trust the sentence you just wrote into a description, you need the instrument that can tell you it is worse than the one you replaced.

Every token count in this chapter was produced locally with tiktoken 0.14.0 and the o200k_base encoding, on 7 September 2026: over the five third-party skills listed at the top of this chapter, and over the release-notes skill written for this chapter, whose complete text is reproduced above in part. Level 1 is measured as the single line - name: description that a host renders into the system prompt; level 2 is the SKILL.md body after the frontmatter; level 3 is every other file in the folder. The costs use Chapter 16's measured rates for gpt-5.6-terra, $2.00 per million input tokens and $0.20 per million cached input tokens, applied to those counts — they are arithmetic on measured tokens, not observations of a live bill. No paid API was called to write this chapter.

The activation experiment ran Qwen/Qwen2.5-0.5B-Instruct in half precision on one consumer GPU, greedy decoding, 24 requests over six skills, twice — once with descriptions that state what the skill does and when it applies, once with the descriptions cut to a bare subject in the style of the specification's own "poor example". Intervals are Wilson at 95 %; the paired comparison is a two-sided exact sign test over the ten discordant cases; the Wilson interval is Chapter 4's and the exact paired sign test is Chapter 15's, both reused unchanged. Read the magnitudes as a property of a very small model and the method as transferable.

The five skills measured here are third-party packages, not written for this chapter: next-best-practices and next-cache-components from vercel-labs/next-skills, and vercel-composition-patterns, vercel-react-best-practices and vercel-react-native-skills from vercel-labs/agent-skills. Their internal counts — 70 rule files, AGENTS.md at 26,362 tokens, metadata.json dated January 2026 and claiming "40+ rules" — were read from the files on disk on 7 September 2026 and are properties of that published version, not criticisms of its authors: every one of them is the kind of drift that appears in any documentation tree that is edited more often than it is counted.