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

Creating a Claude skill requires no runtime, no install script, and no build step. A skill is a folder with one SKILL.md file. This guide covers the frontmatter, the description that determines when the skill loads, the folder layout, and a template. For the definition, see what Claude skills are.

Step 1 — Create the folder

Pick a scope and make a folder named after your skill (lowercase, hyphenated):

# Personal — works in every project
mkdir -p ~/.claude/skills/release-notes
touch ~/.claude/skills/release-notes/SKILL.md

# Project — committed with a repo
mkdir -p .claude/skills/release-notes
touch .claude/skills/release-notes/SKILL.md

Use the personal path for your own workflows; use the project path (and commit it) for skills your whole team should share.

Step 2 — Write the frontmatter

The top of SKILL.md is a YAML block. Two keys matter most — name and description:

---
name: release-notes
description: Draft clear release notes from a list of merged changes or
  commit messages. Use when the user asks for a changelog, release notes,
  or a "what's new" summary for a version.
---

The description is the single most important line you will write. Claude reads only the name and description of each skill until it decides to use one, so the description has to name the situation — in the third person, with the words users actually type. “Writes text” will never trigger; the version above will.

Step 3 — Write the instructions

Everything below the frontmatter is the skill body. Write it like a briefing for a sharp new teammate: say what to do, not why. Be concrete and ordered.

---
name: release-notes
description: Draft clear release notes ...
---

# Writing release notes

Given a list of merged PRs or commit messages:

1. Group changes under **Added**, **Changed**, **Fixed**, **Removed**.
2. Rewrite each entry in user-facing language (what changed for them,
   not the internal function name).
3. Lead with the most impactful change.
4. Keep each bullet to one sentence. Link PR numbers if provided.
5. End with a one-line summary suitable for a social post.

Step 4 — Add supporting files (optional)

Skills can bundle more than instructions. Drop a template, a reference document, or a helper script in the folder and reference it from SKILL.md — thanks to progressive disclosure, those files are read only when Claude actually needs them, so they cost nothing until used:

release-notes/
├── SKILL.md
├── template.md        # referenced from SKILL.md
└── scripts/
    └── parse_prs.py   # run only when needed

Step 5 — Restart and test

Start a new session so Claude re-scans the skills directory, then make a request that matches the description. If it does not trigger, tighten the description and try again — see the troubleshooting guide for the full checklist.

Writing style: the conciseness test

• Third person, imperative instructions. “Group changes by type,” not “You might want to consider grouping.”
• Trigger-focused description. Name the exact task and its synonyms.
• No filler. If a line does not change the output, cut it — the same discipline you would apply to a CLAUDE.md.
• One job per skill. A skill that tries to do five things triggers for none of them cleanly.

Let a skill build your skill

You do not have to start from a blank file. Anthropic’s Skill Creator scaffolds a new skill — folder, frontmatter, and a first draft of the description — from a plain description of what you want. The Writing Skills skill goes further and codifies the authoring best practices themselves. Once your skill works, consider adding it to a shared library so your team can install it too.