Agent Skills and Progressive Disclosure

An agent that knows how to fill in your company's expense forms, reconcile a general ledger, write a court filing and generate a slide deck has a problem before it reads a single word of the user's request: those four procedures, written out properly, are tens of thousands of tokens of system prompt. Put all of them in the window and every request pays for all four. Put none of them in and the agent is a generalist that guesses at your conventions.

Agent Skills, introduced by Anthropic on 16 October 2025, resolve this by making capability a filesystem rather than a prompt. A skill is a directory containing a SKILL.md file plus whatever scripts, templates and reference documents the procedure needs. The agent loads the pieces in layers, and only the layer it needs.

The three levels

The mechanism is progressive disclosure, and it has a precise shape (Anthropic, Equipping agents for the real world with Agent Skills, 2025):

Level 1, always resident. At startup the agent pre-loads only the name and description from the YAML frontmatter of every installed skill into its system prompt. Those two fields are the entire cost of an uninstalled-but-available capability. A hundred skills at roughly twenty tokens of metadata each is two thousand tokens, which is the price of an index, not a library.

Level 2, loaded on relevance. If the agent judges a skill relevant to the current task, it reads the full SKILL.md into context. This is the procedure itself: the steps, the conventions, the gotchas.

Level 3 and beyond, navigated on demand. SKILL.md can reference bundled files by name. A references/ directory with a 40-page style guide, a scripts/ directory with a deterministic validator. The agent reads or executes these only when the branch it is on calls for them, and a script it runs as a tool never enters the context window at all.

The load-bearing property is that the description field must be good. Level 1 is the only information the agent has when deciding whether to pay for level 2, so a description that says "helps with documents" is a skill that never fires, and one that says "use when the user asks to X, Y or Z" is a skill that fires correctly.

Why this is not just a prompt library

Two things separate skills from a folder of prompt snippets. First, composability: skills stack, so a task can pull in three of them and the agent assembles the combined procedure rather than choosing one template. Second, executable code. A skill can ship a script that the agent runs instead of reasoning through a deterministic transformation. Rotating a PDF, validating a schema, computing a checksum: these are things a model does unreliably and a twelve-line Python file does perfectly, and the skill format lets the procedure hand the work over.

That is the same trade as code execution as a tool interface, applied to instructions instead of tool definitions.

When it breaks

Description collision. Two skills whose descriptions overlap produce non-deterministic selection. The agent picks one, and which one is not stable across model versions. Disambiguation has to be written into the descriptions themselves.

Level 2 bloat. Nothing enforces a size limit on SKILL.md. A skill that grows to 8,000 tokens defeats the mechanism for every task that triggers it, and the failure is silent because the agent still works, just more expensively and with a fuller window. Keep the body a procedure and push detail down to level 3.

Retrieval is the model's judgement, not a ranked search. Skill selection is not embedding similarity with a threshold; it is the model deciding. That is more flexible and less auditable. There is no relevance score to log when it picks wrong.

Trust boundary. A skill is instructions plus code that the agent will execute. Installing one from an untrusted source is equivalent to running an untrusted program with the agent's credentials, which is why sandboxing and least privilege is a prerequisite, not a nice-to-have.