Understand progressive disclosure

An agent may have dozens of skills installed. If it loaded every SKILL.md at startup, most of the context window would be full of instructions for tasks it isn’t doing. Unrelated rules would compete for attention.

Agent Skills solve this with progressive disclosure: show a little first, load more only when needed.

The three levels

At the first level the agent sees only the skill’s name and description. That’s a couple of lines per skill, cheap enough to keep in context for every installed skill.

If the current task matches, the agent loads the full SKILL.md. That’s the second level: the procedure and the gotchas that matter on every run.

Scripts, references, and assets are the third level. They stay on disk until an instruction in SKILL.md tells the agent to open or run one.

What this means for how you write

Each level has a job.

The description must carry enough signal for discovery on its own. We’ll spend a whole lesson on it.

SKILL.md must contain what the agent needs every time. For our release-readiness skill that’s the workflow, the stop conditions, and the evidence rules.

Everything conditional moves out. The detailed matrix of checks per ecosystem goes in references/checks.md. The report template goes in assets/report-template.md. The deterministic validator goes in scripts/validate-report.mjs.

The folder

The portable layout is small:

release-readiness/
├── SKILL.md
├── scripts/
├── references/
└── assets/

Only SKILL.md is required. The other three folders are conventions the specification recognizes. Don’t create them empty to make the skill look complete. Every file has to earn its context and its maintenance cost.

A quick test for each file

Sketch the final tree for your skill. Next to each file write when the agent should load or run it.

If your answer is “always”, that content belongs in SKILL.md, not in a reference. If your answer is “I’m not sure when”, delete the file. A skill with three files that all get used beats one with twelve files where half are never opened.

I like to write the load condition as the first line of the reference itself. references/npm.md starts with “Read this when the repository has a package.json with a publish script.” The agent sees the condition, and so does the next person who maintains the skill.