Claude Skills from 0 to 100: What They Are and How to Build Your Own

You explain to Claude how you write a report. Works great. Tomorrow you open another chat and you have to explain it all over again. And the day after, same thing. That loop is exactly what skills are built to break: you package a process once and Claude uses it when it fits, without you ever explaining it again.

This guide goes from zero to having your first skill working: what it is, how Claude decides to use it, how to build your own step by step, and the mistakes that leave it dead before you even start.

What a skill is (and what it isn't)

A skill is a folder with a file called SKILL.md inside. That file holds natural-language instructions for a specific task: how you write your emails, how you put together a report, what rules you follow when reviewing code. Optionally it can carry more things —templates, reference documents, scripts— but the heart is always the SKILL.md.

How it differs from what you already know:

• A prompt you paste in every time. Manual, repeated work.
• A CLAUDE.md is fixed context for a project: it's read when you start the session in that folder.
• A skill is modular and topic-based. Claude has several and picks the one that applies based on what you ask. It works in any project, not just one.

If you have a process you repeat across different places, that's a skill.

How Claude reads skills: the three levels

Here's the technical key that explains everything else. Claude doesn't load your whole skills at once —that would burn context for no reason. It reads them in three levels, what's called progressive disclosure:

1. Frontmatter (always loaded). Just the name and description of each skill. It's the "label" Claude always has in view to know what's available.
2. Full SKILL.md (loaded if it applies). When your request matches the description, Claude opens the body of the file and reads the instructions.
3. Extra files (on demand). Folders like references/, scripts/, or assets/ are only touched if the task needs them.

The practical consequence is huge: the entire weight of whether your skill triggers or not falls on the description, because it's the only thing Claude sees before deciding. If the description doesn't clearly tell it when to use the skill, it won't even bother opening the rest.

The frontmatter: name and description

The frontmatter is the few lines at the very top of the SKILL.md, between ---. Minimal but decisive.

name — the identifier, in kebab-case (lowercase and hyphens). Rules you don't skip:

• Lowercase, words separated by hyphens: email-reviewer, not Email_Reviewer.
• No "claude" or "anthropic" inside it.
• No tags or weird characters.

description — the sentence that decides your life. It has to say two things: WHAT the skill does and WHEN to use it, with phrasing that mirrors how you ask for things. You have up to around 1,024 characters; don't waste them on marketing, spend them on concrete triggers.

# ❌ WEAK — Claude doesn't know when to trigger it
---
name: emails
description: Helps with emails.
---

# ✅ GOOD — says WHAT + WHEN with real triggers
---
name: blackdark-email-reviewer
description: >
Reviews and rewrites emails in the Blackdark voice: direct, no filler,
clear subject line and a single call to action. Use it when the user
asks "review this email", "improve this message", "rewrite this email
so it reads better" or pastes an email draft to send.
---

Notice the good version: it includes the literal phrases you'd use to ask for the task ("review this email", "improve this message"). That's what hooks it. A vague description is the number-one reason a skill never fires.

Build your first skill, step by step

Let's put together a real skill. Two paths.

Path A — have Claude generate it. You describe the case in plain language ("I want a skill that reviews my emails with a direct tone, a clear subject line, and a single CTA") and it writes the SKILL.md for you. Fast to get started; then you fine-tune the description by hand.

Path B — by hand. More control, and you understand better what's going on. Recommended body structure:

---
name: blackdark-email-reviewer
description: >
Reviews and rewrites emails in the Blackdark voice: direct, no filler,
clear subject line and a single call to action. Use it when the user asks
"review this email", "improve this message" or pastes a draft to send.
---

# Blackdark Email Reviewer

## Instructions
- Direct, practical tone. No filler, no "hope you're doing well".
- Clear subject line under 50 characters.
- A single call to action, at the end, unmistakable.
- Respect the language of the original draft.

## Steps
1. Read the draft and detect the real goal of the email.
2. Rewrite: subject + body, max 120 words unless more is requested.
3. Note on a separate line what you changed and why.

## Example
Input: "Hi, I wanted to see if maybe we could perhaps schedule a call
whenever you can to talk about the project, thanks."
Output:
Subject: 20-min call this week
Body: Does a 20-min call on Thursday at 11:00 work to wrap up the
project? If not, send me two slots and I'll adapt.

## Mistakes to avoid
- Don't invent data that isn't in the draft.
- Don't add more than one CTA even if the original has several intentions.

Now place it where Claude will read it:

• In Claude Code: create the folder ~/.claude/skills/blackdark-email-reviewer/ and drop the SKILL.md inside. Restart the session and you're set.
• In claude.ai: zip the folder into a .zip and upload it from the skills panel; then turn it on with its toggle.

The folder name and the frontmatter name must match, and the file must be named exactly SKILL.md, in uppercase.

How to test it (on two fronts)

Don't call a skill good until you've tested the two things that can fail separately:

1. Does it trigger on its own? Ask for the task in your real words —not by copying the description— and see whether Claude uses it without you telling it to. Try three or four variants of how you'd really ask. If it doesn't fire, the problem is in the description.
2. Is the result correct? Once triggered, check that the output respects the rules (format, tone, limits). If it triggers but ignores instructions, it's usually that the important stuff is buried at the end or written ambiguously.

Common mistakes (and how to fix them)

The failures are almost always the same five:

• Never triggers → vague description, no "when". Rewrite it with concrete trigger phrases, the ones you'd actually use to ask for the task.
• Triggers too much, butting in where it's not wanted → description too broad. Narrow the domain and explicitly state which cases it does NOT cover.
• Not recognized on upload → the file isn't named exactly SKILL.md, or the name isn't in kebab-case, or it doesn't match the folder.
• Triggers but doesn't follow the rules → the critical stuff is buried. Move the important rules to the very top and give them clear formatting (lists, bold).
• Slow or burns a lot → the SKILL.md is a wall of text. Keep only the essentials in it and move the long detail into references/ files that load only when needed.

A well-made skill is short in the SKILL.md, brutal in the description, and honest about when NOT to use it. Start with just one, the process you repeat most, and fine-tune it until it triggers on its own. When you see Claude do your task without you explaining it, you've got it.