Progressive Disclosure — The Three-Level System That Lets Skills Scale

The single architectural decision that makes skills work where every previous approach failed: progressive disclosure. Understanding it explains why you can install 50 skills without performance loss.

If skills were just "save your prompts to files", they would not have spread the way they did. The genuinely innovative part of the SKILL.md design is progressive disclosure — a three-level loading system that lets agents have access to enormous capability libraries without paying the context-window cost on every conversation.

Level 1: Metadata (Always Loaded)

When the AI agent starts up, it scans every installed skill and reads only the YAML frontmatter — typically the name and description fields, around 30 to 100 tokens per skill. This metadata goes into a small section of the system prompt: "Here are the skills available and roughly when each one applies."

The agent now knows what skills exist and the rough domain of each. It does not know the detailed instructions. It does not know which scripts each skill bundles. It has just enough information to recognise when a skill is relevant — and not enough to be slowed down by the existence of skills it does not need right now.

Level 2: Instructions (Loaded When Triggered)

When you send a request, the agent compares your message against every skill description. If your message matches one (or several) descriptions, the agent reads the full Markdown body of those specific skills and adds the instructions to its working context.

This is where the scaling magic happens. If your request does not match any skill, no skill body loads — only the small metadata strings stay in context. If your request matches one skill, only that skill body loads. The agent never reads instructions for skills it does not need.

The specification recommends keeping each skill body under 5,000 tokens. For most well-designed skills, the body is far smaller — a few hundred tokens of clear instructions and examples. The agent loads exactly what is needed for the current task and nothing more.

Level 3: Resources (Loaded On Demand)

For skills with extensive content — detailed error code references, comprehensive examples, long-form documentation — the SKILL.md body itself stays focused and references separate files. REFERENCE.md, EXAMPLES.md, TROUBLESHOOTING.md and other companion files are loaded only when the skill body explicitly references them.

Scripts are similar. A skill that bundles Python or Bash scripts loads those scripts only when the agent decides to execute them. The script code never enters the agent context window — it runs as a separate process.

Why This Architecture Wins

The cumulative effect: you can install 50 specialised skills covering every aspect of your work. Each adds 30-100 tokens to the system prompt at startup — a total of perhaps 3,000-5,000 tokens for the entire library. When you ask a question, perhaps one skill loads its full body (a few hundred to a few thousand tokens). Total overhead for the system: under 10,000 tokens regardless of library size.

Compare this to loading all 50 skills as custom prompts: 50 skills × 3,000 tokens average = 150,000 tokens of overhead on every conversation. The context window is exhausted before you have asked anything. This is why progressive disclosure is not a clever feature — it is the architectural decision that makes the entire approach viable.