How to Create a Claude Code Skill (SKILL.md), Step by Step

A skill is a folder with a SKILL.md file that teaches Claude Code a task you repeat. Claude Code keeps each skill's short description in view and loads the full instructions only when a task matches, so you can keep many skills without filling the context window.

Before you start

Claude Code installed.
One task you keep explaining from scratch. This guide uses writing release notes.

How a skill loads

flowchart LR
  A[Your request] --> B{Does it match a skill's description?}
  B -- yes --> C[Load the full SKILL.md]
  C --> D[Follow its steps and use its bundled files]
  B -- no --> E[The skill stays unloaded]

Step 1: Create the folder

Project skills live in .claude/skills/ and travel with the repo. Personal skills live in ~/.claude/skills/ and work in every project on your machine.

mkdir -p .claude/skills/release-notes

Step 2: Write SKILL.md

---
name: release-notes
description: Write release notes from the pull requests merged since the last tag. Use when the user asks for release notes or a changelog.
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. List the pull requests merged since that tag with `gh pr list --state merged`.
3. Group them under Added, Changed and Fixed.
4. Write one plain line per change, ending with the PR number.

The description is the field that matters most: Claude matches it against your request. Say what the skill does and when to use it.

Step 3 (optional): Add supporting files

Put long references next to SKILL.md and point to them from the steps, for example See template.md for the layout. Claude reads them only when a step needs them.

.claude/skills/release-notes/
  SKILL.md
  template.md

Step 4: Test it

Claude Code picks up new and edited skills within the current session, so you can try it right away. Ask in plain words, "Write the release notes for this release," or start it by name with /release-notes. If the .claude/skills folder itself did not exist when the session started, run /reload-skills first.

Step 5 (optional): Make risky skills manual-only

A skill that deploys or deletes should never start on a guess. Add one line to its frontmatter:

disable-model-invocation: true

Now Claude never loads it on its own; it runs only when you type /release-notes.

Common mistakes

A vague description. "Helps with git" never matches anything. Name the task and the trigger.
One giant SKILL.md. Keep the steps short and move references into their own files.
A brand-new skills folder that never loads. If .claude/skills was created after the session started, run /reload-skills.