What Agent Skills Are, and Why Progressive Disclosure Changes the Math

Equipping an agent with expertise used to mean one thing: put it in the system prompt. Every convention, every report format, every "always do X before Y" got pasted into one ever-growing block of instructions that the model reads on every single call, whether the call needs it or not. That scales badly in the most literal way possible: the cost of knowing a hundred things is paid a hundred times over, on every turn, forever. Agent Skills are the fix, and the reason they work is a single mechanism worth understanding before anything else.

The mental model: onboarding a specialist, not memorizing a handbook#

A skill is a folder that packages one piece of procedural know-how for an agent to pull in only when a task calls for it. The framing that makes it click is onboarding a new hire. You do not hand a new teammate the entire company handbook to memorize on day one. You give them a short job description, and they pull the relevant procedure, template, or script off the shelf the moment a task needs it. A skill is that shelf: written once, consulted only when relevant, reusable by anyone (or any agent) who needs the same job done.

Concretely, a skill is a directory, not a snippet. At its simplest it is one file:

code-reviewer/
└── SKILL.md          # required: frontmatter (name, description) + a markdown body

At its richest it bundles the material the instructions point to:

pdf-processing/
├── SKILL.md          # entry point: what it is, when to use it, quick start
├── FORMS.md          # extra guidance, loaded only when filling a form
├── REFERENCE.md      # detailed API reference, loaded only when needed
└── scripts/
    └── fill_form.py  # a script the agent runs, not reads

The frontmatter has two fields that carry the whole design: a name, and a description that states both what the skill does and when to use it. That description is the entire matching surface, the only text the model sees before it decides whether to load the rest. Hold onto that, because it is the hinge of the mechanism.

Progressive disclosure: the whole trick#

Progressive disclosure is the single idea that makes skills work at all. Content enters the agent's context in three stages, each triggered by a different event, rather than all at once at startup:

Two mechanical details make the third stage effectively free no matter how much a skill bundles. The model reads only the file a task actually needs, so a skill can ship a dozen reference documents and an unrelated task loads none of them. And when the agent runs a bundled script, the script's source code never enters context, only its output does. That is what turns "no real limit on bundled content" from a slogan into a fact: a skill can carry a full API reference or a large dataset at zero standing cost, because nothing loads until a specific step asks for that specific thing.

If this feels abstract, notice it is the pattern the agent listing at the top of most agent sessions already runs on: one line of name-and-description per available capability, nothing more, until a task matches one and its full instructions get pulled in. Progressive disclosure is not a diagram in a doc. It is the mechanism the tools around you are already using.

Why this changes the math#

The payoff is easiest to see by putting a skill next to the system prompt holding the same knowledge:

The core move is that skills decouple three costs a system prompt smashes together: the cost of having expertise installed, the cost of using it, and the cost of the material it bundles. Only the first is paid on every call, and it is cheap. That decoupling is what buys you the three properties people actually want. Skills are composable, because each is triggered independently on its own description match, so a code-review skill and a deploy skill coexist without being merged into one mega-prompt. They are context-lean, because installing the tenth or hundredth skill does not grow the standing cost of the first. And they are portable, because the format is just a folder of markdown and scripts with no vendor API baked in.

That last property is not theoretical. Anthropic introduced skills and then published the format as an open standard, and it has since been implemented by a genuinely cross-vendor set of agent products well beyond Claude, from coding assistants to CLI agents, each reading the same SKILL.md shape. That breadth of independent adoption is the evidence for "portable," not a marketing claim you take on faith.

It is really just context engineering, shipped#

If you have thought about context engineering, none of this is new, which is a point in its favour. A skill is a productized instance of two levers you already know. It is selection: only the skill whose description matches the task ever has its body loaded, and the rest stay as unloaded metadata. And it is timing: the body and its files load just in time, on the step that needs them, not preloaded "just in case." A skill's name-and-description catalog is a compressed pointer to much larger content, and triggering it is the same just-in-time retrieval you would apply to files or memory. Skills just standardize that pattern into a distributable, versioned package instead of a one-off convention per project.

Gotchas, or what actually bites teams#

• The description is the whole ballgame, and it is easy to write badly. It is the only text matched against a task, so a description that states capability ("extracts PDF text") without a trigger ("use when the user mentions PDFs, forms, or extraction") quietly under-fires and the skill never loads.
• A fat SKILL.md body is a tax on every later turn. The body enters context on trigger and then stays for the session. Every paragraph the model did not need is paid again on every subsequent turn, so push anything not needed on every run into a reference file the body links to.
• "Install a hundred skills for free" has a ceiling in practice. The metadata is cheap but not zero, and the listing competes for a slice of the window. Past enough installed skills, some runtimes start trimming the least-used descriptions, and a skill silently stops being discoverable.
• Confusing a skill with new access. A skill is know-how, not connectivity. It cannot reach a system it has no client for; it only makes better use of access that already exists. Which layer does what is the subject of its own post.
• Trusting a folder you did not write. A skill runs code and injects instructions, so an installed skill is a dependency, not a document. That is the security post.

Where this goes next#

Once you see a skill as a unit of know-how, the obvious next question is how it relates to the other ways to extend an agent, tools, MCP, and subagents, which get conflated constantly. That is Skills vs MCP vs Tools vs Subagents. And because a skill carries executable code and injectable instructions, the one you should read before installing anyone else's is A Skill Is a Dependency That Runs Code.