Progressive Disclosure

An agent capability — a skill, a playbook, a per-harness tool reference — is usually written as a body of documentation far larger than any single task needs. Progressive disclosure structures that documentation into levels, so that only a one-line pointer is preloaded and the deeper levels enter the context window only when the agent actually decides to use the capability.

The canonical implementation is Anthropic Agent Skills: a skill is a directory whose SKILL.md carries YAML frontmatter with a name and a description. Only that name and description are injected into the system prompt for every skill installed. When the model judges the skill relevant, the harness reads the body of SKILL.md into context. Files referenced from that body — references/*.md, scripts/, templates, schemas — are loaded only if the skill's instructions send the agent there. Three levels, each one paid for only when reached.

Principle

Preload a discovery-sized pointer; load the full instructions on selection; load the long tail only on demand. The cost of having a capability available becomes independent of the size of its documentation, so a library of capabilities can grow without a per-turn tax.

Techniques

Name + Description Index

Only the metadata of each capability sits in the always-present context: enough for the model to decide whether this is the right thing, never enough to perform it. Descriptions must therefore be written for triggering — naming the concrete situations that should select the skill — rather than for summarizing.

Body on Selection

The instruction body loads when the capability is invoked. This is where the procedure lives. Keeping it out of the preloaded level is what lets an agent carry hundreds of skills at a fixed cost.

Reference Files on Demand

Long reference material — API tables, edge-case catalogs, format specs — lives in separate files that the body links to, with a one-line hint about when the agent should open each. The agent reads them only along the branch it is actually walking.

Audience-Sharded References

Where documentation varies by environment, split it per environment rather than writing one document covering all cases with conditionals. A tool reference sharded into one file per harness means an agent loads only its own harness's file; a single combined file would charge every agent for every harness.

Executable Instead of Explained

A scripts/ directory holds code the agent runs rather than prose the agent reads. The token cost is the invocation line, not the algorithm, which also makes the step deterministic. See Generator Invocation.

Trade-offs

The failure mode is not cost but recall: a level that never loads is documentation the agent behaves as if it does not have. Each pointer must state the condition under which to follow it.

Anti-patterns

• Putting the whole procedure in the description field, which reintroduces the per-turn cost the design removes.
• One monolithic instruction file with sections for every variant, so every reader pays for every variant.
• Reference files linked with no indication of when to open them — the agent either loads all of them or none.
• Restating the content of a reference file in the body "so the agent does not have to open it."
• Levels deep enough that reaching the operative instruction costs more round-trips than inlining it would have cost tokens.

See Also

• Dynamic Tool Loading — the same staged-loading principle applied to tool schemas rather than to instructions.
• Selective Context Inclusion — deciding per query which material is relevant; progressive disclosure makes that decision structural and delegates it to the model.
• Context Isolation via Subagents — an alternative when the material is bulky data rather than instructions.
• Subagents as Context Firewalls — a child loads its own skills, so the parent never pays to pass them down.
• Prompt Caching — the preloaded metadata index is stable and cacheable.
• Signal-per-Token Optimization — each disclosure level should carry the densest possible signal.
• Generator Invocation — scripts shipped with a skill are disclosure by execution rather than by reading.

Tools

• Anthropic Agent Skills — three-level disclosure: frontmatter name/description preloaded, SKILL.md body on selection, references/ and scripts/ on demand.
• Claude Code skills — the harness injects only skill metadata into the system prompt and reads the body when the skill is invoked.
• MCP (Model Context Protocol) — resources are advertised by URI and description, and fetched by the client only when needed.