Progressive disclosure
Giving the agent a short index up front and letting it load the detail only when a task calls for it.
Progressive disclosure is the practice of exposing information in layers: a brief summary that is always present, with the full material available on request. In an agent setting, the top layer lives in AGENTS.md or a skill's description and costs a few lines of context. The lower layers are files, docs, and tools the agent reads only when the task turns out to need them. The name comes from interface design, where menus hide advanced options until you ask.
The alternative is loading everything up front, which fails in two directions. The context window fills with material the task never touches, and the attention budget that should go to the task is spread across pages of irrelevant setup. Sessions that start slow and sloppy often have a thousand-line instructions file as the cause, not the model.
Structure your instructions as a map, not a manual. The always-loaded file says what exists and when to read it: “deployment steps are in docs/deploy.md; read it before touching infra.” That line is a context pointer. Skills work the same way, with a one-line description in the index and the full procedure loaded on invocation. The agent stays sharp because it only pays for what it uses.
- Claude CodeSkills expose only their name and description until invoked; the SKILL.md body loads on use.
- Claude CoworkSkills and connectors appear as short descriptions and expand only when the task calls for them.
- Most toolsNested instruction files in subdirectories are a form of it; they load when the agent works in that directory.
“Should I put the whole API style guide in CLAUDE.md?”
“No. One line saying where it is and when to read it. That's progressive disclosure.”
“What if it doesn't read it?”
“Then say 'read docs/api-style.md before adding endpoints.' The pointer is cheap; the guide only loads when it's needed.”
Course 01 puts every one of these terms to work: you install Claude Code, run the loop, and ship a real project — permission modes, compaction, hooks and all.
Start Course 01 →