How to Write a Claude Skill: Turning Your Best Person's Method Into a File

To create a Claude skill, choose one repeatable job, capture how your best person does it, and write that method into a SKILL.md file with a clear name, a short description and step-by-step instructions. Then test it on real requests and refine it. The file format is easy; capturing the method well is the real work.

How do you create a Claude skill?

Create a folder named after the skill, add a SKILL.md file that starts with a name and description, write the instructions in plain Markdown below them, and add any examples or templates to the same folder. Upload it to Claude or place it where Claude Code reads skills, then test it on real requests.

The mechanics are deliberately simple. According to Anthropic's help documentation, every skill is a directory containing at least a skill.md file. That file opens with YAML frontmatter holding two fields: a name of up to 64 characters and a description of up to 200 characters. Everything below the frontmatter is instructions.

Anthropic describes skills as "folders that include instructions, scripts, and resources that Claude can load when needed". Claude reads only the name and description at first, then loads the rest when a request matches. That is why a skill can be detailed without slowing down every conversation.

The harder part comes before the file: deciding which job to capture, and capturing it well.

Which job should become a skill?

Choose a job your team does often, where quality depends on knowing your company's way of doing it, and where you can quickly tell whether the output is right. Weekly reports, proposals, content checks, follow-up emails and research briefs are common first choices. Avoid rare or highly judgement-based work at first.

Three questions sort candidates quickly:

• Is it frequent? Weekly or more, so the skill pays back the effort of writing it.
• Is there a best way? Someone on the team does it noticeably better than the average.
• Can you check it? A person can tell in minutes whether the output followed the method.

A weekly client report scores well on all three. Negotiating a contract scores badly on the third, because judging the output takes as long as doing the work.

How do you capture your best person's method?

Ask the person who does the job best to walk through a real example while someone takes notes or records the conversation. Capture the steps, the checks they make, the mistakes they avoid and what good looks like. Then write it in their words, not in policy language, and have them confirm it.

People are often poor at describing their own expertise in the abstract. Ask "how do you write a report?" and you get a generic answer. Ask them to talk through last week's report, and you get the real method: where they pull the numbers, what they compare against, which caveats they always add.

Useful prompts for that conversation:

1. "Show me the last one you did." Work from a real example.
2. "What do you check before it goes out?" That becomes the checklist.
3. "What do people usually get wrong?" That becomes the warnings.
4. "What would make you reject a draft?" That defines good.

This step is also where a skill differs from process documentation. A process document is written to be read, so it rarely is. A skill is written to be followed by an agent every time the job comes up, so gaps show up quickly and get fixed. The guide to process documents vs skills explores that difference.

What goes in the SKILL.md file?

The file holds a name, a description that says what the skill does and when to use it, and the instructions: steps, checks, warnings and at least one example of good output. Keep it focused on one job. Supporting material, such as templates or reference lists, goes in separate files in the same folder.

Here is a simplified example for a weekly client report:

---
name: weekly-client-report
description: Writes the weekly client report from this week's figures. Use when asked for a client's weekly report or weekly results summary.
---

# Weekly client report

1. Read the client's targets from the account file before writing.
2. Compare this week with last week and with the monthly target.
3. Lead with the one number the client cares about most.
4. Explain any change over 10% in one plain sentence.
5. Never speculate about causes the data does not show.

Check before handing over: every figure matches the source, and the
report fits on one page. See example-report.md for a good one.

Two details matter most. First, the description: Claude decides whether to use the skill from that line alone, so it should name the task and the phrases people use to ask for it. Second, the example: Anthropic advises including example inputs and outputs, because one good example teaches more than a page of rules.

How do you test a Claude skill?

Test it with several requests that should trigger it and a few that should not. Check that Claude picks it up when expected, follows the steps, and produces output your best person would accept. If the skill does not fire, rewrite the description. If the output misses the mark, tighten the instructions or improve the example.

Anthropic's documentation recommends exactly this loop: try prompts that should trigger the skill, and iterate on the description if Claude does not use it. Have the person whose method it captures judge the output. They will spot what is missing faster than anyone.

Be wary of judging by feel. According to a 2025 randomised trial by METR, experienced developers believed AI had made them 20% faster when it had made them 19% slower. Compare skill output with the real thing, side by side, rather than trusting an impression. The guide to testing a skill covers simple ways to do that.

How do you share and maintain skills?

Share skills with your team through your organisation's Claude settings or a shared repository, and give each skill a named owner who updates it when the method changes. Review skills regularly, retire ones nobody uses, and keep them in files your business owns so they outlast any one person or tool.

Anthropic added organisation-wide management in December 2025, so administrators can provide skills to everyone at once. In the same month it published Agent Skills as an open standard, which makes well-written skills more portable between tools.

Maintenance is where most skill libraries decay. Prices change, the report format changes, a new step is added, and nobody updates the file. Naming an owner and reviewing skills quarterly prevents that. The guide to running a skill library goes deeper.

Skills also work better with accurate facts to draw on. A report skill is only as good as the targets it reads. Skein builds skills as agents on top of a shared company brain, so each method has current facts to work from; the skill library shows the kinds of skills involved. That suits a team turning several methods into skills. A single user can write one useful skill in an afternoon without any wider system.

Frequently asked questions

How do I make a Claude skill?

Create a folder named after the skill containing a SKILL.md file. Start the file with a name of up to 64 characters and a description of up to 200 characters, then write step-by-step instructions and an example below. Upload the folder to Claude, enable it, and test it on real requests.

What should a SKILL.md file contain?

It should contain a name, a description saying what the skill does and when to use it, and instructions covering the steps, the checks before handing over, common mistakes to avoid and at least one example of good output. Supporting templates or reference files can sit alongside it in the same folder.

Why is my Claude skill not working?

Usually the description is too vague, so Claude does not recognise when to use the skill. Rewrite it to name the task and the words people use to ask for it, then test with several matching requests. If the skill fires but the output is weak, tighten the instructions or add a better example.

Do I need to code to create a Claude skill?

No. A skill can be written entirely in plain Markdown: a name, a description and instructions. Scripts are optional and only needed for tasks such as processing files or running calculations. Most business skills, such as report, proposal and checking methods, need no code at all.

How many Claude skills should a business have?

Start with one or two for your most frequent, method-dependent jobs, prove they work, then add more. Because Claude loads a skill only when relevant, a team can install many. The practical limit is maintenance: every skill needs an owner who keeps it current.

Related reading