How to Create a Claude Skill, Step by Step

To create a Claude skill, make a folder named after the skill, put a SKILL.md file inside it with a name and a description in YAML frontmatter, and write the instructions underneath. Then drop the folder into ~/.claude/skills/ for Claude Code, or zip it and upload it under Customize → Skills on claude.ai. Most of the real work comes after that: testing whether Claude actually picks the skill up, and rewriting the description until it does.

Here's the whole process in five steps:

1. Pick one repeatable task and write three test prompts before you write anything else.
2. Create the folder and SKILL.md, with a lowercase, hyphenated name and a description that says what the skill does and when to use it.
3. Write short instructions that Claude follows for the whole task.
4. Add scripts, references or templates only when plain instructions aren't enough.
5. Test it in Claude Code or claude.ai, then tune the description until it triggers on the right prompts and stays quiet on the wrong ones.

If you want the concepts first — what skills are and why they're cheap on context — start with our Claude Skills overview. This guide builds one real skill, file by file.

What a Claude skill is made of

A skill is a folder. Anthropic's Agent Skills overview and the open Agent Skills specification define the same layout: one required file, three optional folders.

We'll build a skill called writing-meeting-recaps. It turns messy meeting notes into a recap with decisions, owners and due dates. Here's the finished folder:

writing-meeting-recaps/
├── SKILL.md
├── scripts/
│   └── check_recap.py
├── references/
│   └── email-style.md
└── assets/
    └── recap-template.md

That last column is why skills scale: at startup Claude sees only each skill's name and description, roughly 100 tokens per skill according to the spec.

How to create a Claude skill, step by step

Step 1: Pick one task and write your test prompts first

Good first skills are things you already explain to Claude over and over. Anthropic's help article on creating custom skills puts it simply: one specific, repeatable task per skill, not a skill that does everything.

Before writing the skill, write three prompts it should handle. Anthropic's skill authoring best practices recommend building evaluations before the documentation, so the skill fixes real gaps instead of imagined ones. For our recap skill:

• "Here are my notes from the pricing call, turn them into a recap."
• "Can you write a follow-up email from this transcript?"
• "Summarize what we decided in this meeting and who owns what."

Add one prompt that should not trigger it, such as "Summarize this research paper."

Step 2: Create the folder and the SKILL.md frontmatter

For Claude Code, create the folder in your personal skills directory:

mkdir -p ~/.claude/skills/writing-meeting-recaps

Then open SKILL.md and start with the frontmatter:

---
name: writing-meeting-recaps
description: Turns meeting notes or transcripts into a recap with decisions, action items, owners and due dates. Use when the user shares meeting notes or a transcript, or asks for a recap or follow-up email.
---

The rules for those two fields depend on where the skill will run:

Sources: the Claude Code skills docs, the platform overview and the spec linked above.

The practical takeaway: write to the strictest column. Keep the folder name and name identical (the spec requires it), keep the description under 200 characters, and your skill will load everywhere. The example description above is 195.

Anthropic's guidance adds two rules: write the description in the third person ("Turns notes into…", not "I can help you…"), and use the words a real person would type, like "notes", "transcript" and "recap".

Step 3: Write instructions Claude will keep following

Below the frontmatter goes the body. Anthropic's default assumption is that Claude is already smart, so include only what it can't guess: your format, rules and edge cases.

# Writing meeting recaps

Follow these rules for the whole task, including later edits.

1. Read the notes once. List every decision, then every action item.
2. Fill in assets/recap-template.md. Keep its headings and order.
3. Every action item needs one owner (@name) and a due date (YYYY-MM-DD).
   Use the meeting date to resolve "Friday" or "next week".
   If the notes name no owner or date, put the item under Open questions.
4. Save the recap as recap.md and run: python3 "${CLAUDE_SKILL_DIR}/scripts/check_recap.py" recap.md
   Fix whatever it reports and run it again until it prints OK.
5. If the user wants an email, read references/email-style.md first.

## Example
Notes: "Ana sends the pricing deck Friday. We're dropping the Q4 webinar."
Recap:
- Decisions: Drop the Q4 webinar.
- Action items: - [ ] Send pricing deck — @ana — 2026-10-31

Notice the first line. In Claude Code, a skill's content enters the conversation once and the file isn't re-read on later turns, so the docs recommend wording guidance as standing instructions ("for the whole task") rather than one-off steps. Put the most important rules near the top too: after the conversation is compacted, Claude Code keeps only the first 5,000 tokens of each invoked skill.

Size limits are generous but real. Both the spec and Claude Code's docs say to keep SKILL.md under 500 lines and move detail into separate files.

Add scripts, reference files and templates

Plain instructions are fine for judgment calls. For anything that must be exact every time, bundle a file.

A script for checks that can't be fuzzy. When Claude runs a script, only its output enters context, not the code. Here's the validator from step 4:

import re, sys

text = open(sys.argv[1], encoding="utf-8").read()
problems = []
for heading in ("## Decisions", "## Action items", "## Open questions"):
    if heading not in text:
        problems.append("missing section: " + heading)
for line in text.splitlines():
    if line.startswith("- [ ]"):
        if not re.search(r"@\w+", line):
            problems.append("no owner: " + line)
        if not re.search(r"\d{4}-\d{2}-\d{2}", line):
            problems.append("no due date: " + line)
print("\n".join(problems) or "OK")
sys.exit(1 if problems else 0)

This is the "feedback loop" pattern Anthropic recommends: check, fix, check again.

Notice how step 4 calls it: python3 "${CLAUDE_SKILL_DIR}/scripts/check_recap.py", not python scripts/check_recap.py. Claude Code runs shell commands from your project directory, not the skill's folder, so a bare relative path fails as soon as you use the skill in a real project. Claude Code replaces ${CLAUDE_SKILL_DIR} with the folder that holds SKILL.md, which the skills docs say resolves "regardless of the current working directory."

A reference file for detail Claude only sometimes needs. references/email-style.md holds your email tone, sign-off and length rules. It costs nothing until someone asks for an email. Link it directly from SKILL.md; the spec says to keep references one level deep, not chained file to file.

An asset for output that must look the same every time. assets/recap-template.md is the empty recap with its three headings.

Use forward slashes in paths, even on Windows, and never hardcode API keys or passwords. Dependencies also differ by surface: per the claude.ai help article, Claude and Claude Code can install packages from PyPI or npm, but Skills on the API can't install anything at runtime.

Install and test your skill

In Claude Code

Where you save the folder decides who gets the skill:

Claude Code watches these folders, so edits to SKILL.md show up in the current session without a restart. If you created the top-level skills folder after the session started, run /reload-skills.

Then test it two ways:

• Automatic: paste some notes and say "turn these into a recap." This is the real test, because it checks the description.
• Direct: type /writing-meeting-recaps. This only checks the instructions.

If the skill never fires, ask Claude "What skills are available?" to confirm it loaded. If the YAML is malformed, Claude Code still loads the body but with empty metadata, so /writing-meeting-recaps works while automatic triggering silently doesn't. Start Claude Code with --debug to see the parse error, or validate the folder with claude plugin validate ~/.claude/skills. Outside Claude Code, the spec's skills-ref library runs the same kind of frontmatter check.

On claude.ai

claude.ai needs a zip, and the structure matters. Per the help article, the zip must contain the skill folder at its root, not loose files:

writing-meeting-recaps.zip
└── writing-meeting-recaps/
    ├── SKILL.md
    ├── scripts/
    ├── references/
    └── assets/

Then, following Using skills in Claude:

1. Make sure Code execution and file creation is turned on in your settings. Skills don't run without it.
2. Go to Customize → Skills, click +, then Create skill, then Upload a skill.
3. Upload the zip and toggle the skill on.
4. Try your test prompts, and check Claude's thinking to confirm it loaded the skill.

One thing that catches people out: skills don't fully sync between surfaces. A folder in ~/.claude/skills/ stays on that machine. Skills enabled on your claude.ai account do get downloaded into Claude Code sessions where you sign in with that account, but the Claude API keeps its own separate list. If you need the skill everywhere, install it in each place.

Make it trigger: iterate on the description

Seeing the skill work once proves little. Claude Code's docs split the question in two: does Claude invoke it on the right prompts, and is the output right when it does?

Run your four test prompts in a fresh session, once with the skill on and once with it off. Fresh matters, because leftover context from writing the skill hides gaps in the instructions. Then fix what you see:

Two findings from Anthropic's own skill-creator are worth knowing. First, Claude tends to undertrigger skills, so its authors suggest making descriptions a little "pushy", naming the situations where the skill applies even if the user doesn't say its name. Second, simple one-step requests may not trigger any skill, because Claude can handle them on its own. Test with substantial, realistic prompts.

Use skill-creator as your Claude skill creator

You don't have to do this loop by hand. skill-creator is the closest thing to an official Claude skill creator: it interviews you about the task, drafts SKILL.md, and helps test it. In Claude Code, install the skill-creator plugin with /plugin install skill-creator@claude-plugins-official, then ask Claude to evaluate your skill. According to the Claude Code docs, it stores test cases in evals/evals.json, runs each one in a clean subagent, benchmarks with-skill against without-skill, and generates should-trigger and should-not-trigger prompts to tune the description.

On claude.ai, you can ask Claude to draft a skill in the conversation and edit the files beside the chat before you save it. Claude for Mac also lets you record a skill: you do the task on screen in Cowork, and Claude proposes a skill from the recording.

Once your own skill works, reading other people's SKILL.md files gets more useful. Our list of the best Claude skills and the guide to the Claude skills marketplace are good next stops, and Anthropic's skills repository has a bare template to copy.

FAQ

How do I build a skill in Claude without writing code?

Most skills have no code at all. A SKILL.md with a name, a description and plain-English instructions is a complete skill. Scripts are optional and only worth adding for checks that must be exact.

Is there an official Claude skill creator?

Yes. Anthropic publishes skill-creator, a skill (and a Claude Code plugin) that helps you write, test and refine new skills, including tuning the description for triggering.

Do I need both name and description?

For claude.ai and the API, yes; both are required. Claude Code makes them optional, using the folder name and the first line of the body as fallbacks, but you should still write both so the skill works everywhere.

Why does my skill work with /name but never on its own?

Usually the description. Either it doesn't contain the words people type, or the YAML frontmatter failed to parse, which leaves Claude with nothing to match. Check with --debug.

Can I share a skill I made?

In Claude Code, commit it to a project's .claude/skills/ folder or package it in a plugin. On Team and Enterprise plans, claude.ai lets you share a skill with colleagues or publish it to your organization, per the Using skills in Claude article. Creators can also publish their work to Taku from Claude Code with the Taku Publisher plugin.

Key points

• Match the folder name and name, keep the description under 200 characters, and stick to spec fields if you'll upload it.
• Write standing instructions, and bundle scripts only for checks that must be exact.
• Test in a fresh session, with and without the skill, and treat the description as the thing you iterate on most.
• Skills don't fully sync between Claude Code, claude.ai and the API. Install where you need them.

Building skills is the easy half. The harder half is getting a skill, or a whole workflow someone else built, running on your machine without rebuilding their setup. Taku mirrors a working AI setup into a desktop workspace where you can run it, edit it and save it as your own. Taku is in Beta, and the Mac app is available now.