What Claude Skills Are and How They Work

Imagine you get a new helper at work. They are clever and fast, but they do not know how your team likes things done. So every single day you explain it again. Same explanation, every morning, forever.

A Claude Skill is how you stop doing that. You write the explanation down once, in a file. From then on Claude reads it by itself, at the moment it becomes useful.

Anthropic gives away a whole set of these for free at github.com/anthropics/skills. You can read every one of them.

A skill is just a folder

This part surprises people. There is no app to install and no code to write. A skill is a folder with a text file inside it.

skill-name/
├── SKILL.md      <-- the only file you actually need
├── scripts/      <-- optional: small programs
├── references/   <-- optional: extra notes
└── assets/       <-- optional: templates, fonts

Only SKILL.md is required. The .md ending means Markdown, which is a simple way of writing text where you use a # to mark a heading and a - to mark a bullet point. If you have used Reddit, WhatsApp or Discord formatting, you already know most of it.

What goes in the file

Two parts. A label at the top, then your instructions underneath.

---
name: commit-style
description: How we write commit messages. Use this when
  writing or editing a commit message.
---

# Commit messages

Keep the first line under 60 characters.
Explain WHY you made the change, not what you changed.

The bit between the two --- lines is called the frontmatter. That is a slightly odd word for a very simple thing: it is the label on the box. It tells Claude what this skill is and when to open it.

Everything under it is what you actually want Claude to do.

That is a complete, working skill. Nothing else is needed.

The label rules

• name — required. Up to 64 characters. Only lowercase letters, numbers and hyphens.
• description — required. Up to 1024 characters. Say what it does and when to use it.
• license — optional. Who is allowed to reuse it.
• compatibility — optional. Anything special it needs to run.
• metadata — optional. Extra notes for your own use.
• allowed-tools — optional, and still being tested.

You can ignore the last four. Almost every skill uses only the first two.

Why you can have loads of these

Here is the clever bit, and it explains why skills do not slow Claude down.

Think about a library. You do not read every book to find the one you want. You read the spines, pick one, and open only that.

Claude does the same thing:

• It always reads the spines. That is the name and description of every skill you have. Tiny.
• It opens one book only when the description matches what you asked for.
• It looks at the appendix only if that book points to one.

So having twenty skills installed costs almost nothing. Claude is only reading twenty spines.

The description decides everything

Because Claude only sees the spine when choosing, the description is the most important thing you write. Brilliant instructions with a vague description will never get opened.

Weak: “PDF stuff.”

Strong: “Pull text and tables out of PDFs, fill in forms, join files together. Use this whenever someone mentions a PDF.”

The strong one contains the words a real person would actually say. That is what makes it match.

If a skill never seems to fire, the description is nearly always the problem. Rewrite that before you touch anything else.

Where to put the folder

~/.claude/skills/     <-- just for you, in every project
.claude/skills/       <-- shared with your team, in one project

The second one is the interesting option. If you put a skill in the project folder and share the project, everyone on your team gets it automatically. Nobody has to be told the rules, because the rules arrive with the code.

You can also run a skill on demand by typing a slash and its name, like /deploy.

Try it in five minutes

1. Think of something you have explained more than twice.
2. Make a folder for it inside ~/.claude/skills/.
3. Put a SKILL.md in it with a name, a description, and your rules.
4. Start a new chat and ask for something that should use it.
5. If nothing happens, improve the description.

Then go and read a few real ones in Anthropic’s public collection. Seeing a good one teaches you more than any guide.