Progressive Disclosure

Type
Concept
Published
2026-04-29
Aliases
lazy loading skills, on-demand reference loading, lean skill pattern
Brief definition

A skill design pattern in which the skill itself loads as a short instruction file, and supporting reference material is fetched on demand only when the current task requires it — minimising token cost while preserving full expert depth when needed.

What it is

A naive skill that wants to encode framework-level expertise tends to grow large. Every pattern, every convention, every framework-specific snippet ends up inline. The result is a 2,000-line file that loads into context every time the skill is invoked, even when 90% of its content is irrelevant to the immediate task.

Progressive disclosure splits the skill into two layers. The top layer is a lean instruction file — Sukh Sroay cites roughly 80 lines for the Claude Skills plugin — that tells Claude how to think about a class of tasks and where to look for specifics. The second layer is a library of reference files (patterns, examples, debugging guides, framework-specific conventions) that the skill points to but does not include inline. When Claude invokes the skill, the lean instructions load immediately; references are pulled in surgically, only the ones the actual task needs.

Why it matters

Progressive disclosure is the skills-layer answer to the Context Window constraint. The pattern preserves full expert depth — all the references are still available — without paying the token cost upfront. Sroay’s framing captures the point: “80 lines lean. Then it surgically loads only the references your exact task needs. Zero token bloat. Full expert depth only when required.”

The pattern also makes skill libraries maintainable. A skill that is one large file gets edited as one large file; a progressively-disclosed skill can have its references updated independently of its instructions. This matters for long-lived skill libraries that encode evolving framework conventions or institutional patterns. Combined with Nested Skills, progressive disclosure lets a skill system scale to many domains and many depths without bloating the context window in any single interaction.