How to create custom skills for Claude Code

To create a custom skill for Claude Code, make a folder named after the skill in ~/.claude/skills/ (or .claude/skills/ in a project), add a SKILL.md file with a name, a description and your instructions, then test it by asking for that task or typing /skill-name. Anthropic's skill-creator skill can then help you measure and refine it.

If you are new to the format, read what a Claude skill is first. This guide covers the practical steps.

Step 1: Pick one job

A skill works well when it covers one repeatable task with a clear finish: "write release notes from merged pull requests", not "help with the project". The Claude Code documentation suggests turning instructions you keep pasting into chat into a skill, and moving procedures out of CLAUDE.md once they grow long.

Choose a short name using lowercase letters, numbers and hyphens, such as release-notes. The name becomes the folder name and the slash command.

Step 2: Create the folder

Personal skills, available in every project on your machine:

mkdir -p ~/.claude/skills/release-notes

Project skills, shared with anyone who clones the repository:

mkdir -p .claude/skills/release-notes

Plugins can also carry skills in a skills/ folder, which is the usual route for sharing a set of skills across many repositories.

Step 3: Write SKILL.md

---
name: release-notes
description: Drafts release notes from merged pull requests since the last tag. Use when the user asks for release notes, a changelog entry, or a summary of what shipped.
---

## Steps
1. Find the latest git tag and list pull requests merged after it.
2. Group changes under Added, Changed and Fixed.
3. Write one plain sentence per change and link the pull request.

## Rules
- Leave out internal refactors unless they change behaviour.
- Ask before publishing anything.

Three points make the difference:

• The description decides when the skill loads. Claude compares requests against it. State what the skill does and when to use it, and include words people would naturally type. Claude Code truncates long descriptions in its skill list (the combined text is capped at 1,536 characters), so put the main use first.
• Write instructions that stay true for the whole session. Claude Code adds the skill's content to the conversation once and does not reread the file on later turns.
• Keep it short. Aim for under 500 lines in SKILL.md; move detail into separate files.

Step 4: Add scripts and reference files if needed

Long reference material belongs in its own file, linked from SKILL.md so Claude knows when to open it:

release-notes/
├── SKILL.md
├── references/style-guide.md
└── scripts/list_merged_prs.py

Scripts suit steps that must give the same result every time. Claude runs them and sees only the output. In Claude Code, refer to bundled files with the ${CLAUDE_SKILL_DIR} variable so the path works whether the skill is installed personally, per project or in a plugin. The Agent Skills specification recommends that scripts list their dependencies and print clear error messages.

Step 5: Decide who can start it

By default both you and Claude can start a skill. Two Claude Code fields change that:

The allowed-tools field pre-approves named tools for the turn that runs the skill. Grant as little as the task needs.

Step 6: Test it

1. Start Claude Code and ask "What skills are available?" Your skill should be listed.
2. Make a request that matches the description, without naming the skill, and check that Claude loads it.
3. Run it directly with /release-notes.

Claude Code watches skill folders, so edits apply within the session; a skills folder that did not exist when the session started needs /reload-skills. If the YAML is malformed, the slash command still works but Claude cannot match your description. Running claude --debug shows the parse error, and claude plugin validate ~/.claude/skills checks front matter (Claude Code v2.1.233 or later). For skills meant for other agents too, the specification's skills-ref validate ./my-skill command checks the standard fields.

Use the skill-creator skill

Anthropic publishes a skill-creator skill in its anthropics/skills repository. Its own description says it creates new skills, improves existing ones and measures how they perform. The workflow it follows:

1. Ask what the skill should do, when it should trigger and what good output looks like.
2. Draft SKILL.md and any bundled files.
3. Write two or three realistic test prompts and save them in evals/evals.json.
4. Run each prompt with the skill and without it (or against the previous version), grade the results, and show them for your review.
5. Revise and repeat until you are satisfied.
6. Generate prompts that should and should not trigger the skill, then adjust the description to improve the hit rate.

In Claude Code, install it as a plugin with /plugin install skill-creator@claude-plugins-official, then ask, for example, "evaluate my release-notes skill with skill-creator". The Claude Code documentation says each test runs in a separate subagent with a clean context, and that results include pass rate, time and tokens with and without the skill.

Codex ships its own built-in skill-creator, started with $skill-creator. You can also find the skill on our skill listings.

Share your skill

• With your team: commit .claude/skills/ to the repository.
• Across repositories: package skills in a Claude Code plugin.
• In claude.ai: upload the folder as a zip file. Only the standard front matter fields are accepted there.
• In other agents: keep to the standard fields and check each agent's documentation for its skills folder.

Custom skills do not sync between Claude Code, claude.ai and the API, so add them in each place.

Safety note

A skill with scripts runs code on your machine, and a project skill's allowed-tools setting takes effect even in a folder you have not marked as trusted, according to the Claude Code documentation. Review skills that arrive in repositories as carefully as any other code, and see our security questions to ask before installing a server or skill.

Next steps

If your skill needs live data from another app, pair it with an MCP server: our guide to MCP versus skills explains how the two fit together. For ideas, browse skills for code review or documentation.