What agent skills are, and when they beat a prompt
An agent skill is a folder with a markdown file in it. That is the whole idea. The file is called SKILL.md, it starts with a few lines of YAML, and the rest is instructions written for an assistant rather than for a person.
The reason this is interesting has nothing to do with the format. It is that the instructions sit on disk instead of in your head, so you stop retyping them.
The problem skills actually solve
If you work with an assistant for any length of time, you develop a house style for repeated jobs. The order you check things in. The three mistakes you always have to correct. The output format you want. Right now most people hold that in a note somewhere and paste it in each time, or retype it from memory and get it slightly different every time.
A skill is that paste, stored once, loaded automatically when it is relevant.
That is a smaller claim than the word "skill" suggests, and it is worth being clear about, because the main failure mode is expecting a skill to give an assistant an ability it does not have. A skill cannot make a model able to read your DNS records. It can only tell it how to go about reading them, and which tool to use. The ability has to come from somewhere else.
What goes in the file
The minimum is two frontmatter fields and some prose:
---
name: email-deliverability
description: Diagnose why mail from a domain is being rejected or sent to spam. Use when a user reports bounced mail, messages landing in spam, or asks about SPF, DKIM, DMARC or MTA-STS.
---
# Email deliverability triage
Work through the records in this order. Do not guess a record's
contents: look it up.
1. Resolve the MX records. No MX means no inbound mail.
2. Check the SPF record. Count DNS lookups; more than ten is a failure.
3. Check DKIM for the selectors the sender actually uses.
4. Check DMARC last, because it depends on the two above.
name and description are the fields that matter. The body is ordinary markdown.
The description is doing more work than it looks. It is the only part of the skill that is loaded all the time, and it is what the assistant matches your request against when deciding whether this skill is relevant. So it has to say two things: what the skill does, and when to use it. Anthropic's own documentation is blunt about this, and a description that only covers the first half is the single most common reason a skill never fires.
Compare these two:
description: Helps with email.
description: Diagnose why mail from a domain is rejected or filtered as
spam. Use when a user reports bounced mail, messages landing in spam,
or asks about SPF, DKIM, DMARC or MTA-STS records.
The first will sit unused. The second has the words a real request contains.
How the loading works
Skills are built around loading as little as possible until it is needed. There are three levels, and the token costs are documented:
| Level | When it loads | Cost |
|---|---|---|
name and description | Always, at startup | About 100 tokens per skill |
The SKILL.md body | When the skill is triggered | Under 5k tokens |
| Bundled files | Only when referenced | Nothing until read |
That third level is the part worth designing around. A skill is a directory, not a single file, so you can keep the main instructions short and put the long material beside it:
email-deliverability/
SKILL.md main instructions
spf.md SPF syntax and the lookup limit
dmarc.md policy, alignment and reporting tags
check.sh a script that runs the lookups
The assistant reads SKILL.md, and only opens spf.md if the job turns out to involve SPF. Scripts are better still: when a script runs, only its output enters the context, never its code. So a skill can carry a great deal of reference material and cost almost nothing when that material is not relevant.
The practical rule is to keep SKILL.md to the decision making, and push anything that is lookup material into a file next to it.
Where they live
In Claude Code, skills are files on disk and need no upload. A skill in ~/.claude/skills/<name>/SKILL.md is yours everywhere. One in .claude/skills/<name>/SKILL.md lives in a repository, so it ships with the project and your colleagues get it when they clone.
The project location is the one most teams underuse. A skill checked into a repository is documentation that actually gets read, because the assistant reads it before touching the code.
On claude.ai, custom skills are uploaded as zip files, on the paid plans with code execution turned on. Through the API, you reference a skill by id alongside the code execution tool.
The thing to know before you write a network skill
Skills on the API run in a sandboxed container with no network access. That is a deliberate design decision and it catches people out.
It means a skill cannot be how an assistant reaches the live internet. If the job needs a real DNS answer, a real TLS handshake or a real HTTP response, the skill can only describe the method. Something else has to make the request, and that something is normally an MCP server.
This is why skills and MCP are complements rather than competitors, and why nearly every useful skill about live systems is really a pair: a skill that holds the judgement, and a server that holds the reach. We go through that split in when to use a skill and when to use an MCP server.
For the network half, toolhq runs an MCP server with eight read only checks, which is one command to add:
claude mcp add --transport http toolhq https://toolhq.io/api/mcp
Once an assistant can actually resolve a record, a skill that says "resolve the MX records first" becomes an instruction instead of a wish.
When not to write a skill
Three cases where a skill is the wrong reach:
A one off job. If you will do this once, just ask. Writing the skill costs more than the task.
Something that needs live data and nothing else. If the gap is purely access, you need a tool or an MCP server. A skill wrapped around a capability that does not exist produces confident, invented answers, which is worse than no answer.
A task with one correct output and no judgement. Hashing a string, converting a timestamp, validating JSON. A model is unreliable at these in a way that instructions do not fix. Use something exact instead, which is the argument in where an exact tool beats an AI model.
Skills earn their place on repeated work that involves judgement: an order of operations, known traps, a house format. That is a narrower target than the enthusiasm around them suggests, and hitting it squarely is more useful than writing twenty skills that never fire.
Next
If you want to write one, how to write your first agent skill goes through a real one line by line. If you would rather see what is worth building, agent skills by type of work is a list organised by job rather than by technology.