Progressive Disclosure

What is Progressive Disclosure, and how does it differ from putting everything into one document?

Progressive disclosure means organizing a document's content in layers: the top layer is a concise main file (Skill.md, for instance) containing only the most basic usage and a "signpost" — links pointing to other extension files. The genuinely detailed content (advanced features, a full API reference, extensive examples) each lives in its own separate file, and Claude only reads the corresponding extension file when that specific information is actually needed.

The key difference from cramming everything into one document is when context gets consumed. If every detail is written into a single main file, all of it consumes context space once loaded, regardless of whether the current task actually needs it. Progressive disclosure means extension files consume zero tokens until they're actually read — only the main file's concise overview enters the context up front, and the corresponding file only gets read on demand when detail is genuinely needed.

Why is Progressive Disclosure needed, and what problem does it solve?

The Context Window is a shared resource — a Skill's content has to share the same limited space with the System Prompt, conversation history, other Skills' metadata, and the user's actual request. If every Skill crams its full detail (API reference, extensive examples, advanced feature documentation) into the main file, situations where a user might trigger multiple Skills at once, or where a single Skill's content is simply large, quickly exhaust the context space, squeezing out room that should actually go toward handling the current task.

Progressive disclosure solves exactly this resource-allocation problem: it separates "content existing" from "content consuming context." A Skill can bundle extremely complete, thorough reference material, and as long as it isn't read, none of that material consumes any tokens. This means the author doesn't need to trade off between "is the content complete enough" and "will this consume too much context" — both can be satisfied at once, because completeness is handled by the extension files and conciseness is handled by the main file.

How does Progressive Disclosure actually work, and what organizational patterns are common?

The most basic mechanism: Claude only preloads the name and description (metadata) of every Skill at the start; the full SKILL.md content is only read once that particular Skill is judged relevant to the current task, and other extension files SKILL.md references are only read separately once Claude genuinely needs that piece of information. This mechanism relies on Claude, operating in an execution environment with filesystem access, reading files on demand using something like command-line tools.

Three organizational patterns are common. The first is "high-level guide plus references": the main file gives a quick-start approach, with advanced features or a full API reference each split into their own extension files. The second is "organized by domain," fitting a Skill that spans multiple topics — building separate reference files for finance, sales, and product, for instance, so a user asking a sales question only ever triggers reading the sales-related file, without also pulling in finance or product content. The third is "conditional detail," where the main file gives the basic approach first, only linking to a corresponding extension file when the user's need genuinely touches an advanced scenario (tracking revisions, handling a complex format). Across all three, one shared practical recommendation applies: keep extension-file references just one level deep directly from the main file — don't let an extension file link to yet another, deeper file — because when Claude reads a reference nested too deeply, it may preview only part of the content, ending up with incomplete information.

What does Progressive Disclosure actually mean for me, and how do I decide what goes in the main file versus an extension file when writing a Skill?

A simple criterion: if a piece of content is basic usage that gets used almost every time this Skill triggers, it belongs in the main file. If it's an advanced feature, a full reference, or extensive examples that only apply in a specific situation, split it into its own extension file and leave a single line plus a link pointing to it in the main file. In practice, official guidance recommends keeping the main file's body under about 500 lines — once you're approaching that length, that's the signal to consider splitting some content out.

Another practical test: ask yourself, "if this task doesn't need a particular piece of content at all, is there a way for that content to never get loaded?" If the answer is "no, because it's written together with the main file," that content is worth splitting out. If it's already a separate file that only gets read when needed, that part is already achieving what progressive disclosure is meant to do. For longer extension files (over a hundred lines), adding a table of contents at the top lets Claude grasp the file's full scope even if it only previews part of it.