Progressive Disclosure Rules
Design Claude workspaces, projects, and agents so the model sees the right context at the right moment — not everything at once. Use when configuring a Project, building a Skill, or auditing why an agent feels distracted, slow, or expensive.
Install
npx at-skills install progressive-disclosure-rulesDrops files into ~/.claude/skills/progressive-disclosure-rules/. Restart Claude Code to load it.
Progressive Disclosure Rules
The goal is not to give the agent more context. It is to give it the right context — and only when the next decision actually depends on it.
Purpose
Apply the three rules below to design any Claude-facing surface — Projects, Skills, system prompts, workspace docs — so that context loads in layers rather than all at once. The result is faster, cheaper, and less scattered agent behavior.
When to use
Invoke this skill in these situations:
- Configuring a new Claude Project (top-level description + uploaded files)
- Authoring or revising a Skill (
SKILL.md+ references) - Auditing a workspace where agents feel slow, distracted, or expensive
- Reviewing an organically-grown setup that has accumulated material over time
- Deciding what to inline vs. what to defer when writing instructions for any agent
The three rules
Apply all three together. They are interdependent.
1. Default to closed drawers. Treat every document, file, or context source as a drawer that must be opened deliberately. Render the top level as a one-page map: how to navigate, what each drawer contains, and the signal that should open it. Inline nothing else at the top level.
2. Disclose by signal, not by precaution. Open a drawer only when the conversation gives an explicit signal it is needed — a keyword, a file mention, a tool result, a user phrase, a referenced policy name. Reject precautionary loading ("might be useful later", "better safe than sorry"). Precautionary loading dilutes attention and burns tokens.
3. Optimize for the next decision, not the whole job. Surface only enough context to decide what to do next. Trust the system to disclose more when the next next-decision demands it. Never preload the full architecture, the team handbook, or the complete policy set "to be thorough".
How to apply
For the specific situation in front of you, load the matching reference:
- Configuring a Claude Project → load references/patterns/summary-with-drawer.md. The Project description is the map; uploaded files are drawers.
- Authoring or refactoring a Skill → load references/patterns/progressive-skill-structure.md. This skill itself is the worked example.
- A workspace with more than 5 drawers → load references/patterns/tiered-context.md. Promote to L0/L1/L2 tiers.
- Auditing an existing setup → run references/audit-checklist.md. Seven questions, ten minutes.
- Deciding whether to load X now or later → consult references/when-to-disclose-what.md. Decision table.
- Looking for a concrete before/after → read references/bad-vs-good.md. One scenario, two configurations.
What this skill is not
This is not a rule against giving the agent context. It is a rule against giving the agent all the context all the time. Drawers must exist and be findable. They must not be permanently open.
One-line summary
A new employee on their first day does not need the entire company wiki — they need one good map and a working desk drawer they know how to open.