Build a Custom Claude Code Skill with SKILL.md

A skill is a reusable packet of instructions (and optionally scripts) that extends what Claude Code can do. You write the instructions once in a file called SKILL.md, and Claude adds it to its toolkit.

Think of it as a custom cheat sheet. Whenever the task matches, Claude can load the skill on demand and follow your instructions exactly. This lets you automate repetitive work like formatting code, running a release checklist, or generating a database schema, without re-typing the steps every time.

Unlike putting everything in CLAUDE.md, a skill's body only loads when it is actually used, so even long reference material costs almost no context until you need it.

Each skill is a folder containing a SKILL.md file. Where you put that folder decides who can use it:

• Personal (all your projects): ~/.claude/skills/<skill-name>/SKILL.md
• Project (this repo only, commit it to share): .claude/skills/<skill-name>/SKILL.md

The folder name becomes the command you type. A skill at .claude/skills/deploy-staging/SKILL.md is invoked as /deploy-staging.

A SKILL.md has two parts:

1. YAML frontmatter between --- markers. The most important field is description — Claude reads it to decide when to use the skill automatically. (name is optional and just sets the display label.)
2. Markdown instructions below the frontmatter — the steps Claude follows when the skill runs.

---
description: Format and clean up Markdown files. Use when asked to tidy or format a .md document.
---

When formatting a Markdown file:
- Put a blank line before every heading
- Remove trailing spaces at the end of lines
- Wrap paragraphs at 80 characters

A skill folder can also hold supporting files — templates, example outputs, or helper scripts (bash or Python) that Claude runs — but only SKILL.md is required.

There are two ways a skill runs, and understanding the difference is the whole point of skills:

• Claude auto-invokes it. Claude always sees each skill's description. When your request matches, it loads the skill on its own. Ask "tidy up README.md" and a well-described formatter skill kicks in without you naming it.
• You invoke it directly by typing /<skill-name> (the folder name), e.g. /format-md. Use this when you want to trigger the skill yourself.

You control this with frontmatter. Add disable-model-invocation: true to make a skill manual only — handy for actions with side effects like /deploy or /commit, where you don't want Claude deciding to run it. By default both you and Claude can invoke a skill.

Let's build a real project skill that tells Claude how to tidy up Markdown files. From your playground, create the skill folder:

mkdir -p .claude/skills/format-md

Now create .claude/skills/format-md/SKILL.md. Open it in your editor and paste:

---
description: Format and clean up Markdown files. Use when asked to tidy, clean, or format a .md document.
---

When formatting a Markdown file:
- Put a blank line before every heading
- Remove trailing spaces at the end of lines
- Wrap paragraphs at 80 characters

Because this folder is named format-md, the skill is available both automatically (from its description) and directly as /format-md.

Launch Claude Code in your playground:

claude

First, confirm Claude can see the skill. Ask:

What skills are available?

You should see format-md listed. Now test both invocation styles.

Direct — type the command and a target file:

/format-md clean up intro.md

Automatic — describe the task without naming the skill, and let Claude pick it up:

Tidy up the formatting in intro.md

Either way, Claude reads your skill's rules, adds blank lines before headings, strips trailing whitespace, rewraps paragraphs, and saves the result.

Type /exit to close the session.