How to create a Claude skill

1. Name it for the job

Name the skill after the job it does (“release-notes-writer”, “seo-content-optimizer”), not the tool or model behind it. The name field uses lowercase letters, numbers and hyphens, and becomes the slash command you can type to run the skill.

2. Create the folder

A skill is a folder with a SKILL.md inside. Put it in ~/.claude/skills/ to use it in every project, or in a repository's .claude/skills/ to share it with everyone who works on that repo.

~/.claude/skills/release-notes-writer/
├── SKILL.md          # required: frontmatter + instructions
├── reference.md      # optional: longer detail, loaded only when needed
└── scripts/          # optional: helper scripts the instructions call

3. Write the description carefully

Claude reads only each skill's name and description up front, and loads the full instructions when a request matches. So the description has to say both what the skill does and when to use it, in the words a user would actually type. A vague description (“helps with docs”) means the skill never gets picked.

4. Write the instructions

Below the frontmatter, write the steps Claude should follow, what to avoid, and an example if the output has a specific shape. Keep SKILL.md focused; move long reference material into separate files and mention them by name so Claude reads them only when needed.

---
name: release-notes-writer
description: Turns a list of merged pull requests into user-facing release notes. Use when the user asks for release notes, a changelog entry, or "what shipped" for a version.
---

# Release notes writer

1. Ask for the version number and the list of merged PRs if they
   were not provided.
2. Group changes under: New, Improved, Fixed. Drop internal-only
   changes (CI, refactors, test-only PRs).
3. Write each item as one sentence a user would understand. Lead
   with the benefit, not the implementation.
4. End with an "Upgrade notes" section only if a change needs
   action from the user.

Never invent a change that is not in the PR list.

5. Test it

Start Claude Code and ask for something the description covers (“write release notes for v2.4 from these PRs”), or type /release-notes-writer to run it directly. If Claude doesn't pick the skill up on its own, the description is usually the problem — make it more specific about when to use it. Try a few real inputs and keep the ones that went wrong as examples to check future edits against.

6. Share it

Commit .claude/skills/ to share a skill with your team. To list it on ClaudeSkill, put it in a public GitHub repository under an open license (MIT or Apache-2.0 suit most skills) and submit the repository URL via /submit. Submissions are reviewed before they are published — see the editorial policy.