Part 10 of 13 · 4 min read
The same trick, for instructions instead of data
The same trick, for instructions instead of data: progressive disclosure and SKILL.md
Think of an onboarding guide for a new hire. There is a table of contents on page one. There is a chapter you open only when that part of the job comes up. There is an appendix nobody reads until one specific form needs filling in.
In plain words: part 1 offloaded data to a file and kept a short stub in the window. An Agent Skill applies the exact same idea to procedural instructions instead of tool output: a skill is a directory containing a SKILL.md file (required) plus, optionally, reference files and scripts. At the start of a session, the agent sees only each installed skill's name and description, pulled from SKILL.md's metadata -- not the instructions themselves. When a task's description matches a skill, the agent then reads the full SKILL.md body. If that body points to a reference file for something more specific, that file loads too, only then. Anthropic calls this progressive disclosure, and it is why an agent can carry hundreds of skills without most of their content ever touching its context window -- the same shape as this module's stub, just applied one level up, to know-how rather than to a tool's output.
A worked example. Anthropic's own reported figures for this three-tier load: metadata for an installed skill costs roughly 50 tokens; the full SKILL.md body, once loaded, costs roughly 500 tokens; a reference file loaded on top of that can run 2,000 tokens or more. A skill that packages, say, a company's PDF-formatting conventions sits dormant at 50 tokens until a request actually involves a PDF -- at which point its 500-token body loads, and only if that body itself points to a forms.md reference does the agent pay the 2,000-token cost of reading it. Compare that to pasting the same instructions into a system prompt on every single turn regardless of whether the task needs them: the cost structure is identical to this module's stub-versus-full-file choice in part 1, with "skill" written where part 1 wrote "tool output."
About this example About this part
This module's mini-workspace has no skill loader; nothing here is run. Anthropic published Agent Skills on 16 October 2025 and opened the format as a cross-platform standard at agentskills.io on 18 December 2025, under the same Agentic AI Foundation that took in AGENTS.md (part 9). The token figures above are Anthropic's own reported approximations for its three-tier design, not measurements from this repo. Last checked: 15 November 2026.
Agent Skill, SKILL.md, progressive disclosure
An Agent Skill is a directory of procedural knowledge for an agent: a required SKILL.md file, plus optional reference files and scripts the agent can read or run when the skill is actually in use. SKILL.md carries YAML metadata (name, description) at the top, for cheap discovery, and the instructions themselves in the body below it. Progressive disclosure is loading that content in stages -- metadata always, the body when the task matches, reference files only when the body itself points to them -- rather than paying the full cost on every turn regardless of relevance.
Example: a skill's 50-token metadata sitting in context all session while its 500-token body loads only on the one turn that needs it is progressive disclosure doing, for know-how, exactly what a stub path does for a tool's output in part 1: most of the content exists, fully retrievable, without occupying space on every request.
For the curious Skill or AGENTS.md: which one
Part 9's AGENTS.md is one flat file, read in full at the start of every session, meant to be short -- project conventions a session needs regardless of what it ends up doing. A Skill is the opposite shape on purpose: possibly large, but invisible until a specific task calls for it, and then loaded in exactly the depth that task needs. A project typically wants both: a short AGENTS.md for what is always true, and a shelf of Skills for what is only sometimes true.
What the example does not do
About this example What the example does not do
- The agent is deterministic. A real model sometimes greps the wrong file, uses a bad pattern, or reads too much; the exercises measure that.
- Questions are answerable by one grep. Multi-hop questions over several files, or ones needing a computation across files, cost more.
- No concurrency, quotas or sandboxing.
- Tokens are estimated by the module 1 counter.
- Optional real-model experiment: give a real model the stub window and the three file tools and measure how often it picks the right file and pattern.
Check yourself
An agent saves a 1,000-token log to a file and leaves a 25-token stub. Later it needs a reference code that nobody flagged. Which is safer, a notes file or the saved log, and why?
Show answer
The saved log. Notes only hold what was judged important when written; the log still has the detail.
What you will use daily at work
| Practice | What it looks like |
|---|---|
| Stub plus path | The window holds a pointer, the file holds the data. |
| Capped reads | A read returns a few hundred tokens and says how to continue. |
| Confine the path | Resolve the path and check it is under the root before every read or write. |