Progressive disclosure for agent skills

The three levels

This is the model in the Agent Skills specification. The practical rule: put at each level only what is needed to decide whether to go to the next one.

A refactor, with file trees

Start with a skill that keeps a 120-row error table in SKILL.md. Made up for this page; token counts are the scanner's estimate.

api-errors/
└── SKILL.md  (6,580 tokens)

1. Cut the table out of SKILL.md and paste it into error-codes.md.
2. Replace it with one line in the workflow: 'Open error-codes.md and look up the code for that area and kind.'
3. Keep the workflow, the rules and one worked example in SKILL.md. Those are what the agent needs every time.
4. Rescan. The orphan-file and missing-reference checks tell you if a pointer is wrong.

api-errors/
├── SKILL.md  (259 tokens)
└── error-codes.md  (6,329 tokens)

A skill that is split well

A small skill needs only one reference file. This made-up sample has a 549-token body and a short examples file that the body points to.

changelog-writer/
├── SKILL.md  (637 tokens)
└── examples.md  (112 tokens)

For a real one, this is the folder of the ProSkills Skill Author skill: a body that carries the workflow, and one reference file for the detail. File names and sizes only.

skill-author/
├── CHANGELOG.md  (36 tokens)
├── SKILL.md  (2,005 tokens)
└── spec-and-antipatterns.md  (1,926 tokens)

Checklist

1. Description is 150 to 700 characters and starts with the trigger.
2. SKILL.md body is under 500 lines and 5,000 tokens.
3. Any table or example block over about 40 lines lives in its own file.
4. Every reference file is named in SKILL.md with a line on when to open it.
5. References sit one level below SKILL.md and do not link to each other.
6. Long reference files open with a heading or a contents list.
7. Scripts are named in SKILL.md with what they do and when they run.

These map to scanner rules: eff/body-tokens, eff/body-lines, eff/orphan-file, eff/nested-refs and eff/reference-toc. For the cost side, see reduce skill token usage.

Sources

• Agent Skills specification: progressive disclosure and file references
• Claude Code: skills

Questions

What is progressive disclosure in agent skills?

Loading a skill in stages. The agent always sees the name and description, reads the SKILL.md body when the skill triggers, and opens other files only when the task needs them. Detail costs nothing until it is used.

How deep should reference files go?

One level. SKILL.md points to a reference file, and that file does not point to another. Deep chains make an agent read partial files and miss things.

How does the agent know to open a reference file?

Because SKILL.md says so. Name each file and say when to open it, for example 'for the full error table, read error-codes.md'. A file SKILL.md never mentions is not read; the scanner flags it as an orphan.

When should I not split a skill?

When the whole thing is short. A 60-line skill in one file is easier to review and costs little. Split when a table or example block grows past roughly 40 lines or the body nears 5,000 tokens.

Keep reading

• Skill ScannerScore any skill in your browser. Nothing is uploaded.
• SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
• Reduce skill token usageWhat a skill costs in context, a token estimator, and a trim you can copy.
• How to write a Claude skillSeven steps, a weak and a strong description, scored side by side.
• All guidesEvery guide, grouped by what you are trying to do.