What is progressive disclosure in agent skills?

Progressive disclosure means an agent loads a skill in stages instead of all at once. At startup it sees only each skill's name and description, about 100 tokens per skill in Anthropic's figures. It reads the full SKILL.md when the skill is used, and opens reference files or runs scripts only when the task needs them. Claude Code, Codex and Cursor all work this way.

How are real skills split into those stages?

Use This Skill lists every skill folder it finds in 48 public GitHub repositories. On November 2, 2026, we read the folder of each of the 2,058 skills in the November 1 crawl (data/skills.json) and counted how it is laid out. The safety results come from the November 1 scan (data/scan.json).

Folder layout read on November 2, 2026 from each repository's default branch, at the path recorded in the November 1, 2026 crawl. Median SKILL.md: 92 lines across all 2,058; 150 lines outside ComposioHQ/awesome-claude-skills, whose 864 skills come from one short template.

Three things stand out.

• Most skills never use the third stage. 1,134 of 2,058 are a single SKILL.md, so the whole skill loads at once when it is used. That works for a short skill. The median single-file SKILL.md is 92 lines, or 190 outside the template repository.
• Where there are reference files, they are usually the larger part. In 480 of the 847 skills with extra Markdown or text files, those files together are larger than SKILL.md. In the ui-styling skill, for example, SKILL.md is 10,943 characters, while the folder held 207,522 characters of Markdown and text at the commit its proof used. Progressive disclosure is what keeps that bulk out of the conversation until it is needed.
• Most SKILL.md files point to their files by name. Of the 871 skills with supporting files, SKILL.md names every one of them in 655, some of them in 196, and none of them in 20.

What loads at each stage?

Anthropic's Agent Skills overview describes three levels. Claude Code, Codex and Cursor document the same idea in their own terms.

Checked on each product's official documentation on November 2, 2026; links in the sources below.

In Claude Code, the rendered SKILL.md "enters the conversation as a single message and stays there across later turns," and Claude Code does not re-read the file on later turns. The documentation's example folder lists a helper script as "executed, not loaded."

How do Claude Code, Codex and Cursor handle it?

Codex's documentation notes that its budget applies only to the initial list; reading a full SKILL.md after selection is not counted against it. For what the stage 1 budget means when you install many skills, see how many skills Claude Code can load at once.

Why does it matter how a skill is laid out?

Because the layout decides what the agent pays for, and when.

A single-file skill costs its whole text the moment it is used. A skill that puts its rules in SKILL.md and its long tables, API notes and examples in references/ costs only the rules, plus whichever reference file the task calls for. A script is cheaper still: the agent runs it and reads the result, so a long validator costs only the lines it prints, not its code, and not the tokens the agent would spend writing an equivalent script itself.

Our proofs show the cost of skipping the stages. Each proof loads the skill's whole folder in one call, with no tools, which is the opposite of progressive disclosure. In the October 24, 2026 proof of ui-styling, that added 44,105 input tokens per run (data/proofs.json), because the folder was loaded up to the proof script's 120,000-character cap. In Claude Code, the same skill would cost its description on every turn, its 10,943-character SKILL.md once used, and its reference files only if Claude opened them. The methodology page explains why proofs load the whole folder.

How do I write a skill that uses progressive disclosure?

1. Make the description carry stage 1. It is the only part the agent sees before it decides. Say what the skill does and when to use it, early; how to write a SKILL.md description shows what 2,056 real descriptions do.
2. Keep SKILL.md to the steps and rules. Claude Code's documentation says to keep it under 500 lines; 2,037 of the 2,058 skills we counted already do.
3. Move bulk into references/. One topic per file, so the agent opens only the one it needs.
4. Name every file in SKILL.md, with when to open it. Claude Code's documentation gives the pattern: "For complete API details, see reference.md." Twenty skills in our count name none of their supporting files.
5. Say whether to run or read a script. "Run scripts/validate.py" keeps the code out of context; "see scripts/validate.py" loads it.
6. Put the rules that must hold first. After compaction, Claude Code can keep only the start of an invoked skill.

Does progressive disclosure make a skill safer to install?

No. It changes what the agent reads, not what the folder contains, and the files that load last are the ones people read least. In the November 1, 2026 scan, 73 skills came back as review or flagged, and in 36 of them every finding sat in a file other than SKILL.md: a reference file, a script or an install note. Skills that ship scripts were more likely to need a look: 35 of the 246 with script files were review or flagged, against 38 of the 1,812 without.

So read the whole folder, not just SKILL.md, before you install. The free skill check scans every text file in a skill folder for nine risky patterns and shows the file and line of each finding. For what the flagged skills in the directory turned out to contain, see are agent skills safe?.

How we counted

The skill list and paths come from data/skills.json (crawl of November 1, 2026: 2,058 skills, 48 repositories). On November 2, 2026, each repository was cloned from its default branch and each skill folder walked, skipping .git and node_modules. Supporting files are .md, .mdx and .txt files other than SKILL.md, and script files (.py, .sh, .bash, .zsh, .ps1, .js, .mjs, .cjs, .ts, .rb, .go, .rs); license, README, NOTICE and CHANGELOG files are not counted. A file counts as named when its path or file name appears in SKILL.md, ignoring case. Sizes compare the bytes of the supporting text files with SKILL.md. Scan results come from data/scan.json (November 1, 2026), which reads every text file in each folder; the folder layout was read a day later, so a skill changed in between could differ slightly.