How to Create a Claude Skill: SKILL.md Explained With a Real Example

A Claude skill is a folder with a SKILL.md file that teaches Claude a task you do often. If you're not sure what skills are yet, start with what Claude skills are and how to install them. This guide is about writing one.

The good news: the format is simple. The part people get wrong is the description, so we'll spend most of the time there.

Step 1: Pick one job

A skill should do one thing. "Help with marketing" is too broad; Claude can't tell when to use it, and the instructions end up vague. "Turn a blog post into a 5-slide carousel script" is a skill.

A good test: can you describe the input and the output in one sentence each?

• Input: a blog post or article
• Output: five slide texts, each under 20 words, plus a caption

Step 2: Create the folder

For a skill you want in every project, create:

~/.claude/skills/carousel-script/SKILL.md

The folder name becomes the skill's name if you don't set one, and in Claude Code it's also the slash command (/carousel-script). Use lowercase letters and dashes.

Step 3: Write the front matter

SKILL.md must start with a header between two --- lines, on the very first line of the file:

---
name: carousel-script
description: Turn a blog post, article or long note into a 5-slide
  Instagram or LinkedIn carousel script with a caption. Use when the
  user asks for a carousel, slides for social, or to repurpose a post.
---

Writing a description that triggers

Claude sees only the name and description of each skill until it decides to load one. So the description has to answer two questions: what does it do, and when should it be used?

• Lead with the main use case. Put the most important trigger first.
• Use the words people actually type. "Carousel", "slides for Instagram", "repurpose this post". If you'd ask for it as "turn this into slides", say slides.
• Be specific about the input. "Blog post, article or long note" helps Claude match a pasted article.
• Don't pad it. A clear sentence or two beats a paragraph of keywords.

If your skill never activates on its own, the description is the first thing to fix.

Step 4: Write the instructions

Below the header, write the instructions the way you'd brief a sharp new teammate. Be concrete:

## Steps
1. Find the one idea the post is really about. If there are several,
   pick the most surprising one.
2. Slide 1 is a hook: a question or a bold claim, under 10 words.
3. Slides 2–4 each carry one point, under 20 words, in plain language.
4. Slide 5 is the payoff or takeaway, not "follow for more".
5. Write a caption of 2–3 short lines that adds context, no hashtags
   unless the user asks.

## Rules
- Never invent numbers, quotes or results that aren't in the source.
- Keep the author's voice. If the post is casual, stay casual.

## Output format
Slide 1: ...
Slide 2: ...
...
Caption: ...

Things that make instructions work well:

• Numbered steps for anything with an order.
• Rules for what must never happen. "Never invent numbers" is the kind of line that saves you later.
• An output format, so the result is the same shape every time.
• Short. Keep SKILL.md focused, well under a few hundred lines. Its content stays in Claude's context once loaded, so every extra paragraph costs space.

Step 5: Add supporting files (optional)

Long references don't belong in SKILL.md. Put them next to it and tell Claude when to read them:

carousel-script/
├── SKILL.md
├── examples.md      (three before/after examples)
└── voice.md         (your tone rules, read when rewriting)

In SKILL.md, add a line like: "Before writing, read examples.md for the format of a strong carousel." Claude only opens the file when it needs it.

Skills can also include scripts that Claude runs, which is how more advanced skills work. My video styles, for example, include render scripts that turn Claude's scene code into an MP4, so the skill doesn't just describe the process, it does it.

Step 6: Test it

1. Open a new Claude Code session and run /skills to check it's listed.
2. Ask for the task without naming the skill, the way you normally would. Does Claude pick it up?
3. Run it on two or three real inputs, not just one. Note where the output drifts.
4. Tighten the instruction that caused the drift, and test again.

If Claude ignores the skill, rewrite the description with the words you used in step 2. If it uses the skill but the output is off, the problem is in the steps or rules.

Common mistakes

• The header isn't on line one. A blank line or a title above --- breaks it.
• One skill doing five jobs. Split it.
• No rules. Without "never do X", Claude fills gaps with its defaults.
• Everything in one file. Move examples and long references into their own files.

A complete example to copy

---
name: carousel-script
description: Turn a blog post, article or long note into a 5-slide
  Instagram or LinkedIn carousel script with a caption. Use when the
  user asks for a carousel, slides for social, or to repurpose a post.
---

## Steps
1. Find the one idea the post is really about.
2. Slide 1: a hook under 10 words.
3. Slides 2–4: one point each, under 20 words.
4. Slide 5: the takeaway.
5. Caption: 2–3 short lines.

## Rules
- Never invent numbers, quotes or results.
- Keep the author's voice.

## Output format
Slide 1: ...
Slide 5: ...
Caption: ...

Start with something this small. Once it works, grow it with examples and scripts as you find out what Claude gets wrong.