How to Create a Claude Skill

To create a Claude skill, make a folder, put a file named SKILL.md in it, and write two things in that file: a short description of when the skill should be used, and the instructions Claude should follow. Save the folder under ~/.claude/skills/ and Claude Code will pick it up. The rest is refinement: a better description, supporting files, and testing.

Create the folder and file

In Claude Code, personal skills live in your home directory and apply to every project.

mkdir -p ~/.claude/skills/summarize-changes

Then save a file at ~/.claude/skills/summarize-changes/SKILL.md:

---
name: summarize-changes
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---

Run `git diff HEAD` and read the output.

Summarize the changes in two or three bullet points, then list any risks
you notice, such as missing error handling, hardcoded values, or tests
that need updating. If the diff is empty, say there are no uncommitted
changes.

This example is adapted from the one in Anthropic's Claude Code documentation. To make the skill part of a project instead, put the folder under .claude/skills/ in the repository and commit it.

Fill in the frontmatter

The block between the --- lines is YAML frontmatter. The open standard at agentskills.io defines six fields, of which two are required.

Field	Required	Rule
name	Yes	Up to 64 characters; lowercase letters, numbers and hyphens; must match the folder name
description	Yes	Up to 1,024 characters; what the skill does and when to use it
license	No	A license name or a reference to a bundled license file
compatibility	No	Environment requirements, up to 500 characters
metadata	No	Extra key-value pairs, such as author and version
allowed-tools	No	Tools the skill may use without asking; marked experimental

Claude Code adds fields of its own. Two control who can run the skill: disable-model-invocation: true means only you can invoke it, and user-invocable: false means only Claude can. Another, context: fork, runs the skill in a separate subagent.

If you plan to upload the skill to claude.ai or the API, keep to the six standard fields. Uploads reject a file with any others.

Write a description that triggers

The description does most of the work. At startup Claude sees only each skill's name and description, and decides from those whether a skill is relevant.

The specification gives a good and a poor example:

# Good
description: Extracts text and tables from PDF files, fills PDF forms, and merges multiple PDFs. Use when working with PDF documents or when the user mentions PDFs, forms, or document extraction.

# Poor
description: Helps with PDFs.

Three habits help:

• Say both what the skill does and when to use it.
• Include the words a person would type when asking for that task.
• Put the main use case first, because long descriptions can be shortened when many skills are installed.

Write the instructions

The body is plain Markdown, and the specification places no restrictions on its format. It suggests step-by-step instructions, examples of inputs and outputs, and common edge cases.

Two points from Anthropic's documentation are worth following:

• Keep it concise. Once a skill loads, its content stays in the conversation for later turns, so every line has a recurring cost. State what to do.
• Write standing instructions. Claude Code does not re-read the file on later turns. "Run the tests after every edit" holds up better over a long task than "Run the tests".

Add supporting files

When the instructions grow, split them. Put detailed material in separate files and reference them from SKILL.md so Claude knows what each contains and when to open it.

my-skill/
├── SKILL.md
├── reference.md
├── examples.md
└── scripts/
    └── helper.py

Reference files are read only when needed. Scripts are run, and only their output enters the conversation. The specification recommends keeping SKILL.md under 500 lines and file references one level deep.

Test it

Open a project, start Claude Code, and try both ways of triggering the skill:

1. Ask for the task in natural words, such as "What did I change?"
2. Call the skill directly with /summarize-changes.

If the direct call works and the natural request does not, the description needs work.

Seeing a skill trigger only tells you Claude found it. To know whether it helps, Anthropic recommends a baseline comparison: run a few realistic prompts in a fresh session with the skill available, run them again with it turned off, and compare the output.

If you write skills for other agents as well, the skills-ref tool from the agentskills project checks that the frontmatter is valid:

skills-ref validate ./my-skill

Use skill-creator

You do not have to do all of this by hand. Anthropic publishes a skill called skill-creator that drafts new skills, improves existing ones and measures how they perform. In Claude Code it installs as a plugin from the official marketplace:

/plugin install skill-creator@claude-plugins-official

According to the documentation, it stores test cases with the skill, runs each one in a clean subagent, grades the results, compares runs with and without the skill, and proposes description edits when the skill activates on the wrong requests.

For a bare template, the skills CLI has a command that creates a starter SKILL.md:

npx skills init my-skill

See the skill-creator page for more on that skill.

Share it

A skill is a folder, so sharing it is a matter of where you put the folder.

• With your team: commit .claude/skills/ to the repository.
• With other projects: package it in a plugin, in a skills/ directory.
• With everyone: publish it in a public repository. Anyone can then install it with npx skills add owner/repo.

For worked examples to model yours on, see Claude skills examples.