Your AI coding agent has access to 47 skills, 12 MCP server connections, and a project configuration file with 200 lines of instructions. Loading all of that into the agent's context window at the start of every conversation would burn through thousands of tokens before you even type your first question.
Progressive disclosure solves this by loading information in layers. The agent sees only what it needs, when it needs it. Everything else stays on the shelf until called for. It is a foundational concept in context engineering.
Progressive Disclosure Context Loading Explained
Progressive disclosure is a three-level loading strategy that controls how much information enters an AI agent's context window at any given time. Instead of dumping everything into the prompt upfront, it loads content in stages based on relevance.
The concept is borrowed from user interface design, where it means showing users only the essential options first and revealing advanced features on demand. In the agent world, it applies the same principle to context management. The agent's context window is a limited resource, and progressive disclosure treats it like one.
"The best context strategy is not giving the agent everything it could need. It is giving the agent exactly what it needs right now."
The Three Levels of Loading
Progressive disclosure in modern agent harnesses follows a consistent three-level pattern.
| Level | What Loads | When It Loads | Token Cost |
|---|---|---|---|
| Level 1: Metadata | Name and one-line description of each skill, tool, or resource | Always, at session start | Very low |
| Level 2: Body | Full instructions, procedures, and configuration details | On trigger, when the user invokes a skill or the agent determines relevance | Moderate |
| Level 3: Files | Referenced assets, scripts, templates, and supporting documents | On reference, when the body explicitly points to additional resources | High |
At Level 1, the agent knows what exists. At Level 2, the agent knows how to do it. At Level 3, the agent has everything it needs to execute. Each level only loads when the previous level signals that more detail is required.
Why Progressive Disclosure Matters for AI Agents
Context Windows Are Finite
Every AI model has a context window limit. Even models with 200,000 token windows run into practical limits when the context gets too large. Retrieval accuracy drops as context grows, a problem related to context rot. The model spends more time processing irrelevant information and less time focusing on the actual task. Progressive disclosure keeps the context lean and relevant.
Token Costs Add Up Fast
Every token in the context window costs money on API-based models. A project with 50 skills, each averaging 500 tokens of instructions, would consume 25,000 tokens just for skill definitions. Loading all of them into every conversation means paying for 25,000 tokens of context that goes unused 95 percent of the time. Progressive disclosure cuts that to a few hundred tokens of metadata, loading full instructions only for the one or two skills the conversation actually needs.
Speed Matters
Larger contexts mean slower response times. The model takes longer to process the prompt, and the first token takes longer to appear. In an interactive coding session where you expect near-instant responses, loading 50,000 tokens of skill definitions creates noticeable lag. Progressive disclosure keeps the initial context small and the first response fast.
How Progressive Disclosure Reduces Token Cost
The math behind progressive disclosure is straightforward. Consider a project setup with the following resources.
- 40 skills, each with a 10-token metadata entry and a 400-token body
- 15 MCP server descriptions at 50 tokens each
- A project configuration file at 2,000 tokens
- Average conversation uses 2 skills
Without progressive disclosure, every conversation loads everything. That is 40 times 400 plus 15 times 50 plus 2,000, totaling 18,750 tokens before the user says a word.
With progressive disclosure, the agent loads 40 metadata entries at 10 tokens each (400 tokens), the 15 server descriptions (750 tokens), and the project config (2,000 tokens). When the user triggers a skill, it loads that skill's 400-token body. A typical conversation uses about 3,950 tokens of context instead of 18,750. That is a 79 percent reduction in context cost.
"Progressive disclosure does not limit what the agent can do. It limits what the agent has to think about at any given moment."
Progressive Disclosure in Practice
How Modern Harnesses Implement It
Modern agent harnesses have made progressive disclosure the default loading strategy, part of the broader AI-driven development shift. When the agent starts a session, it receives a list of available skills with just their names and descriptions. This list acts as a menu. The agent can scan it quickly to understand what capabilities are available without processing the full instructions for each one.
When the user types a slash command or asks for something that matches a skill description, the harness loads that skill's full body into the context. The agent now has the detailed instructions it needs to execute the task. If those instructions reference external files, templates, or scripts, the harness loads those only when the agent reaches the step that needs them.
Deferred Tool Loading
The same principle applies to tool definitions. An agent connected to multiple MCP servers might have access to hundreds of tools. Without proper scoping, this also expands the blast radius if something goes wrong. Loading the full JSON schema for every tool at session start wastes context on tools that will never be called. Instead, the harness loads only the tool names and descriptions. When the agent decides to call a specific tool, the full schema loads on demand.
This is why some tools appear as "deferred" in agent sessions. Their names are visible so the agent knows they exist, but their parameter schemas are not loaded until the agent actually needs to call them. This also reduces the risk of tool poisoning by limiting exposure to tool descriptions. The fetch happens transparently, adding only the relevant schema to the context right before the call.
Designing for Progressive Disclosure
If you write skills or tool descriptions, structuring them for progressive disclosure makes the whole system work better.
- Write descriptions that stand alone. The one-line description at Level 1 must give the agent enough information to decide whether to load the full body. A description like "Deployment helper" is too vague. A description like "Deploy the current branch to staging with database migrations and health checks" tells the agent exactly when this skill is relevant.
- Keep the body self-contained. The full instructions at Level 2 should contain everything the agent needs for most executions. Only reference external files when the task genuinely requires them.
- Minimize file references. Every file the body points to is a Level 3 load that adds tokens to the context. If a template is short enough to include inline in the body, do that instead of referencing a separate file.
- Use clear trigger words. Include specific keywords in the description that match how users naturally ask for the task. This helps the agent match user requests to skills without loading every skill body to check. It also prevents agent drift by keeping the context focused.
Progressive Disclosure Beyond Skills
The three-level pattern applies to more than just skills. Conversation memory, project documentation, code architecture, and even error logs can all benefit from progressive loading. The principle is always the same. Show the agent what exists at the lowest cost, load details when they become relevant, and fetch supporting materials only when execution demands them.
This pattern also helps with context window management over long conversations. As a conversation grows, older context can be summarized and compressed while keeping metadata pointers to the full details. If the conversation circles back to an earlier topic, the full details reload from the pointer. The agent maintains awareness without maintaining every detail in active context. Without this, teams accumulate verification debt from unreviewed context bloat.
Conclusion
Progressive disclosure is a three-level context loading strategy that keeps AI agent sessions fast, cheap, and focused. It loads metadata always, full instructions on trigger, and supporting files on reference. This approach reduces token costs by up to 80 percent in typical sessions while giving the agent access to the same full set of capabilities. It is now the default loading strategy in modern agent harnesses because it solves the fundamental tension between giving an agent broad capabilities and keeping its context window lean enough to work effectively. If you build skills, tools, or agent configurations, designing for progressive disclosure means writing descriptions that stand alone, keeping instructions self-contained, and minimizing external file references. It pairs naturally with well-structured agent skills that follow the same layered approach.
