progressive-disclosure

name: progressive-disclosure description: > Design layered context strategies for AI agents. Avoid prompt stuffing by letting agents discover information incrementally through skill files, recursive references, subagents, and search tools. license: MIT allowed-tools: Read Edit Grep Glob metadata: author: lyzr version: "1.0.0" category: agent-architecture

Progressive Disclosure — Layered Context Discovery

When to Use

When a developer needs their agent to access a large body of knowledge without stuffing it all into the system prompt. Also when deciding between adding a tool vs. adding context that the agent can discover.

The Problem

Agents often need domain knowledge, but putting everything in the system prompt causes:

• Context rot — irrelevant information dilutes focus on the actual task
• Interference — reference docs make the model drift from its primary job
• Wasted tokens — most of the context goes unused in any given conversation

The Progressive Disclosure Pattern

Instead of front-loading context, create layers that the agent discovers on demand:

Layer 0: System prompt (identity, core instructions, tool list)
    |
Layer 1: Skill files (loaded when skill is invoked)
    |
Layer 2: References within skills (files the skill points to)
    |
Layer 3: Search results (agent uses grep/glob to find specifics)
    |
Layer 4: Subagent results (delegated deep research)

Each layer is only loaded when needed. The agent starts lean and adds context as the conversation requires it.

Claude Code Examples

Example 1: The Claude Code Guide

Problem: Users asked Claude Code about its own features (MCP, slash commands, etc.) but Claude didn't know the answers.

Rejected approach: Put all docs in the system prompt.

• Would add thousands of tokens of context rot
• Users rarely ask these questions
• Would interfere with Claude Code's main job: writing code

Progressive disclosure approach:

1. Give Claude a link to its docs (Layer 1)
2. Claude loads docs when asked about itself (Layer 2)
3. But Claude loaded too much — so they built a Guide subagent (Layer 4)
4. The subagent has specialized instructions for searching docs efficiently

Result: Claude can answer self-referential questions without polluting its main context.

Example 2: Agent Skills

Skills formalized progressive disclosure:

1. Agent reads SKILL.md (Layer 1)
2. Skill file references other files: See knowledge/api-reference.md (Layer 2)
3. Agent reads those files and follows more references recursively (Layer 2+)
4. Agent uses search tools if it still needs more context (Layer 3)

A common use of skills is to add search capabilities — instructions on how to query a database, call an API, or navigate a specific codebase structure.

Designing Your Disclosure Layers

Layer 0: System Prompt

Keep it focused:

• Agent identity (SOUL.md)
• Hard rules (RULES.md)
• Tool definitions
• 1-2 sentence description of each skill

Do NOT put here: reference docs, API schemas, lengthy examples, rarely-used instructions.

Layer 1: Skill Files

Each skill's SKILL.md contains:

• When to use this skill
• Core instructions (under 5000 tokens)
• References to deeper documents

# My Skill

## When to Use
When the user asks about X.

## Instructions
Do A, then B, then C.

## References
- For API details, read `knowledge/api-spec.md`
- For examples, read `knowledge/examples/`

Layer 2: Referenced Documents

Files that skills point to. The agent reads them only when following a reference.

Structure as knowledge/ with an index:

# knowledge/index.yaml
documents:
  - path: core-concepts.md
    always_load: true      # Layer 0 — keep very small
  - path: api-reference.md
    always_load: false     # Layer 2 — loaded on demand
  - path: troubleshooting.md
    always_load: false

Layer 3: Search

Give the agent tools to search when references aren't enough:

• Grep for code patterns
• Glob for file discovery
• Web search for external docs

Layer 4: Subagents

For deep research that would pollute the main context:

• Spawn a subagent with specialized search instructions
• Subagent returns a concise summary
• Main agent stays focused

Decision Framework

Is this info needed in EVERY conversation?
  YES → Layer 0 (system prompt) — but keep it minimal
  NO  →
    Is it needed when a specific skill is invoked?
      YES → Layer 1 (skill file)
      NO  →
        Can the agent find it by following references?
          YES → Layer 2 (referenced docs)
          NO  →
            Can the agent search for it?
              YES → Layer 3 (search tools)
              NO  → Layer 4 (subagent with specialized instructions)

Anti-Patterns