Agent skills.
A skill gives an agent no new ability — the model could already write the report, it just did not know your house style for one. What a skill actually buys is conditional loading: a folder of instructions the agent reads only when the task matches, so a library of two hundred procedures costs almost nothing until one is needed. Which means the hard part is not writing the instructions. It is writing the one-sentence description that decides whether they ever get read.
A folder, a Markdown file, and three loading tiers.
A skill is a directory containing a SKILL.md: YAML frontmatter followed by prose instructions, optionally next to scripts, templates and reference documents the instructions point at. Only two frontmatter fields are required — name and description — with license, allowed-tools, metadata and compatibility available and everything unrecognised ignored, which is what makes the same folder portable across runtimes. Anthropic published the format as an open standard in December 2025; through 2026 it was picked up across coding agents, CLIs and IDE assistants.
The mechanic that matters is progressive disclosure, and it is a three-tier read:
- Always resident — each installed skill's
nameanddescription, on the order of a hundred tokens apiece. This is the only cost you pay for a skill you never use. - On match — the full
SKILL.mdbody, which is why the format's own guidance keeps it under roughly five thousand tokens. It enters the context when the agent decides the task is this one. - On demand — bundled reference files, read like any other file, only if the body sends the agent to them. A 200-page style guide costs nothing until a sentence of the skill says to go open it.
Compare the alternative. Instructions in the system prompt are resident on every request of every conversation forever; that is the budget a skill is designed to get off. Two hundred skills at a hundred tokens is twenty thousand tokens of index — real, but bounded — against two hundred procedures inlined, which no context window survives.
The description is a retrieval index, and that is where skills fail.
Because the body loads only on a match, the description is not documentation — it is the query the agent matches a task against. A skill with excellent instructions and a vague description is dead weight: it sits in context announcing itself and never fires. This inverts where authors spend their effort, which is almost always on the body.
- State what it does and when to use it. "Formats reports" loses to "Formats quarterly revenue reports into the finance team's board-deck template; use whenever asked for a board or investor-facing revenue summary." The trigger conditions are the load-bearing half.
- Overlap is the scaling limit. Two skills whose descriptions both plausibly match "clean up this spreadsheet" is a coin flip, and the loser's absence is silent — no error, just a worse answer. A library stops scaling at the point where descriptions collide, not at a token count.
- Name it for the trigger, not the mechanism. The name must be lowercase-hyphenated, match its folder, and cap at 64 characters; within that, it is another retrieval signal, so spend it on the situation rather than the implementation.
The practical consequence: debug a skill that "doesn't work" by first checking whether it loaded at all. Most reported skill failures are retrieval failures wearing an instruction failure's clothes.
Skill, tool, or MCP server — the placement rule.
These get conflated constantly, and the conflation is expensive in both directions. The distinction is clean: a tool or an MCP server adds capability the model does not otherwise have — a connection to a system, a credential, an effect in the world. A skill adds procedure the model could already execute but does not know your version of.
- Needs to reach something? That is a tool. Prose cannot query your warehouse; no skill will give an agent database credentials it lacks.
- Needs to do something a particular way? That is a skill. Wrapping a procedure in an MCP server buys you nothing and costs you a tool definition resident in every request, forever — the opposite of the trade skills exist to make. See tool design for agents.
- Applies to everything, always? That belongs in the system prompt. Skills earn their keep on procedures that apply sometimes; a skill that matches every task is a system prompt paying an indirection tax.
Most useful skills contain both halves anyway — instructions that tell the agent which tools to call, in which order, and how to interpret what comes back. That is context engineering with a filesystem, which is the honest description of the whole idea.
What it costs you: a skill is executable text.
A skill is instructions the agent reads and follows, loaded from a file, often from a shared repository or a marketplace. Everything that can write a SKILL.md into a location your agent reads can rewrite what your agent does — and unlike a tool call, there is no approval prompt on "read the instructions." A skill pulled from a public directory is closer to a dependency than to a document.
- Review skills like code. Diff them on update, pin what you install, and be specific about which directories the agent is allowed to load skills from. The failure is not exotic: it is the ordinary prompt injection problem with a friendlier file extension.
- Scope the blast radius.
allowed-toolsexists so a formatting skill cannot reach the send-email tool. Use it; a skill that can invoke anything the agent can invoke is an unnecessary widening. - They rot. A skill encodes a process, and processes change. An unversioned skill describing last year's approval workflow is worse than no skill, because the agent follows it confidently.
Write the description first, and write it as the sentence that must beat every other skill you own. Then keep the body under a page and push everything long into reference files the body links to. A skill that loads at the right moment and says four specific things will outperform a beautifully complete one that never fires — and the second failure mode is invisible, so you will not find it by reading your skills.
Related: context engineering for the budget this is all in service of, prompt caching for why load order matters, and agent supply-chain security for what installing someone else's instructions actually admits.