Insight · September 24, 2026
Teach it once.
Not every time.
A skill is a folder an agent reads only when the work calls for it. Anthropic shipped the format in October 2025 and opened it as a standard two months later.
01 · The shift
You keep re-explaining the same thing.
Every new conversation with an agent starts cold. You paste the same house rules, the same file layout, the same way you like commits written, and you do it again tomorrow. The model is capable. It just does not remember how you work.
Agent Skills close that gap. Anthropic published the format on October 16, 2025, then released it as an open standard for cross platform portability on December 18. A skill is the procedure written down once, in a form the agent loads on its own when the moment fits.
02 · What it is
A folder with a file that tells the agent what to do.
At its core a skill is a directory with one required file, SKILL.md. The top of that file is a short block of metadata, a name and a description in plain text. Below it is the body: the instructions, written in Markdown, the way you would brief a new hire on their first day.
Anthropic uses that exact comparison. Building a skill, the engineering team wrote, is like putting together an onboarding guide for a new hire. The folder can hold more than the one file. It can carry reference documents the agent reads when it needs a detail, and scripts the agent runs instead of writing the code from scratch.
Each type of content plays to a different strength. Instructions give flexible guidance the agent can adapt. Scripts give deterministic operations that run the same way every time. Reference files give facts the agent looks up rather than remembers. One folder, three kinds of help.
Nothing about it is proprietary. It is structured text and ordinary files, no APIs and no special format. That is the whole point. Any agent that understands the convention can read the same skill.
The one line to keep
“A prompt tells the agent what to do once. A skill teaches it what to do every time.”
03 · How it loads
The agent reads in layers, not all at once.
01
Name and description
Loaded at startup and kept in the system prompt, roughly one hundred tokens per skill. It is how the agent decides whether a skill is even relevant. Until then it costs almost nothing.
02
The instructions
Read only when your request matches the description. The agent opens SKILL.md, pulls the body into context, and follows it. Most skills keep this under a few thousand tokens.
03
The resources
Reference files and scripts sit on the filesystem until a step actually calls for them. A skill can bundle a large manual and pay nothing for the pages it never opens.
04 · Why the shape matters
Load a hundred skills and pay for the one you use.
Because only names and descriptions sit in context by default, an agent can carry a large library of skills without slowing down or crowding out the actual work. It reaches for the right one the way you reach for the right chapter, and leaves the rest on the shelf.
Skills also compose. A task that needs three procedures can pull all three, each written and tested on its own. And because the format is portable, the same skill runs across Claude.ai, Claude Code, the Agent SDK, and the API. Write the procedure once, use it wherever the agent runs.
The bundled scripts are where the design gets quietly clever. When the agent runs a script, only the output enters context, never the code itself. A validation step that would cost hundreds of tokens to generate on the fly costs almost nothing to run and read the result. Deterministic work stays cheap and exact, and the agent spends its attention on judgment instead.
05 · What one looks like
A skill is smaller than you expect.
Here is a complete skill. A name and a description at the top, then the steps. The description is the line that matters. It is what the agent checks your request against, so it has to say both what the skill does and when to use it.
--- name: commit-style description: Write git commit messages in the house format. Use whenever staging or committing changes in this repo. --- ## Instructions Write the subject in the imperative, under fifty characters. Explain what changed and why in the body, never how. Reference the issue number on the final line.
One file · loaded only when the work matches the description
06 · The operator view
Skills are the reusable unit of what an agent can do.
In Claude Code a skill is a folder on disk. Drop it in your home directory and it follows you across every project. Commit it to a repository under a skills folder and the whole team gets it the moment they clone. The agent finds it by its description, or you call it directly by name.
That is the shift worth seeing. Capability stops living in the heads of the few people who know the right prompt, and starts living in version control next to the code. A skill is reviewed, versioned, and shared the way a function is. It can be improved once and the improvement reaches everyone.
The prompt was a keystroke. The skill is an asset.
07 · The caution
A skill is instructions and code, so treat it like code.
A skill can tell the agent to run scripts and use tools. That is its power and its risk. Anthropic is blunt about it: use skills only from sources you trust, and audit anything from outside before you run it. A skill that fetches from an external address can carry instructions you never wrote.
And not every job needs one. A single answer is still faster as a plain prompt. Skills earn their setup on the procedures you run over and over, the ones where writing it down once and getting it right forever is worth the afternoon it takes.
Closing
Stop briefing the agent. Start handing it the manual.
Pick one procedure you explain to the agent every week. Write it down as a skill, once, with the finish line spelled out. The next time it runs the work without being told how, you will start moving every procedure you own into the same shape.
Anthropic · Equipping agents for the real world with Agent Skills, October 16, 2025 · Agent Skills documentation, platform.claude.com · open standard published December 18, 2025
Share this perspective
More insights
Adjacent perspectives.
Bttr. Field Brief
The brief Bttr. writes for senior buyers.
Monthly. One signal worth your time on Brand Operating Systems, AI search visibility, and the infrastructure buildout. No filler.