ResourcesMethod
What makes a good AI skill: the elements every skill needs
Adding more instructions rarely fixes a skill that does not work. These are the 23 things we look for in a reliable AI skill, walked through with one real-world example.
The Fygment team
, 9 min read
Download the checklist (PDF)All 23 elements on one page, to use when you build or review a skill.
When an AI skill does not work, most people do the same thing: they add more instructions. Then more. We see people keep adding detail to a skill and still not get it to work reliably.
What usually decides whether a skill works is its structure. Researchers who studied real-world skills found that over 99% break at least one basic rule for writing them. And in SkillsBench, a 2026 research benchmark, short and focused skills beat long and exhaustive ones.
Below are the 23 elements we look for in a reliable skill, in five groups, with one example running through the whole article. The full list is also available as a one-page PDF at the top of this page.
The example: a skill that drafts client proposals
Imagine a consultancy where account managers spend a morning on every first draft of a proposal. Someone writes a skill so that Claude or ChatGPT can produce that first draft from a brief.
It sounds simple. In practice the draft depends on the brief in the CRM, the right past work, the service catalogue, the current rates, the company template, and a handful of rules that experienced account managers apply without thinking. That mix is typical of real company work, which makes it a good test for the checklist.
Start with what the skill is for
A skill should do one job. "Help with proposals" is not a job. "Draft the first version of a proposal from a CRM brief" is. The narrower the job, the easier it is to describe when the skill should be used.
That description matters more than people expect. In Vercel's tests, the AI never used an installed skill in 56% of cases, and Anthropic's guidance says the description is what decides whether a skill gets picked at all. Finally, give the skill an owner: one person who answers for it when something goes wrong.
- 1
One clear job. The skill does one task or process well, not everything at once.
- 2
Says what it does and when to use it. A short description the AI reads to decide when to pick the skill. A vague one means the skill is used at the wrong moment, or never.
- 3
A named owner. One person keeps the skill current, handles feedback and approves changes.
Then the process inside it
This is the part most skills leave out, and the part your experts know best. Start by making sure the process itself is agreed: if two experienced colleagues describe the steps differently, settle that first, or the skill will automate a disagreement. Then write the work down as steps. For each step, say where the information comes from. Name the decisions, including the rules nobody wrote down. Add a check after each step, so the AI confirms it did the step right before it moves on, and a final check on the result. Most of a good skill is knowledge that was never written down.
For the proposal skill, the process looks like this.
The proposal skill, step by step
- 1
Collect the brief
Data: the opportunity in the CRM and the account manager's meeting notes. Check: the client name, scope, budget range and deadline are all there. If one is missing, stop and ask the account manager instead of guessing.
- 2
Choose relevant past work
Data: the library of approved case studies. Decision: for clients in finance or healthcare, use only case studies cleared for regulated sectors. Check: at least two references from a similar industry or company size.
- 3
Draft the scope and approach
Data: the service catalogue and the standard delivery method. Decision: if the budget is below the minimum engagement size, propose a smaller first phase. Check: every deliverable matches a need in the brief.
- 4
Price it
Data: the current rate card, owned by finance. Unwritten rule: discounts above 10% need a director's approval, so flag them rather than apply them. Check: the total matches the rate card and the estimated effort.
- 5
Write it up
Data: the company proposal template and tone guide. Check: no promises outside the service catalogue, and the length stays within the template's limit.
- 6
Check the whole draft
The draft is checked against the quality criteria and handed to the account manager with a short list of open questions.
Look at the discount rule in step four. Nobody had written it down; account managers simply knew it. Rules like that are where skills go wrong, and you only find them by sitting with the people who do the work.
- 4
An agreed process. The people who do the work agree on the steps and on what a good result is. Do not automate a process that is still disputed.
- 5
Defined steps. The work broken into clear steps, in order.
- 6
A data source for each step. Which system, document or person each step takes its information from.
- 7
The decision points. The ifs and conditions, including the rules nobody ever wrote down.
- 8
A check after each step. How the AI confirms a step was done correctly before it moves on, and what to do if it was not.
- 9
A quality check on the result. The criteria the final output must meet before it is handed over.
- 10
Examples of good output. Concrete examples, or a template, of what a good result looks like.
“Most of a good skill is knowledge that was never written down.”
Write only what the AI doesn't know
The AI already knows what a proposal is and how to write a persuasive paragraph. What it does not know is your rate card, your rule for regulated clients and your tone of voice. Leave out the general explanations; Anthropic's own guidance gives the same advice.
Be strict where a mistake is expensive, like pricing, and leave room for judgement where many answers are fine, like the wording of the introduction. Use one term for one thing throughout. And keep dates and temporary rules out of the instructions, where they quietly go out of date.
- 11
Only what the AI doesn't already know. Your company's knowledge, not general explanations. More detail does not make a better skill.
- 12
Strict where mistakes are costly. Exact instructions for fragile or high-stakes steps, and room for judgement where many approaches work.
- 13
One term for one thing. The same word for the same concept throughout, so the AI never has to guess.
- 14
Nothing that goes out of date. No dates or temporary rules buried in the instructions. Old ways of working are kept apart and clearly marked.
Test it before anyone else uses it
Two good runs prove very little, as we explain in AI skills aren't one-and-done. Before anyone else uses the skill, write at least three test cases with the result you expect. Anthropic suggests writing them before the skill is finished, and comparing the results with how the AI does without the skill, so you know the skill actually helps.
Because the AI answers a little differently every time, run each test several times, and in every AI tool your team will use. An AI judge can score the results against your quality criteria, so nobody has to read every output. For the proposal skill, three test cases cover the normal path and both decision points.
Test cases for the proposal skill
| Test case | Expected result |
|---|---|
| A standard request with a complete brief | A complete draft using the template, two relevant case studies and a price that matches the rate card. |
| A bank asking for a proposal | Only case studies cleared for regulated sectors are used. |
| A budget below the minimum engagement size | A smaller first phase is proposed, and no discount above 10% is applied. |
- 15
Test cases with expected results. At least three real tasks with the result you expect, written before the skill is finished.
- 16
A before-and-after comparison. How well the AI does the task without the skill, so you know the skill actually helps.
- 17
Automatic scoring of the output. An AI judge scores each result against your quality criteria, so testing does not depend on someone reading every output.
- 18
Tested in every AI tool you use it in. A skill can behave differently in Claude, ChatGPT or Copilot, and even between models from the same vendor.
- 19
Tested by others on real work before sharing. Colleagues use it on real tasks. Working twice for its author is not enough.
Keep it good after it ships
A skill keeps running long after its author has moved on to other work. When the AI model underneath changes, run the tests again, and give the skill a review schedule that matches how much the company relies on it.
Make sure the people who use the skill can tell the owner what is wrong, and turn each improvement into a new version that is reviewed before it reaches everyone. And check that the skill is actually used. A skill nobody uses usually has a vague description or the wrong job.
- 20
Re-tested when the AI changes, and on a schedule. New AI models change behaviour. A skill approved last month can quietly get worse.
- 21
A feedback route to the owner. People who use the skill report problems and suggest improvements where the owner sees them.
- 22
Every change versioned and reviewed. Each improvement becomes a new version, reviewed before it reaches people, with the previous one kept.
- 23
A check that it is actually used. Whether people and AI tools use the skill, or it just sits installed.
Why this takes longer than an afternoon
A simple skill can be written in minutes. The proposal skill above cannot. Most of the time does not go into writing. It goes into mapping the process with the people who do it, finding the data each step needs, and getting the unwritten rules out of their heads. That work is what makes a skill worth relying on.
It is also the work we built Fygment around. Every skill in Fygment lives in one company library with its owner, its versions and its approval history, and the approved version reaches each AI tool your team uses. While someone writes a skill, Fygment points out what is missing from this checklist, such as steps without checks or a vague description. Each skill carries its test cases, a new version has to pass them before it is approved, and usage shows whether people actually use it.
If you want to try it with one of your own skills, Fygment is free to start.
Questions we often get
- What should an AI skill include?
- A clear job, a description of when to use it, an owner, defined steps with a data source and a check for each, a quality check on the result, examples, test cases with expected results, and a plan for keeping it current.
- How long should an AI skill be?
- As short as it can be while still covering your company's process. Include only what the AI does not already know. Research shows focused skills outperform long, exhaustive ones.
- How do I test an AI skill?
- Write at least three test cases with the result you expect, including the tricky cases. Run each one several times, compare the results with what the AI does without the skill, and repeat in every AI tool the skill will be used in.
- Does this checklist work for custom GPTs, Gems and Copilot agents?
- Yes. The elements are about how reusable AI instructions are built and maintained, so they apply to Claude skills, ChatGPT skills and custom GPTs, Gemini Gems, and Copilot agents alike.
Keep reading
- AI skills aren't one-and-done: the mistakes companies make
Most AI skills are written once, tried twice and shared with the whole team. These are the six mistakes we see most often, why they happen, and what the teams that get skills right do differently.
- What is an AI Skills registry?
An AI Skills registry is the shared inventory, review surface, and package lifecycle for reusable agent capabilities that need ownership, versioning, and install state.