How to Build Your First Claude Skill

A Claude skill is a folder of instructions Claude loads only when your request matches it. To build one, create a file at .claude/skills/<name>/SKILL.md with a one-line description and the steps you want Claude to follow. That is the whole thing.

By the end of this tutorial you'll have a working skill that Claude picks up on its own, you'll know the one field that decides whether it fires, and you'll be able to bundle a helper script with it. Every example below is copy-paste ready.

Most people never write one

We pulled the numbers in our State of Claude Code 2026 study: only about 28% of public Claude Code repos use skills at all, and among the ones that do, the median is just 8. That is the gap this guide closes. If you use Claude Code every day and have never made a SKILL.md, you are in the majority, and you are leaving the single cheapest upgrade on the table.

A skill is the thing you reach for when you catch yourself pasting the same instructions into a new session. "Write the commit message our way." "Follow our PR template." "Draft the changelog entry like this." You write that procedure once, and Claude runs it the same way every time after.

What a skill actually is

A skill is a small folder with one required file inside it called SKILL.md. That file teaches Claude how to do one specific thing.

The trick that makes skills cheap is progressive disclosure. In a normal session Claude does not read the body of every skill you have installed. It only reads each skill's short description. When a description matches what you asked for, Claude loads that skill's full body and follows it. Everything else stays on disk, costing almost nothing. The official docs put it plainly: a skill's body "loads only when it's used, so long reference material costs almost nothing until you need it."

Two ways a skill gets into the conversation. Claude can pick it on its own when the description fits, or you can call it by hand with /skill-name. For the longer version of this background, see what Claude skills are and the Claude skills guide.

A real SKILL.md, start to finish

Here is a complete skill that writes a changelog entry from your latest commits. It is a good first skill because the task is repetitive, the output has a house style, and you want it done the same way every time.

The first line of the body runs a shell command and drops the output into the prompt before Claude reads it, so the entry is grounded in your actual commits. Everything below that is plain instructions. There is nothing else to learn.

---
name: changelog-writer
description: Drafts a changelog entry from recent git commits in our house style. Use when the user asks to write a changelog, update CHANGELOG.md, summarize what shipped, or prep release notes.
---

## Recent commits

!`git log --oneline -20`

## Instructions

Write one changelog entry for the commits above. Follow these rules:

1. Group changes under three headings, in this order: Added, Changed, Fixed. Drop any heading that has no items.
2. Each line starts with a verb in the past tense ("Added dark mode", "Fixed the signup redirect"). One sentence, no period.
3. Ignore commits that only touch tests, formatting, or CI config.
4. Write for the user, not the developer. "Faster page loads" beats "memoized the selector".
5. Put the newest entry at the top of CHANGELOG.md under a heading with today's date. Do not touch older entries.

If there are no user-facing changes in the commits, say so instead of inventing entries.

Two parts to the file. The block fenced by the --- lines is the frontmatter, written in YAML. The only field that earns its place here is description. The name is optional and just sets the display label. Below the frontmatter is the Markdown body Claude reads when the skill fires.

The line !`git log --oneline -20` is dynamic context injection. Claude Code runs that command and replaces the line with its output before Claude ever sees the skill, so the instructions arrive with your real commit history already inlined.

The folder layout

A skill is a directory, and SKILL.md is the entrypoint. For the changelog skill above, the whole thing is one file:

.claude/
└── skills/
    └── changelog-writer/
        └── SKILL.md

When a skill grows past a simple body, you bundle supporting files alongside SKILL.md and point at them from the body. Say you want the changelog rules pulled out into a longer reference, plus a Python helper that formats the version header. The layout becomes:

.claude/
└── skills/
    └── changelog-writer/
        ├── SKILL.md          # the instructions Claude loads
        ├── style-guide.md    # detailed rules, loaded only when referenced
        └── scripts/
            └── format-header.py   # executed, never loaded into context

Supporting files do not load by default. Claude opens style-guide.md only when the body tells it to, and it runs format-header.py rather than reading it. That is how a skill can carry pages of reference without spending tokens until the moment it needs them. To wire them in, add a short section to the body:

## Additional resources

- For the full formatting rules, read style-guide.md before writing.
- To build the version header, run `python scripts/format-header.py`.

Build it in four steps

Step 1: Create the folder

Make the directory in your project's .claude/skills/. Project skills ship with the repo, so anyone who clones it gets the skill.

mkdir -p .claude/skills/changelog-writer

If you want the skill on every project on your machine instead, use ~/.claude/skills/changelog-writer in your home directory. That version follows you everywhere but never gets committed.

Step 2: Write the SKILL.md

Save the changelog skill above to .claude/skills/changelog-writer/SKILL.md. The directory name (changelog-writer) becomes the command you type, so this skill is callable as /changelog-writer.

You do not need a name field at all. Leave it off and the command name still comes from the folder. Include it only when you want a prettier display label in skill listings.

Step 3: Write a sharp description

This is the step that decides everything. Claude only sees the description until a skill fires, so a vague description means the skill never gets picked. The fix is to lead with what the skill does, then spell out the phrases a user would actually type.

Compare these two:

# Weak: Claude rarely connects this to a real request
description: Helps with changelogs

# Strong: states the job, then lists the triggers
description: Drafts a changelog entry from recent git commits in our house style. Use when the user asks to write a changelog, update CHANGELOG.md, summarize what shipped, or prep release notes.

The combined description text gets truncated at 1,536 characters in the listing Claude reads, so you have plenty of room. Spend it on trigger phrases, not adjectives. "Use when the user asks to..." followed by the real wording is the pattern that works.

Step 4: Test that Claude invokes it

Two ways to confirm it works. First, call it by hand to check the body runs:

/changelog-writer

Then test the part that matters, automatic invocation. Open a session, make sure you have a few commits, and ask in plain language:

write up a changelog for what I shipped this week

If your description is sharp, Claude reaches for the skill on its own and follows the rules. If it doesn't, that is your signal to tighten the description with the exact phrasing you just used. Editing the file takes effect on the next turn without a restart, so iterate fast.

Skill vs subagent vs slash command

These three get confused constantly, so here is the short version.

A skill is the default for "do this the same way every time". A subagent is for forking off a worker that should not crowd your main context, like a parallel research pass or a long build. As of 2026 a custom slash command and a skill are the same thing under the hood, so a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. For the worker case, see how to create a Claude Code subagent.

The cleaner the split, the better each piece works. Facts that are always true belong in CLAUDE.md. Procedures you run on demand belong in a skill. Isolated work belongs in a subagent.

What you get

Once the skill is in place, the repetitive ask is gone. You stop pasting the changelog rules, the commit style, or the PR template into a fresh session. Claude loads the procedure the moment the topic lands and runs it identically every time.

Multiply that by every recurring task in your workflow and the payoff compounds. Your house rules become portable, they live next to your code, and a teammate who clones the repo inherits all of them on the first session. That is the difference the 28% who write skills already feel, and the one the rest are missing.

A faster start than a blank folder

If you'd rather inherit a library of skills than build them one at a time, the Build This Now Code Kit ships a set of skills and subagents already wired into a Next.js plus Supabase project, including planning agents, a build pipeline, evaluators, and quality gates, plus auth, payments, and database. It's $29 one-time, no subscription. You can read every SKILL.md it ships and adapt them, which is also a fast way to learn how production skills are written.

Either way, the move is the same. The next time you paste the same instructions into Claude twice, stop, and make it a skill instead.

FAQ

How do I create a Claude Code skill?

Make a folder at .claude/skills/your-skill-name/ and put one file inside it called SKILL.md. Add YAML frontmatter with a description line, then write the instructions below it. Save the file and Claude can use the skill on the next prompt. No build step and no registration.

What goes in a SKILL.md file?

Two parts. A YAML frontmatter block between two lines of three dashes, where the only field that matters is description, and a Markdown body below it with the instructions Claude follows when the skill runs. The description tells Claude when to load the skill. The body tells Claude what to do once it does.

Is the name field required in a skill?

No. The only recommended field is description. The skill's command name comes from the directory name, so a folder called changelog-writer becomes /changelog-writer. The name field only sets the display label in skill listings and is optional.

Why does Claude not pick up my skill?

Almost always the description. Claude only sees skill descriptions until one matches your prompt, so if the description is vague Claude never loads the skill. Rewrite it to lead with what the skill does, then add the exact phrases a user would type. You can also invoke it by hand with /skill-name to confirm the body works.

What is the difference between a project skill and a personal skill?

A project skill lives in .claude/skills/ inside the repo and ships with the code, so anyone who clones the project gets it. A personal skill lives in ~/.claude/skills/ in your home directory and follows you across every project on your machine but never gets committed.

Can a skill run a script or shell command?

Yes. A skill folder can bundle a scripts/ directory, and the body can point Claude at a helper script to run. You can also inject live shell output into the skill before Claude reads it by prefixing a line with an exclamation mark and a backtick-wrapped command.

How is a skill different from a subagent or a slash command?

A skill teaches Claude a procedure it loads when the description matches. A subagent is a separate worker with its own context window and tool list. A slash command is now the same feature as a skill. Use a skill for a reusable how-to, a subagent for isolated heavy work, and reach for either by typing a slash.

Posted by @speedy_devv