Progressive disclosure in skills: one level, and stop

Everyone writing SKILL.md files has absorbed the same folklore. Keep the top file thin. Push detail into reference files. Let the agent walk the tree as needed. More layers, more context efficiency.

A controlled study submitted July 20 tested that across InfiniteBench, three agent harnesses, and three model families, comparing raw-document navigation against skill packs at varying disclosure depths against a classical hybrid retriever. One level of progressive disclosure held up well and won as the corpus scaled to many books. A second routing level never helped. Sometimes it made accuracy worse.

And on single documents with a strong harness, the gain from progressive disclosure was near zero.

The line I've been repeating since I read it: progressive disclosure buys context, not intelligence. It's a compression technique for when the corpus outgrows what the agent can read directly. That's the whole value proposition. It does not make the agent reason better about what it eventually reads, and every routing hop you add is another place for the agent to pick the wrong branch and never recover.

I went back through my own skill files after this. I had a three-level structure in one of them: entry file pointing to a category index pointing to specifics. That middle layer was pure ceremony. I'd built it because it felt organized, which is a design instinct misapplied to a retrieval problem. Organizing for a human reader who can scan and backtrack is different from organizing for an agent that commits to a branch and keeps going.

The timing matters because skills stopped being a Claude Code concept this month. DeepChat at 6,155 stars added agent-skills as a top-level topic. ECC ships skills across Claude Code, Codex, Opencode and Cursor. Codex 0.145.0 added /import for Cursor and Claude Code settings including skills and MCP servers. The primitive is portable now, which means bad structural habits port too.

Concrete action: audit your skill packs for depth. If any reference file's only job is to point at other reference files, delete it and flatten. If your corpus fits in what the agent can read directly, skip progressive disclosure entirely and just give it the documents. You're paying routing cost for nothing.

The broader thing I like about this paper is that it tested against a classical hybrid retriever as a baseline. Half the agent-architecture discourse forgets that BM25 plus a dense retriever is still very good, and that "let the agent navigate" is a design choice that needs to beat retrieval, not just work.