title: "What is Progressive Disclosure in Claude Code Skills?" description: "Progressive disclosure splits Claude Code skill content into three loading tiers so context costs stay flat even as your skill library grows." pubDate: "2026-04-14" category: skills tags: ["claude-code-skills", "progressive-disclosure", "beginner"] cluster: 14 cluster_name: "Progressive Disclosure Architecture" difficulty: beginner source_question: "What is progressive disclosure in Claude Code skills?" source_ref: "14.Beginner.1" word_count: 1480 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

What is Progressive Disclosure in Claude Code Skills?

TL;DR: Progressive disclosure is a loading architecture for Claude Code skills. Descriptions load at session start, the skill body loads on trigger, and reference files load on demand. The result: a library of 20 skills costs roughly the same context as a library of 5, because only one skill runs at a time.

Most developers hit a wall around their tenth skill. Claude starts getting slower. Instructions from early in the session disappear. Outputs that were reliable get inconsistent. The library that felt like a productivity tool starts feeling like a liability.

The problem isn't the skills. The problem is that all of them are loaded at once.

AEM's progressive disclosure architecture fixes this by splitting skill content across three tiers that load at different times, for different reasons, at different costs.

What is progressive disclosure in the context of skill architecture?

Progressive disclosure in Claude Code skill engineering is a three-tier loading model where Tier 1 (descriptions) loads at session start, Tier 2 (the full SKILL.md body) loads when a skill is triggered, Tier 3 (reference files) loads only when the running skill requests it, so context cost scales with the current task, not the total library size.

The term comes from UI design, where progressive disclosure means showing users only the information relevant to their current action, not everything at once. Applied to Claude Code skills, the same principle holds: load only what Claude needs for the current task, not everything in your library.

The three tiers are:

1. Descriptions (always loaded): every skill's description field loads at session start. This is the index.
2. Skill body (loaded on trigger): the full SKILL.md body loads when the user's message matches the skill's description.
3. Reference files (loaded on demand): files in the skill's references/ folder load when the running skill's instructions explicitly call for them.

A library of 20 skills with progressive disclosure loads roughly 1,000-2,000 tokens at startup (AEM production measurement, 2025). Without it, that same library loads 15,000-80,000 tokens before any task begins (AEM production measurement, 2025).

Why does progressive disclosure exist? What problem does it solve?

Progressive disclosure exists because Claude has a fixed context window, and loading an entire skill library at session start consumes that window before your task begins — every token spent on inactive skills is a token unavailable for instructions, input, and output on the task you're actually running.

Claude's context window is 200,000 tokens (Anthropic, 2024). That sounds enormous until you start loading skill libraries. A SKILL.md body averages 400-1,200 tokens (AEM production measurement, 2025). A reference file averages 500-3,000 tokens (AEM production measurement, 2025). If you load all of these at session start for 15 skills, you've consumed 15,000-60,000 tokens before your task begins.

The second problem is instruction reliability. Stanford's NLP Group found that language models lose track of instructions that appear in the middle of a long context ("Lost in the Middle," Nelson Liu et al., ArXiv 2307.03172, 2023). Instructions placed at position 50,000 in a 200,000-token context are retrieved with significantly less accuracy than the same instructions at position 1,000. When your task-specific instructions are buried under 50,000 tokens of skill library, Claude's compliance drops.

Progressive disclosure keeps task-relevant content near position zero in the context. Your current task's instructions load first. Everything else stays off.

What are the three tiers and what does each one contain?

The three tiers are the description layer, the skill body, and the reference files, each with a specific scope, loading trigger, and token cost: descriptions load always at 50-100 tokens per skill, the body loads on trigger at 400-1,200 tokens, and reference files load only when the running skill's instructions explicitly call for them.

Tier 1: The description layer

Content: the description field from each SKILL.md file. Loading trigger: session start, automatic. Token cost: 50-100 tokens per skill.

This is what Claude reads to know your skills exist. It's the persistent index. Every skill in your library contributes its description to this layer. The description must serve double duty: it's the index entry and the trigger condition simultaneously.

Tier 2: The skill body

Content: everything in the SKILL.md file below the description, the instructions, process steps, output format, constraints. Loading trigger: user message matches the skill's description. Token cost: 400-1,200 tokens per skill.

This is the working memory for your task. It loads when your skill fires, stays for the full task, and unloads when the session ends.

Tier 3: Reference files

Content: external files in the skill's references/ directory, rubrics, vocabulary lists, style guides, checklists, example libraries. Loading trigger: an explicit Read instruction in the skill body. Token cost: 500-4,000 tokens per file.

These load conditionally, when a specific task needs them. A skill with three reference files loads only the one (or two) relevant to the current task, not all three by default.

What does progressive disclosure look like in practice?

In practice, progressive disclosure collapses the startup cost of a multi-reference skill from 5,400 tokens to 75, then loads only what the current task needs: a code-review skill with three reference files costs 75 tokens at session start instead of 5,400, and a standard review run costs 2,400 tokens instead of the full library weight.

Say you have a code-review skill. It has a SKILL.md body with 900 tokens of instructions, and three reference files: security-rubric.md (1,800 tokens), code-quality-rubric.md (1,500 tokens), and documentation-rubric.md (1,200 tokens).

Without progressive disclosure, all of this loads at session start: 900 + 1,800 + 1,500 + 1,200 = 5,400 tokens, whether you're about to do a code review or not.

With progressive disclosure, session start costs 75 tokens for the description only. When you ask for a code review, the 900-token body loads. The SKILL.md body's instructions say: "Load security-rubric.md if the user requests a security review. Load code-quality-rubric.md for all reviews. Load documentation-rubric.md if the PR includes documentation changes."

A standard code review loads 900 + 1,500 = 2,400 tokens. A security-focused review loads 900 + 1,800 + 1,500 = 4,200 tokens. The token cost scales with the task complexity, not with the size of your skill library.

"Developers don't adopt AI tools because they're impressive — they adopt them because they reduce friction on tasks they repeat every day." — Marc Bara, AI product consultant (2024)

Progressive disclosure is how you keep a growing skill library from becoming the friction it was supposed to eliminate.

Do I need progressive disclosure for my skill?

Not always — progressive disclosure pays for itself once your library reaches 10 or more skills, or once any skill carries reference files exceeding 150 lines, because that is the point where startup token costs and mid-session instruction loss become measurable; below that threshold, the architecture overhead outweighs the savings.

You need progressive disclosure if:

• Your library has 10 or more skills
• Any skill has reference files with 150+ lines of content
• You're noticing Claude losing instructions mid-session as your library grows

You don't need it for:

• Libraries with 3-5 simple skills
• Skills with no reference files and SKILL.md bodies under 400 tokens
• One-off or experimental skills that won't be in long-term rotation

We measured this threshold across production skill libraries built in AEM: once you're past 10 skills or once a skill's reference content exceeds 150 lines, the token savings from progressive disclosure outweigh the architecture overhead.

For a detailed breakdown of the actual token costs at each tier, plus how to design your skills to exploit the architecture, see Progressive Disclosure: How Production Skills Manage Token Economics.

Frequently asked questions

What's the simplest way to add progressive disclosure to an existing skill? Move any content that isn't needed on every task run into a references/ subdirectory inside your skill folder. Then add a line to your SKILL.md body: "Read references/[filename].md before [specific step]." That's the minimum viable implementation.

Does Claude load reference files automatically, or do I have to trigger them? You have to trigger them explicitly. Reference files load only when your SKILL.md body contains an instruction like "Read references/rubric.md." Claude doesn't scan the references/ directory automatically. This is by design — it gives you control over what loads when.

If I have 5 skills and none of them have reference files, is my library already using progressive disclosure? Partially. The description index (Tier 1) is always in effect for Claude Code skills. The distinction between Tier 2 and Tier 3 only applies if your skill has reference files. At 5 skills with no references, you're using the first tier correctly, and Tiers 2-3 aren't relevant yet.

How do I know how many tokens my skill descriptions are using at startup? Count the characters in each description field and divide by 4 (rough tokens-per-character estimate for English text; OpenAI and Anthropic tokenizer benchmarks, 2024). A 120-character description is roughly 30 tokens. At 20 skills averaging 120 characters each, your startup index costs around 600 tokens.

Can progressive disclosure be used with agent subskills, not just standalone skills? Yes. The same three-tier model applies when skills are invoked by agents as part of a multi-step workflow. The description still loads at startup. The body loads when the agent triggers the skill. Reference files load when the body instructs them. For multi-agent architectures, the token economics get more complex, but the per-skill cost structure stays the same.

Last updated: 2026-04-14