Claude Skills, explained: what they are and how to build your own

What is a Claude Skill made of?

The whole thing is a folder. Inside it sits one required file, SKILL.md, and whatever else the job needs.

SKILL.md has two parts. At the top is a short block with the skill's name and a one-line description. That description is what triggers the skill: Claude reads it, compares it to what you asked for, and loads the rest of the file when they match. Below the description come the instructions themselves, written the way you would brief a careful new colleague. The steps, the format you want back, what to do when the input is incomplete, and one worked example.

Next to SKILL.md you can add optional files. Scripts the skill can run, reference files it should read before answering, templates it should fill in, a checklist to run before it replies. A skill for weekly reports might carry the report template and a script that pulls the numbers. A skill for writing in my voice carries a corpus of my own posts. The skill file stays short and points at the rest.

If I could teach one line of all this, it would be the description. A vague one loads for nothing, or for everything. Name the inputs the skill expects and the words a person would use when asking for the job, and the matching takes care of itself.

Where the folder goes depends on where you use it. The Claude app and Claude Code each have their own place for it.

Skills vs projects vs custom instructions vs saved prompts

These four get confused because they all tell Claude how to behave. They differ on when they load and how much they carry.

	What it is	When it loads	Best for
Skill	A folder with SKILL.md, plus optional scripts and reference files	Only when a task matches its description	One repeatable job, done the same way in chat and in Claude Code
Project	A workspace with its own files and standing instructions	Every chat opened inside that project	Ongoing work on one client, product or topic
Custom instruction	Standing preferences about you, your tone and your formats	Every chat, everywhere	How you like answers written, whatever the task
Saved prompt	A block of text you keep somewhere and paste in	Only when you paste it	A task you run by hand now and then

The rule I use: if the same job comes up in more than one project, it wants to be a skill. If it belongs to one body of work, a project. If it is about me rather than the job, a custom instruction. If I will do it twice this year, a saved prompt is fine, and the Claude prompts in the library are a good place to take one from.

How to write your first skill in 20 minutes

Pick a job you have briefed Claude on at least three times by hand. That repetition is the signal. Then write five things.

1. A name. Lowercase, hyphenated, and it should say what the skill does: meeting-notes-to-actions, never helper.
2. A one-line description. This is the trigger, so write it for the part of Claude that decides whether to load the skill, and name the situations in which it should fire.
3. The steps. Numbered. Include what to do when the input is missing something.
4. One example. A short input and the exact output you want back. One good example does more than a paragraph of adjectives.
5. A test prompt. Something you would actually type, saved next to the skill so you can re-run it after every edit.

Here is a generic SKILL.md that follows that shape.

---
name: meeting-notes-to-actions
description: Turns raw meeting notes into a table of actions, owners and due dates. Use when the user pastes meeting notes, a call transcript or a summary and asks for follow-ups, action items or next steps.
---

# Meeting notes to actions

Steps

1. Read the whole input before writing anything.
2. Pull out every commitment: who said they would do what, and by when.
3. If an owner or a date is missing, write "unassigned" or "no date". Never guess.
4. Return a table with four columns: Action, Owner, Due, Source line.
5. End with one line listing open questions, if there are any.

Example

Input: "Sam will send the deck by Friday. We still need someone to book the venue."

Output:

Action	Owner	Due	Source line
Send the deck	Sam	Friday	1
Book the venue	unassigned	no date	2

Open questions: who owns the venue booking?

Save it, run the test prompt, and read the output against the example. The first version is usually close and wrong in one specific way: a column missing, or a guess where you asked for "unassigned". Fix the step that caused it and run again. Two or three rounds and it holds.

What keeps a skill library useful at 50 skills?

The first few take care of themselves. Then the folder starts to rot, and by fifty skills it is either a system or a junk drawer. Four habits decide which. This is the material in module 3 of the course, stated at a high level.

One job per skill. The moment a skill does two things, its description gets vague and it starts loading for the wrong tasks. Split it.

Naming that sorts. Prefix by domain so related skills sit together in a listing: email-, seo-, code-, client-. A name you can guess from the outside is a name you will reuse.

Versioning. Put a version line in the file and note what changed. When a skill stops behaving, you want to know whether it was your edit or the model that moved.

A README index. One file at the top of the folder that lists every skill, its trigger, its version and its last update. It is the map you read before you write a new skill, because the fastest way to grow a mess is to build the same skill twice under different names.

Where else does a Claude Skill run?

The same folder runs in Claude Code, Cursor, Codex, Gemini CLI and thirty other agents. That portability is the reason to learn the format properly rather than keep a pile of saved prompts.

A skill is plain text in a folder. Any agent that reads a SKILL.md can pick it up, so the work you do once follows you across tools and across model versions. Prompts saved inside one product's interface do neither.

A skill tells an agent how to do a job. An MCP server gives it a tool it can call, a database or a browser. The two stack, and if you want the tool side I keep a directory of MCP servers.

Free starting points

You can start without buying anything, and you should. The skills directory lists ready-made skills you can read and adapt. Reading other people's SKILL.md files is the fastest way to develop taste for what a good description looks like.

If you want a set to install today, the free Claude Skills Pack for Beginners has 10 ready skills. And if you would rather understand how I build and score what is on this site before trusting any of it, that is written up on the documentation page.