Progressive Disclosure

An agent carries far more material than any single task needs: procedures it could follow, facts it has learned, tools it could call. Progressive disclosure structures that material 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 them.

Principle

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

Three Dimensions

Modern agent harnesses such as Claude Code apply the same principle along three independent dimensions. Each has its own always-present index and its own on-demand payload.

Skills — what the agent knows how to do

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.

Memory — what the agent knows about the user and project

Persistent memory is stored as one file per fact, each with a name and a one-line description in its frontmatter. Only an index — a MEMORY.md with one pointer line per memory — is loaded at session start. The body of a memory file is read only when its description matches the task at hand, and memories link to each other with [[name]] references that the agent follows only along the relevant branch. The per-turn cost is one line per fact, not the facts themselves. See Hierarchical Memory.

Deferred Tools — what the agent can call

Tool schemas are the most verbose part of a system prompt: every parameter, type and description of every MCP server. With deferred tools, the harness advertises only tool names; the full JSON schema is fetched through a search tool (Claude Code's ToolSearch, e.g. select:WebFetch,Monitor or a keyword query) only when the agent decides to call it. A session with a hundred connected tools pays for a hundred names, plus the schemas of the handful actually used. See Dynamic Tool Loading.

The three dimensions share one structure — index preloaded, body on selection — and one failure mode: an index entry too vague to trigger the load it guards. They differ in who writes the index: skill authors write descriptions, the agent writes its own memory descriptions, and tool descriptions come from the tool provider, with only the name surviving into the preloaded level.

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 deferred-tools dimension in depth: staged loading of tool schemas.
• Hierarchical Memory — the memory dimension in depth: an index layer over detailed memory files.
• 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.
• Claude Code memory — MEMORY.md index preloaded, one file per memory read on recall.
• Claude Code ToolSearch — deferred tools listed by name only; schemas fetched with select:<name> or keyword search before first call.
• MCP (Model Context Protocol) — resources are advertised by URI and description, and fetched by the client only when needed.