In the rapidly evolving world of AI agents, the ability to extend capabilities with specialized knowledge is transformative. But what happens when you have hundreds of skills?

As LLMs become more capable, developers are building complex agents equipped with massive libraries of functions, API integrations, and customized workflows. Whether you're building a software engineering assistant (like Claude Code) or a general-purpose workspace copilot, scaling the list of tools and instructions is a natural evolution.

However, this scalability immediately runs into a fundamental wall: the Context Window Bottleneck.

The Core Problem: Context Rot

Even as modern LLMs boast massive context limits—spanning hundreds of thousands or even millions of tokens—stuffing every single tool definition, system prompt, and schema into the context window at start-up is a recipe for disaster. This leads to what is known as Context Rot:

1. Attention Dilution: When an LLM is flooded with hundreds of tool schemas, its attention gets diluted. It struggles to identify the needle in the haystack, leading to poor reasoning and decision-making.
2. The "Lost-in-the-Middle" Phenomenon: Extensive research shows that language models are highly reliable at retrieving information at the absolute beginning or end of their context window, but routinely miss or ignore instruction blocks placed in the middle.
3. Instruction Drift and Hallucinations: The higher the ratio of irrelevant instructions to the current task, the more likely the agent is to execute wrong tools, hallucinate parameters, or mix up instructions.

The Solution: Progressive Disclosure

Progressive Disclosure is a concept borrowed from interaction design where information is revealed only as it becomes necessary for the immediate task. In agentic architectures, it means treating the context window as a scarce, premium resource rather than an infinite bucket.

Instead of a flat system prompt where everything is loaded upfront, progressive disclosure uses a three-tier, layered context retrieval model:

graph TD
    A[User Request] --> B[Layer 1: Metadata Index]
    B -->|Selects relevant skills| C[Layer 2: Activation / SKILL.md]
    C -->|If needed, deep references| D[Layer 3: Deep Context / Schemas]

Layer 1: The Metadata Index (Always Loaded)

At start-up, the agent loads only a lightweight catalog of all installed skills. This catalog contains only:

• The skill's unique name/identifier.
• A single, descriptive sentence explaining what the skill does.

Example:

{
  "skills": [
    { "name": "aws_deploy", "desc": "Deploys applications to Amazon Web Services ECS/S3." },
    { "name": "db_query", "desc": "Queries relational PostgreSQL databases for analytics." }
  ]
}

This Layer 1 catalog consumes virtually no tokens (often less than 1% of the prompt budget) while ensuring the model is fully aware of its entire capability set.

Layer 2: On-Demand Activation (Loaded on Trigger)

When the user requests a task (e.g., "Can you deploy my front-end to S3?"), the agent identifies aws_deploy from its lightweight catalog.

Only at this moment does the agent fetch and inject the full instruction set—often formatted as a SKILL.md file—into the context window. The detailed specifications, parameters, and system prompts of db_query and other 99+ skills remain completely dormant.

Layer 3: Deep Context References (Loaded on Request)

If the aws_deploy skill has large API payloads, complex configuration templates, or historical logs, these are not loaded even during Layer 2 activation. They are kept as modular files and referenced in the SKILL.md. Only when the model decides to invoke a specific sub-task does it read these deep files.

Why this changes everything

1. Massive Token Efficiency: 90% of your codebase's specialized instructions remain unloaded at any given moment, keeping context windows lean, fast, and cost-effective.
2. Laser-focused Accuracy: The model is presented only with the rules that matter for the active task. This virtually eliminates cross-instruction confusion.
3. Infinite Scalability: You can theoretically support thousands of custom tools. The complexity of the system prompt scales with the immediate task, not the total feature list of the agent.

Implementing it in your agent loop

To build an agent that leverages progressive disclosure, restructure your agentic loop to:

1. Parse the prompt against a semantic index (or LLM router) of skill descriptions.
2. Dynamically load the matched skill instructions into the active context.
3. Perform the task, and clear the context (or let it expire) once the conversation topic shifts.

By moving from a "load-all" approach to Just-in-Time (JIT) context, you build AI systems that are both highly capable and exceptionally precise.