Progressive Disclosure Is Mostly Aspirational

"Keep SKILL.md lean and push detail into references/" is the most repeated advice in the ecosystem. The corpus says most skills never got the second half.

Every SKILL.md in the directory, scanned for references to the standard progressive-disclosure folders:

Half the corpus points at a references directory. Less than a quarter ships scripts. Four percent ships templates or media assets.

Why the pattern is harder than it sounds

Progressive disclosure is easy to describe and expensive to do. It requires:

1. Deciding what belongs where. The default is to keep writing into the file you are already editing. Splitting requires a judgment about what loads on every activation versus what loads on demand.
2. Maintaining the links. A references/ directory only helps if the paths resolve. We found skills referencing files they never shipped; that is a worse failure than a long file, because the agent follows a dead pointer.
3. Shipping assets. The 4.2% figure is the honest one: images, templates, and fonts are heavy, and many authors simply paste an example into the skill instead.

What the scores say

Skills that reference references/ average 8.67 versus 8.19 for those that do not — a 0.48-point gap. Skills referencing assets/ average 8.94 versus 8.43 — a 0.51-point gap.

Both gaps are close to our evaluator's own noise floor (re-runs move scores by up to a point), so I would not quote them as proof that splitting files improves quality. What they do show is that the skills with the most deliberate packaging are also the ones that score at the top — which is largely the same statement.

The cheap version

If you are not going to ship a references directory, there is a halfway measure that costs ten minutes:

• Move the long examples out. Anything over ~40 lines that is illustrative rather than operational belongs in a second file.
• Keep the workflow in the main file. The steps must load every time.
• Fix your paths before publishing. An agent that follows a broken reference is worse off than one that never had the file.

The 53.5% who already point at references/ are the majority. The remaining 46.5% are leaving the single most recommended structural improvement on the table — and the 75% who ship no scripts at all are trusting the agent to improvise the executable part.