Keep the top-level file lean and push branch-specific detail into references/ — the agent loads only the reference for the branch it actually takes.

Pattern

Progressive Disclosure

The shape

One lean orchestrator. A folder of details loaded on demand.

skills/planning-products/

Progressive

├──SKILL.md

~1,200 words · always loaded

│ what, why, critical rules, branch decisions

└── references/

loaded only when hit

├──agent-system-template.md

Step 2 only

├──task-templates.md

Step 4 — every task

├──orchestration-rules.md

Step 5 only

└──spawn-template.md

Step 6 only

ReferenceFull templates and edge cases for one branch. Invisible until that branch fires.

If you inline everything into SKILL.md, every agent pays the cost of every branch — including the branches it never takes.

The context budget

Orientation is a tax. Progressive Disclosure minimizes it.

Monolithic SKILL.md~35% orientation

35% orient

65% execute

single fat file~35%

work left~65%

Every branch pays for every branch. The schema task carries 5,500 words of service-task detail it never reads.

Progressive Disclosure~17% orientation

top

ref

83% execute

one reference~9%

work left~83%

Cost is proportional to the branch taken. Top-level + one reference — the siblings stay on disk, invisible.

Across thousands of invocations the 18-point delta compounds — into usable execution headroom, or into polluted context and truncated work.

When to split a reference

Not every detail earns its own file.

✓ Split it out

• Only one workflow branch needs the detail
• Reading it when irrelevant would waste the budget
• The section could be improved independently of the rest
• Content is detailed — templates, edge cases, long examples

✗ Keep it inline

• The detail is needed on every execution
• It's short enough that navigation overhead beats the saving
• It belongs to the critical rules every agent must see
• Splitting would force a round-trip for three lines of content

The test: would an agent that doesn't take this branch be worse off for reading it? If yes, it's a reference.

Applied to CLAUDE.md

Project root points out to where the rest lives.

CLAUDE.md is loaded by every agent. It stays lean — and points to what's loaded on demand.

Always loaded

CLAUDE.md

▸project overview

▸critical rules

▸slash command index

▸quick-start

agent works

in ADW layer→

agent needs

tool docs→

agent runs

a command→

adws/README.md

ADW architecture · hooks

ai_docs/…

domain tool reference

.claude/commands/…

the specific command body

CLAUDE.md is an index, not a manual. The agent reads it, learns where to find more, and loads only what its branch demands.

The discipline

Context usage stays proportional to the work — not to the file that describes it.

A monolithic SKILL.md makes every agent pay for every branch. Progressive Disclosure pushes detail behind a branch decision — agents load what they need, not what someone else might need. Top-level is the map; references are the terrain.