How to write an AI Skill your team will actually use
Most Skills fail at discovery, not quality. They are never triggered because the description is vague. Here is how to write one that gets picked up and used.
Most Skills that fail do not fail because the instructions were bad. They fail because they were never loaded in the first place.
That is worth sitting with before writing one. A Skill is a folder containing a SKILL.md file of instructions, plus optional scripts and reference material, that an AI model pulls in when a task calls for it. The question of when it calls for it is decided by one sentence, and most people spend all their effort on the other thousand.
How the model actually sees your Skill
Skills load in three stages, and knowing the stages changes how you write.
| Level | When it loads | Cost | What it holds |
|---|---|---|---|
| Metadata | Always, at startup | About 100 tokens per Skill | The name and description |
| Instructions | When the Skill is triggered | Under 5k tokens | The SKILL.md body |
| Resources | Only when read | Nothing until accessed | Bundled files and scripts |
Two consequences follow immediately.
The first is that the description is doing all of the discovery work. At startup the model can see only names and descriptions, possibly across a hundred Skills, and it picks from that alone. Your careful instructions are invisible at the moment of selection.
The second is that bundled detail is close to free. Reference files cost nothing until read, and scripts can be executed without their code entering context at all. There is no reason to compress a full schema reference into prose. Put it in a file and link to it.
Write the description like it is the product
Anthropic's authoring guidance is specific here, and it is the highest-leverage part of the whole exercise.
Write in the third person. The description gets injected into the system prompt, and mixing points of view causes discovery problems.
Say what it does and when to use it. Both halves. The "when" is what makes matching possible.
Include the words people will actually use. If your team says "recs" and "breaks", those belong in the description alongside "reconciliation".
Weak, and effectively invisible:
description: Helps with reports
Strong:
description: Produces the monthly supplier reconciliation from the ledger export and flags unmatched lines over £5,000. Use when reconciling supplier accounts, investigating unmatched payments, or when someone mentions recs, breaks or month-end close.
The name matters less but still helps. Lowercase letters, numbers and hyphens, maximum 64 characters, and gerund form reads well: reconciling-supplier-accounts rather than helper or utils.
Be much shorter than feels right
The instinct when writing instructions is to explain. Resist it. The guidance is blunt about why: the context window is shared with the system prompt, the conversation, every other Skill's metadata and the actual request.
The default assumption should be that the model is already capable. Only add what it cannot know: your thresholds, your formats, your systems, your exceptions. Challenge each paragraph with "does this justify its tokens?"
Concretely, cut anything that explains a general concept and keep anything that encodes a local fact. "A reconciliation matches transactions between two records" is a waste of a line. "Exclude intercompany accounts, they reconcile separately in the group system" is the entire reason the Skill exists.
Match specificity to fragility
Not every instruction wants the same tightness, and the useful frame is how much damage a wrong turn does.
Loose guidance where several approaches are valid and context should decide. A review process is a good example: list what to look for, let the model work out how.
A preferred pattern where variation is acceptable but there is a house way of doing it. Give the template and allow adaptation.
Exact commands where the operation is fragile and one wrong step breaks something. State the command, and say plainly not to modify it.
The image in Anthropic's guidance is a good one. A narrow bridge with cliffs on both sides needs exact instructions. An open field needs a direction and trust.
Getting this backwards is a common failure. Over-specify an open-ended task and you get rigid, slightly stupid output. Under-specify a fragile one and you eventually get a broken migration.
Structure it so the detail is reachable but not loaded
Keep the SKILL.md body under 500 lines. When it grows past that, move detail into separate files and link to them from the body.
One rule that is easy to get wrong: keep references one level deep. If SKILL.md links to advanced.md, which links to details.md, the model may only preview the deeper files rather than reading them fully, and you get partial information without knowing. Everything should link directly from SKILL.md.
For reference files over about 100 lines, put a table of contents at the top, so a partial read still reveals the full scope of what is in there.
Organise by domain rather than by document number. reference/finance.md and reference/sales.md beat docs/file1.md and docs/file2.md, because the filename is itself a routing decision.
Build the tests before the instructions
This is the recommendation people skip, and it is the one that most changes the outcome.
Run the task without a Skill first. Watch where the output actually falls down. Note the specific failures: it used the wrong template, it included test accounts, it missed the escalation threshold.
Then write two or three evaluations from those observed failures, establish what performance looks like without the Skill, and write the minimum instruction needed to pass them.
Working the other way round, writing thorough documentation and then checking it, reliably produces Skills that carefully address problems the model never had while missing the ones it did. That gap is why so many Skills get written once, used twice and quietly abandoned.
Test it on someone who was not there
The person who wrote a Skill is the worst judge of it, because they know what they meant.
The reliable method is to work with one session to author the Skill, then use it in a fresh session that has none of that context, on a real task rather than a rehearsed one. Then watch behaviour rather than asking opinions:
- Did it trigger at all? If not, the description is wrong.
- Did it find the right reference file, or wander?
- Did it apply the rules, or acknowledge and then skip them?
- Is there a bundled file it never opens? That file is either unnecessary or badly signposted.
When something goes wrong, take the specific observation back and fix that. "It forgot to exclude test accounts on a regional query" is actionable. "It felt a bit off" is not.
A quick checklist
Before you share one:
- Description written in third person, saying what it does and when to use it.
- The words your team actually uses appear in the description.
- Body under 500 lines, detail in linked files, references one level deep.
- No general explanation the model already has.
- Specificity matched to how fragile each step is.
- Consistent terminology throughout. Pick one word per concept and keep it.
- No time-sensitive instructions like "before August, do X".
- One recommended approach rather than a menu of five.
- At least two or three evaluations, run against a version without the Skill.
- Tested in a fresh session on a real task.
The step after writing it
A good Skill is worth very little while it sits in one person's directory, and that is exactly where it will sit unless someone acts. Custom Skills do not sync across surfaces, and on claude.ai they are individual to each user with no organisation-wide distribution or admin management.
So the last step of writing a Skill is not writing. It is publishing it somewhere your team can find and run it, reviewing it like any other shared asset, and keeping the record of what it did. Otherwise you have written an excellent private note.
That is the gap Connor exists to close: take the working method one person proved, publish it as a Capability the whole team can run, keep it connected to the systems the work lives in, and record every run so you can see whether the output is getting better.
If you have not yet decided whether a Skill is even the right unit, start with why most workflows do not need a custom agent.
Frequently asked questions
- Why does my Skill never get used?
- Almost always the description. Only the name and description of each Skill are loaded at startup, and the model matches your request against that text to decide what to load. If the description says something like 'helps with documents', nothing will match it reliably. Rewrite it in third person, stating what the Skill does and the specific situations that should trigger it.
- How long should a SKILL.md file be?
- Anthropic's guidance is to keep the body under 500 lines. Beyond that, split the detail into separate files that SKILL.md links to, so they load only when needed. The body should read like a table of contents with the essentials inline: enough to do the common case, with pointers to the depth.
- Should I write the instructions or the tests first?
- Tests first. Run the task without a Skill and note where the output actually falls short, then build two or three evaluations from those failures, then write the minimum instruction needed to pass them. Writing documentation first produces Skills that address imagined problems and skip the real ones, which is a common reason they get abandoned.
- How do you know if a Skill is any good?
- Give it to a fresh session that has never seen the conversation where you wrote it, then watch. Does it get triggered by a realistic request? Does it find the right file? Does it apply the rules or skip them? Behaviour under real use tells you more than reading the file back, because you already know what you meant and a new session does not.