You have written the perfect skill. Every edge case, every gotcha, every "if the file already exists, do this instead" is in the SKILL.md. The procedure is airtight. And the agent still botches the task the same way it did before you wrote any of it.
The reflex explanation is that the model didn't read carefully. The more useful explanation, now that someone has measured it, is that the way you packaged the procedure changed whether the agent engaged with it at all — and that the layout of a skill is a lever independent of its content.
The same knowledge, two shapes#
An Agent Skill is just a directory: a SKILL.md with YAML frontmatter (a name and a description), plus optional scripts/, references/, and assets/. (If you're still deciding whether a skill is even the right container versus a subagent or a raw tool, that's a separate question; here we assume you've committed to a skill and are asking how to lay it out.) The design principle Anthropic built it around is progressive disclosure — the model loads information in tiers. At startup it holds only each skill's name and description. If a skill looks relevant, it reads the full SKILL.md. Only if a particular branch applies does it open a referenced file. Anthropic's own numbers make the economy vivid: the median skill costs ~80 tokens to be aware of, and all 17 of their example skills together announce themselves for ~1,700 tokens — less than a single activated skill's body.
So the standard case for progressive disclosure is a budget argument: don't spend 10,000 words of context on a skill when a 200-word slice is what this task needs. True, and enough on its own. But it quietly assumes the only thing at stake is tokens — that a flat file and a layered file teach the model the same lesson, just at different prices.
That assumption is what a new study set out to test.
What SkillJuror actually varied#
SkillJuror is a benchmark harness built to isolate organization from knowledge. It takes a skill, produces semantically controlled variants that carry the identical task knowledge but differ in how it's laid out, and runs matched multi-trial evaluations against a normalized flat baseline. The knowledge is held fixed by construction. The only thing moving is the shape.
On an 82-task SkillsBench, the progressively-disclosed layout didn't just cost fewer tokens. It changed the agent's behavior:
Distinct skill resources touched per run rose from 1.18 to 3.85. Effective uptake events — the agent actually pulling a resource in and using it — rose from 1.33 to 3.92.
That is close to a 3x increase in how much of your own material the agent reaches for, driven entirely by moving the material behind a lean root instead of dumping it in one file. And it converted into outcomes: 17 additional verifier-passing trials out of 410 matched runs, a +4.1% improvement over the flat baseline.
The non-obvious part#
Read those two numbers together and the causal story inverts the usual pitch. The flat file's problem was never only that it wasted context. **The flat file made the agent engage less with the procedure.** Everything was present, so nothing was reached for; the wall of text got skimmed as one undifferentiated block, and the specific branch that mattered never got treated as a decision the agent had to make. Breaking the skill into a root that says "for form-filling, read forms.md" turns a passive dump into an active retrieval — and the act of retrieving is also the act of attending.
Progressive disclosure, in other words, is doing two jobs that people conflate into one. It saves tokens, yes. But it is also a behavioral nudge: it converts "here is everything, good luck" into a sequence of small "do you need this? then go get it" prompts, and agents follow those prompts. Same knowledge, different packaging, measurably different action. This is context engineering at the level of a single file — you're not choosing what the agent knows, you're choosing what it has to reach for.
That reframes a piece of Anthropic's own authoring guidance — keep the SKILL.md body under ~500 lines and split the rest into referenced files. It reads like a style rule about brevity. It isn't. The split isn't there to make the file shorter; it's there to keep the always-loaded root lean while forcing the details to be fetched on purpose. A 480-line flat file that squeaks under the limit but inlines three mutually-exclusive branches has satisfied the letter and missed the point.
What to actually do#
- Root file = a router, not a manual. The
SKILL.mdbody should orient and dispatch: what this skill is for, and which resource to open for which branch. If a section only applies down one path, it belongs behind that path, not in the trunk. - Split on mutual exclusivity, not on length. Two branches that never fire together are the highest-value split — you keep both out of context until one is chosen, and you turn "which branch" into a decision the agent commits to.
- Push determinism into scripts. Where a step has a right answer — validation, parsing, sorting — bundle a script. Only its output enters context, and you sidestep the model reasoning through something a function already knows.
- Don't over-read the +4.1%. It is a real, controlled gain, but a modest one, and it comes with a cost the study also surfaces: touching 3x more resources means more file reads and more turns. On a latency-sensitive path, more uptake is not automatically better. Measure your own skill both ways rather than assuming the layered version wins.
The headline isn't "restructure everything." It's narrower and more durable: the layout of a skill is not cosmetic. You can hand an agent exactly the right knowledge and still lose, because you handed it in a shape that invited a skim. Package the procedure so the agent has to reach — and it will.
