Progressive Disclosure: How AI Agents Learn Without Drowning

Ask a senior associate at a law firm where the indemnification carve-outs live and she won't recite the clause from memory. She'll tell you which binder, which tab, which prior deal had the version everyone copies. That's the whole trick of expertise. Not holding the library in your head. Knowing the shelf.

AI agents have spent the last two years getting this backwards. The instinct, when an agent fumbles a task, is to feed it more. More instructions, more examples, the entire procedures manual stuffed into the prompt before it's even read the question. It works for a while. Then it doesn't.

The reason is dull and physical. A context window is finite, and attention degrades as it fills. Anthropic frames context as a finite, decaying resource: the more you cram in, the less reliably the model tracks any single piece of it. Pour the whole library onto the desk and the associate can't find the binder anymore. She's standing in paper.

So the real ceiling on a capable agent is context, not intelligence. The model is plenty smart. It's just drowning.

The directory that teaches

Anthropic's answer is the Agent Skill, and the idea is almost rude in its simplicity. A Skill is a directory. Inside sits a file called SKILL.md, and alongside it whatever the job needs: instructions, scripts, reference material. Bundle those up and a general-purpose agent becomes a specialist. The same model that was guessing at your invoice format an hour ago now handles it like it's done a thousand. Because, in a sense, it now can.

What makes this more than a folder of notes is how the agent reads it. It doesn't. Not all at once.

Three tiers, loaded on demand

Skills run on what Anthropic calls progressive disclosure, and it works in three levels.

The first level is metadata. Every Skill carries a name and a short description, and only that much gets preloaded into the system prompt. The cost is near zero. The agent walks into the room knowing a hundred Skills exist and roughly what each one is for, the way our associate knows the firm owns a tax-treaty binder without having opened it. She hasn't read a word of it. She knows it's there.

The second level is the SKILL.md body. This loads only once the agent judges the Skill relevant to what's actually in front of it. Someone asks about a cross-border deal, the tax-treaty Skill activates, and now the procedural detail flows into context. Not before. The instructions that would have been dead weight on every other task sit quiet until the one task that needs them.

The third level is the referenced files. The SKILL.md can point to deeper material, a long schema, an edge-case playbook, a worked example, and the agent pulls a given file only when that specific path comes up. You don't read the appendix to answer a question the chapter already covered.

Three tiers, each paying for itself only when summoned. The agent ends up with deep procedural knowledge and a context window that stays lean. It learned the building without memorizing every room.

Stop deriving what you can run

There's a fourth move that matters as much as the loading. A Skill can bundle executable scripts, and the agent runs them directly without reading them into context at all.

This sounds like a footnote. It isn't. Anthropic's example is sorting: if you need a list sorted, having the model reason its way through the ordering token by token is slow, expensive, and occasionally wrong. Running a sort function is instant, free of context cost, and right every time. Deterministic work belongs in code. Make the model re-derive it as prose and you're paying premium tokens to reinvent a calculator, badly.

The agent doesn't need to understand the script. It needs the answer. So it runs the thing and reads the result, the way the associate trusts the firm's deal-term calculator instead of doing the math on a legal pad.

Build it like an operator, not a hoarder

The design principles Anthropic lays out read like advice from someone who's watched a lot of bloated systems fail.

Find the agent's real gaps empirically. Don't guess at what it doesn't know, watch where it actually breaks, then write the Skill that fixes that. Split paths that rarely get used together into separate files, so a task that needs one never has to carry the other. Watch real usage and trim what nobody loads. And audit any Skill that came from a source you don't trust, because a directory that can ship executable scripts is a directory that can ship a problem.

It all rhymes with the same instinct. Keep the desk clear. Let the binders stay on the shelf until the question arrives that needs one.

The best expert in any building has always been the one who knows exactly where to look, not the one who memorized the most, and doesn't reach for the shelf until the moment the answer lives there.

Sources: Anthropic engineering guidance on Agent Skills (Skill as a directory with SKILL.md; three-level progressive disclosure of metadata, body, and referenced files; bundled executable scripts run without entering context, with the sorting example; design principles on finding gaps empirically, splitting rarely-co-used files, watching usage, and auditing untrusted Skills); Anthropic on effective context engineering (context as a finite, decaying resource and attention degrading as the window fills).