What Makes a Good Skill
A good skill gives the same right result every time, for anyone who uses it. These are the habits that get you there.
Make a skill when the job repeats
Make a skill when you have done a job more than once and expect to do it again, when the steps should be the same each time, or when someone else needs to do it your way.
Don't make a skill for a one-off question, or for knowledge that changes every day. For a one-off, a clear request is enough. See Give Clear Instructions.
One skill, one job
A skill that does one job well is easier to describe, test and fix than one that does several. If you write "and also" in the description, think about two skills.
| Too broad | Better |
|---|---|
finance | check-invoices, monthly-expense-report |
website-helper | export-orders, update-stock-levels |
Write the description for the request, not for the skill
The AI chooses a skill by its description alone. Say what it does and when to use it, in the words people will actually type:
| Weak | Strong |
|---|---|
| "Invoice tool." | "Check supplier invoices against the agreed price list and list mismatches. Use when asked to check, verify or reconcile invoices." |
| "Does the weekly report." | "Write the weekly operations report from this week's tickets and orders. Use when asked for the weekly report, a weekly update or this week's numbers." |
Say what done looks like
Name the output, its format and where it goes. "A table" is vague; "a CSV with columns date, supplier, amount, difference, saved as mismatches.csv" is not.
Write down the limits
Tell the AI what it must not do and when it must stop and ask:
- "Read only. Never change records on the website."
- "If more than 20 items fail, stop and report instead of continuing."
- "Ask before sending anything to someone outside the team."
Include a check
Give one representative input and the result you expect, plus a rule the AI can test: "every total matches the sum of its rows", "every ID in the output exists in the input". The AI uses it to verify before it reports back, and you use it to tell whether a change broke something.
Put exact work in a script
If part of the job must be exactly the same every time, such as a calculation, a format conversion or a fixed sequence of calls, put it in a script. The AI's judgement goes into the parts that need judgement. See How a Skill Is Written.
Keep it short; move detail out
Keep SKILL.md to the method. Long reference material such as a price list, a style guide or a field list belongs in a separate file in the skill folder, mentioned in the method ("use references/prices.csv"). The AI opens it when it needs it.
Share it where the work lives
- A skill for one project goes in that project's workspace (
.agents/skills/). Everyone who opens the folder gets the same skill. - A personal habit goes in this computer's skills
- A method for your whole institution can be published by your institution, so everyone gets it and updates arrive automatically
Improve it every time it misses
When a result is wrong, correct it in the chat, then ask the AI to update the skill with that correction. Over time the skill collects the judgement of everyone who uses it.
Checklist
- [ ] Does one job
- [ ] Description says what and when, in the users' words
- [ ] Output, format and location are named
- [ ] Limits and stop conditions are written down
- [ ] Has a representative check
- [ ] Exact steps are in a script
- [ ] Saved where the people who need it will find it
- [ ] Tested in a new chat without naming the skill