How to write your own Claude skill, step by step

If you keep pasting the same instructions into Claude ("use this format", "don't make up due dates", "keep it to one screen"), that's a skill waiting to be written. A skill saves those instructions in a folder, and Claude loads it on its own whenever a request matches.

This guide walks through writing one, using Meeting Minutes, a Skillshelf original, as the example. You don't need to code: most skills are a single markdown file.

What a skill is made of

A skill is a folder with a SKILL.md file inside, plus any other files it needs:

meeting-minutes/
├── SKILL.md
└── templates/
    └── minutes.md

SKILL.md has two parts: a short header between --- lines, called the frontmatter, with the skill's name and description, and then the instructions in plain markdown.

How Claude reads those parts explains most of what makes a skill work:

1. Claude starts out seeing only the name and description of each skill you have installed.
2. When your request matches a description, Claude reads that skill's SKILL.md.
3. Claude opens other files, like a template, only when the instructions point to them.

So the description decides whether your skill gets used, and the instructions decide how well it works.

Step 1: Pick a job you repeat

Good skills come from real, repeated tasks, not clever ideas. Look for:

• something you ask Claude for every week, like minutes, a weekly update or a citation list;
• a job that needs the same format or method every time;
• corrections you keep making, like "you made up a due date again."

Before writing anything, do the task a few times without a skill and note what you have to fix. Save three real requests to test with later. This is what Anthropic recommends too: find the gaps first, then write just enough instructions to close them.

Step 2: Write the name and description

Here's the frontmatter of Meeting Minutes:

---
name: meeting-minutes
description: Turns raw meeting notes, chat logs or transcripts into clean minutes with decisions, action items (owner, task, due date) and open questions. Use when the user pastes notes from a meeting, standup, sync or call and wants a summary, recap, minutes or a list of next steps.
---

The name:

• uses only lowercase letters, numbers and hyphens, up to 64 characters;
• can't contain the words "claude" or "anthropic";
• should match the folder's name, which claude.ai checks when you upload.

The description is the most important line in the skill. It can be up to 1,024 characters. A good one:

• says what the skill does, in the third person: "Turns raw meeting notes into…", not "I can help you…";
• says when to use it, with the words people actually type: notes, standup, sync, recap, next steps;
• is specific. A description like "Helps with documents" gives Claude nothing to match a request against.

Careful with #. In the frontmatter, a space followed by # starts a comment, so description: Writes posts with #hashtags loses everything from #hashtags on. If your description needs a #, put the whole description in double quotes.

Step 3: Write the instructions

Below the frontmatter, tell Claude what to do in plain, direct language. Claude is already capable, so don't explain things it knows. Spend your words on what's specific to this job: the steps, the rules and the output.

Here are the instructions of Meeting Minutes, in full:

# Meeting Minutes

Turn messy meeting notes into minutes people can act on.

## Steps

1. Read everything once before writing. Notes are often out of order.
2. Pull out four things:
   - **Decisions**: anything the group agreed on or ruled out.
   - **Action items**: a task a specific person will do.
   - **Open questions**: things raised but not settled, including tasks with no owner.
   - **Context to remember**: numbers, dates or limits someone will need later.
3. Write the minutes using `templates/minutes.md`.

## Rules

- Never invent an owner or a due date. If the notes don't say, write `—` in the table and add the gap to Open questions.
- Mark anything uncertain in the notes ("maybe Friday", "I think") as *tentative*.
- Start every action item with a verb: "Email the vendor about pricing", not "Vendor pricing".
- Use people's names exactly as they appear in the notes.
- Keep it short. Minutes for a 30-minute meeting should fit on one screen.
- If the notes are too thin to summarize, say what's missing instead of padding.

## Output

Return only the filled-in template. Leave out any section that would be empty, except Action items: if there are none, write "No action items were assigned."

What makes it work:

• Steps in order. Notes are often out of order, so reading everything first means a decision made at the end of the meeting doesn't get missed.
• Rules that answer real mistakes. When notes leave a gap, it's easy to fill in a plausible owner or date. "Never invent an owner or a due date" closes that gap and says exactly what to write instead.
• A clear output. Claude knows to return only the template, and what to do when a section would be empty.
• It's short. The whole file is under 40 lines. Anthropic suggests keeping SKILL.md under 500 lines, and most skills need far fewer.

Step 4: Add files only when they help

Supporting files are for things that are long, need to be exact, or only matter some of the time:

• Templates for an output format, like templates/minutes.md.
• Reference material, like the grading rubric in Essay Feedback or the style rules in Citation Formatter.
• Scripts for steps that must be exactly right, like checking a file's format. Claude can run them where code execution is available. Only include code you've read and understand.

Point to each file from SKILL.md by its path inside the skill, with forward slashes (templates/minutes.md), and say what it's for. Link every file directly from SKILL.md, not from inside another reference file, so Claude knows it exists and reads all of it.

Step 5: Test it

Install your skill (see how to install a skill), start a new conversation, and run the three requests you saved in step 1. Check four things:

1. It's used without being named. Ask the way you normally would. If Claude doesn't use the skill, add the words you used to the description.
2. It isn't used when it shouldn't be. Ask for something nearby, like a meeting agenda for Meeting Minutes, and check that the skill stays out of it.
3. The answer follows every rule. Go through them one by one. Did it leave the due date blank when the notes didn't give one?
4. It's better than without the skill. Compare with your answers from step 1. If nothing changed, the skill isn't adding anything yet.

When something's off, change one thing and run the same requests again. If you use more than one Claude model, test with each: a smaller model may need more detail than a larger one.

Every Skillshelf original goes through this before it's published, and we also actually run any code, formula or calculation in its example to make sure it's right.

Step 6: Package and share it

For claude.ai, zip the folder itself, so the .zip holds meeting-minutes/SKILL.md rather than a loose SKILL.md.

On macOS or Linux:

zip -r meeting-minutes.zip meeting-minutes

On Windows, in PowerShell:

Compress-Archive -Path .\meeting-minutes -DestinationPath .\meeting-minutes.zip

claude.ai accepts only these frontmatter fields: name, description, license, compatibility, metadata and allowed-tools. Claude Code understands more, such as argument-hint or disable-model-invocation, so a skill that uses them only works in Claude Code.

For Claude Code, put the folder in ~/.claude/skills/ to use it yourself, or in a project's .claude/skills/ folder, committed, to share it with everyone on the project.

Let Claude help you write it

You don't have to start from a blank page. After working through a task with Claude, ask: "Turn what we just did into a skill. Include the format we settled on and the rule about not guessing due dates." Claude knows the skill format. Then trim what it gives you: cut explanations of things Claude already knows, and keep the rules that came from real corrections.

In Claude Code, Anthropic's skill-creator plugin helps you create skills, improve them and measure how well they work:

/plugin install skill-creator@claude-plugins-official

Checklist before you share it

• The name is lowercase with hyphens, and matches the folder
• The description says what the skill does and when to use it, in the third person
• The instructions are short: steps, rules and the output format
• Each rule fixes a mistake you actually saw
• Each extra file is linked from SKILL.md by its path
• The skill is used when it should be, and not for nearby requests
• You've read every file in it, including any scripts

Want more examples? Every Skillshelf original shows its full SKILL.md under the Files tab, next to a real example of it at work. Browse all the skills.