Create Your First Skill

The anatomy of SKILL.md

---
name: release-notes
description: Write user-facing release notes from merged PRs since the last tag. Use when the user asks for release notes, a changelog entry, or "what shipped".
argument-hint: "[version]"
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. List merged PRs since then: `gh pr list --state merged --search "merged:>=<tag date>"`
3. Group changes into **New**, **Improved** and **Fixed**. Skip internal refactors.
4. Write for customers, not engineers: lead with the benefit, one line each.
5. Title the notes with version $ARGUMENTS (or "Unreleased" if none was given).
6. Save to `docs/releases/<version>.md` and show me the result.

Two parts:

• Frontmatter (between the --- lines): metadata such as name, description and options.
• Body: the instructions Claude follows when the skill runs.

The folder name becomes the command, so this skill runs as /release-notes 2.4.0.

Write a description that triggers

The description answers two questions: what does this skill do, and when should it be used. Include the words a user would actually say.

You can also add a separate when_to_use field for trigger phrases. It's combined with the description.

Arguments

Anything typed after the command is available as $ARGUMENTS. For positional pieces, use $0, $1 and so on (or name them with the arguments field):

---
name: migrate-component
description: Migrate a UI component from one framework to another
arguments: [component, from, to]
---
Migrate the $component component from $from to $to, preserving behavior and tests.

/migrate-component SearchBar JavaScript TypeScript

If your skill doesn't reference $ARGUMENTS anywhere, Claude Code appends what you typed automatically, so nothing gets lost.

Test it both ways

Changes to existing skills are picked up live. If you create a brand-new top-level skills directory mid-session, run /reload-skills.

Check your understanding