How to Build a Claude Skill: SKILL.md in Six Steps

To build a Claude Skill, create a folder with a SKILL.md file inside it. That file needs YAML frontmatter — a name and a description — followed by plain-Markdown instructions. Claude reads the short description to decide when the skill applies, then loads the full instructions only when your request matches. That is the entire mechanism.

Skill structure and loading behaviour verified 31 July 2026 against Anthropic's Agent Skills documentation.

Agent Skills are how you teach Claude to do a recurring task your way — a commit style, a report format, a review checklist — without re-explaining it every session. The good news: you can build a Claude Skill in a few minutes, and you do not need to be a programmer to do it. Claude currently spans models like Opus 5, Sonnet 5, and Haiku 4.5, and the same SKILL.md format works across all of them — we review this guide regularly so the steps stay accurate — a first skill, including a round of testing, usually takes about 10 minutes. This guide walks through the structure, the one field that matters most, and a step-by-step build you can copy today. If Claude Code is new to you, our pillar guide on what Claude Code is sets the scene first. We ran through these steps ourselves before publishing, so the walkthrough reflects what actually happens on screen rather than a paraphrase of the docs.

What is a Claude Skill?

A packaged set of instructions, plus any optional scripts and resources, that teaches Claude one specific task. Progressive disclosure keeps the cost near zero: only each name and description sit in context until a request matches.

A skill is a packaged, reusable set of instructions — plus any optional scripts or resources — that teaches Claude how to handle one specific kind of task. Instead of pasting the same guidance into chat over and over, you write it once, and Claude pulls it in automatically when it is relevant. Anthropic calls the feature Agent Skills, and the same format works across Claude Code, the claude.ai apps, and the Claude API.

Think of a skill as the onboarding notes you would hand a new teammate: here is the task, here are the rules, here is an example of good output. The efficiency comes from a design Anthropic calls progressive disclosure. Claude loads only each skill's name and description at startup — roughly 100 tokens apiece — and keeps the full instructions on disk until they are actually needed. You can read the official Agent Skills overview for the architecture, but the practical takeaway is simple: dozens of installed skills cost almost nothing until one fires. That is exactly why learning to build a Claude Skill is worth your time.

For a deeper tour of how skills load and install inside the CLI, our companion guide on Claude Code skills covers the mechanics. This article focuses on authoring one yourself.

The structure of a skill

A folder containing one required file, SKILL.md, split into YAML frontmatter and a Markdown body. Templates, reference documents, and scripts can sit alongside it and load only when SKILL.md points Claude at them.

Every skill is a folder, and inside it SKILL.md is the only required file. That file has two parts separated by a line of ---:

1. YAML frontmatter — metadata at the top. At minimum a name and a description. Optional fields let you fine-tune behavior.
2. A Markdown body — the actual instructions Claude follows once the skill activates: steps, rules, examples, and pointers to any bundled files.

A skill can bundle more than SKILL.md. You can add reference documents, templates for Claude to fill in, or scripts Claude runs through the shell — and you reference them from SKILL.md so Claude knows what each file is for. Because those extra files load only when they are needed, a single skill can carry a lot of material without bloating context:

pr-writer/
├── SKILL.md        # required: frontmatter + instructions
├── template.md     # optional: a format for Claude to fill in
└── scripts/
    └── check.sh    # optional: a script Claude can run

Here is what each part does and how to get it right:

Why the description matters most

Claude never reads the body until it has already decided the skill is relevant, and it decides by matching your request against the name and description. State what it does and when to use it, in the words a user would actually type.

If you take one thing from this guide, make it this: the description is the single most important part of any skill. Claude never sees the body until it has already decided the skill is relevant, and it makes that decision by matching your request against the name and description. A vague description means the skill never fires; a sharp one means it fires exactly when you want.

So write the description to say two things clearly: what the skill does and when to use it. Include the words a user would naturally type. "Helps with git" is useless. "Use when the user asks for a changelog, release notes, or a summary of what shipped" is a routing rule Claude can act on. This is the highest-leverage decision when you build a Claude Skill, so spend real time on it and keep it to one clean line of YAML.

How to build a Claude Skill step by step

Six steps: pick one focused task, create the folder and file, write a specific name and description, add imperative numbered instructions, bundle any supporting files, then restart the session and test on natural prompts.

Here is the whole process, start to finish. It is shorter than most configuration files.

Step 1: Pick one focused task. A skill should do one thing well. "Write our pull-request descriptions" is a good scope; "help with coding" is not. Skills that produce a predictable shape — a commit message, a review, a spec — are the easiest to build and test. Before you build a Claude Skill, name the single task in one sentence.

Step 2: Create the folder and SKILL.md. In Claude Code, personal skills live in ~/.claude/skills/ (available in every project) and project skills live in .claude/skills/ at the repo root (shared with your team via git). Create a folder named for the skill:

mkdir -p ~/.claude/skills/pr-writer

Then create a SKILL.md file inside it. The official Claude Code skills docs list the exact locations, including the plugin and enterprise paths.

Step 3: Write a strong name and description. This is the trigger, so make it specific:

---
name: pr-writer
description: Write a clear pull-request description from the current diff. Use when the user asks for a PR description, a summary of changes, or release notes.
---

Step 4: Write the instructions. Below the frontmatter, give Claude clear, imperative steps — what to do, what rules to follow, and an example of the output you expect. Numbered lists work well:

# PR writer
 
1. Read the staged diff.
2. Summarize the change in two sentences.
3. List the key edits as bullets, grouped by area.
4. End with a "Testing" section describing how it was verified.

Step 5: Add supporting files if the task needs them. If the skill needs a template, a checklist, or a script, drop it in the folder and point to it from SKILL.md ("Use template.md as the format"). Keep SKILL.md itself short and move heavy reference material into separate files, so it loads only when Claude reaches for it.

Step 6: Install and test it. In Claude Code, the folder is the install — restart the session so it picks up the new skill, then trigger the task naturally ("write a PR description for these changes"). You can also invoke it directly as /pr-writer to force it. In the claude.ai apps you upload a skill as a zip in settings; through the Claude API you upload it via the Skills endpoints — the packaging differs, but the SKILL.md inside is identical. Testing is the real proof that you build a Claude Skill correctly: watch whether it fires on the prompts it should.

Building skills for this repo in Claude Code, the diagnostic that saved us the most time was using that forced /skill-name invocation as a deliberate test rather than a shortcut. If the skill produced the right output when we called it by name but never fired on its own, we knew the body was fine and the description was the problem — and if it misbehaved even when forced, the instructions were at fault. Splitting the failure that way, before touching anything, meant we stopped rewriting the wrong half of the file.

A minimal SKILL.md example

A complete example fits on one screen: frontmatter naming the exact requests that should trigger it, then a short numbered procedure with an explicit rule against inventing changes. That combination covers most real skills.

Here is a complete, illustrative skill you can adapt. This is an example for reference, not a copy-paste production skill — swap in your own task:

---
name: commit-writer
description: Write a Conventional Commits message from staged changes. Use when the user asks for a commit message or to commit their work.
---
 
# Commit writer
 
1. Read the staged diff.
2. Choose a type: feat, fix, docs, refactor, test, or chore.
3. Write a one-line summary under 60 characters, in the imperative mood.
4. Add a short body only if the change needs explanation.
5. Never invent changes that are not in the diff.

Notice how the description names the exact requests that should trigger it, and the body is a short numbered procedure. That combination is most of what it takes to build a Claude Skill that works reliably.

Best practices

One task per skill, a description written for discovery, imperative numbered steps, an example of the output shape, and iteration against real prompts until it fires on the right requests and stays quiet on the wrong ones.

A few habits separate skills that fire reliably from ones that gather dust:

• Keep each skill focused. One task per skill. When you build a Claude Skill that tries to do five things, its description gets muddy and matching suffers. Split it up.
• Write the description for discovery. State what it does and when to use it, using the phrasings you would actually type into chat.
• Use clear, imperative instructions. Tell Claude what to do in numbered steps. State rules directly rather than narrating background or reasoning.
• Include an example. Showing the output shape you want is worth a paragraph of description, and it anchors Claude to your format.
• Iterate by testing real prompts. Run the requests you care about in a fresh session, with and without the skill, and compare. Tighten the description if it fires on the wrong requests, or misses the right ones.

These principles carry over whether you build a Claude Skill for coding or for knowledge work. Designers package brand rules this way — see Claude skills for designers — and note-takers wire skills into their vault, as in this Claude skill for Obsidian. When you want to hand a finished skill to a team, the Claude Code plugin marketplace bundles it with hooks and agents in one installable package. Browsing the best Claude skills is also the fastest way to study strong descriptions in the wild before you write your own, and the open-source claude superpowers collection is a particularly rich source of well-scoped skills to learn from.