How to Create a Claude Skill: SKILL.md Step by Step

Here is how to create a Claude skill: make a folder, add a SKILL.md file with a name and a description, write the instructions you want the agent to follow, and then test it with real prompts until it triggers when it should. The whole first version can fit in one file. This guide walks through each step in order, using Claude Code for the commands and noting where other agents differ.

You will end up with a working skill in ~/.claude/skills/, a way to check that it loads, a method for improving its description, and a repository other people can install from. If you want the definition first, what Claude skills are covers the concepts.

Before you start: pick one job

A good skill does one job and does it the same way each time. Look for something you have explained to the agent more than twice: a commit-message style, a release checklist, a way of reviewing migrations, a report format. If you catch yourself pasting the same block of instructions into new chats, that block is a skill waiting to be written.

Skip tasks that apply to every request in a repository. Rules like "use tabs" or "run the linter before committing" belong in an always-loaded instruction file, and the topic page for agent instructions lists skills that help maintain those files. Keep skills for procedures you want loaded only when relevant.

Step 1: create the folder and the file

In Claude Code, personal skills live in ~/.claude/skills/<skill-name>/SKILL.md, and project skills live in .claude/skills/<skill-name>/SKILL.md inside a repository. Start with a personal one while you experiment:

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

The open specification asks for a lowercase name of up to 64 characters, made of letters, numbers and single hyphens, which matches the folder name. Use the same name for both and you avoid the most common mismatch.

Step 2: write the frontmatter and instructions

The Claude Code documentation uses a short example that is worth copying as a first test. Save this as SKILL.md in the folder:

---
description: Summarizes uncommitted changes and flags risks
---

## Current changes

!`git diff HEAD`

## Instructions

Summarize the changes above in 2-3 bullet points. List any risks:
missing error handling, hardcoded values, tests needing updates.
If the diff is empty, say there are no uncommitted changes.

Two details are worth knowing. In Claude Code every frontmatter field is optional and name defaults to the folder name, but the open specification requires both name and description, so include both if you want the skill to work in other agents. And the line starting with an exclamation mark and a backtick is Claude Code's dynamic context injection: the command runs before the content reaches Claude, and its output replaces the placeholder. That feature is specific to Claude Code, so leave it out of skills meant for other tools.

Write the body as instructions to a capable colleague. Say what to do, in what order, what the output should look like, and what to do when something is missing. Explain the reason behind a rule when it is not obvious, since the agent can then handle cases you did not list.

Step 3: write a description that triggers

The description decides whether the agent ever opens your skill, so spend more time on it than on any other line. The specification asks for a description of 1 to 1,024 characters that says both what the skill does and when to use it, with the keywords a user is likely to say. Its own examples contrast a good one with a poor one:

• Poor: Helps with PDFs.
• Better: 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.

Claude Code lets you add a separate when_to_use field. It is appended to the description, and the two together are cut off at 1,536 characters in the skill listing, so put the main use case first. If a skill fires too often, narrow the wording or add disable-model-invocation: true. If it never fires, add the phrases people actually type.

Step 4: add scripts and references when they help

Once the main file works, move detail out of it. The specification suggests three optional folders:

• scripts/ for code the agent runs, written to be self-contained with clear error messages
• references/ for longer documents the agent reads on demand, kept focused so each file costs little context
• assets/ for templates, images and lookup data

Link to these from SKILL.md with relative paths, and keep references one level deep so the agent does not chase a chain of files. Both the specification and the Claude Code documentation recommend keeping SKILL.md under 500 lines.

In Claude Code you can point to a bundled script with ${CLAUDE_SKILL_DIR}, which expands to the folder that holds SKILL.md. You can pre-approve that one script in allowed-tools so it runs without a prompt each time. Pre-approve narrowly: a rule that matches a single script is much safer than one that matches a whole shell.

Step 5: test that it loads and triggers

Start Claude Code and check three things in order.

1. Run /skills and confirm your skill appears with the description you wrote.
2. Type /summarize-changes (or your skill's name) to run it directly. This bypasses auto-detection, so it tells you whether the instructions work.
3. Ask a natural question such as "what did I change?" without the slash command. This tests whether the description triggers the skill.

Claude Code watches the skill folders, so edits to an existing SKILL.md apply in the running session. If you created a top-level skills folder that did not exist when the session started, run /reload-skills. If a skill is missing, check that the file is named exactly SKILL.md and that the opening --- is the first line. The documentation also mentions claude plugin validate .claude/skills for finding parse errors in recent versions, and the specification's reference library offers skills-ref validate ./my-skill to check names and frontmatter against the standard.

Step 6: use the skill-creator skill to iterate

You can build all of this by hand, or you can let an agent run the process. The official Skill Creator skill, published by Anthropic under Apache-2.0, guides an agent through drafting a skill, testing it on sample prompts, reviewing results with you and tuning the description. The directory's automated check marks it as passing.

From its own SKILL.md, the process runs like this:

1. It interviews you about what the skill should do, when it should trigger and what the output looks like.
2. It writes the skill and saves two or three realistic test prompts to an evals/evals.json file.
3. It runs each prompt twice in parallel subagents, once with the skill and once without, then grades the outputs against assertions.
4. It opens a review viewer so you can leave feedback, then revises the skill and reruns the prompts as a new iteration.
5. It generates a set of should-trigger and should-not-trigger queries and runs a loop that optimizes the description.
6. It packages the result as a .skill file with a bundled script.

Skill Creator is heavier than a hand-written first draft, and it uses subagents to run the comparisons, so it makes sense once your skill is more than a few lines. Other options in the skill authoring topic take a lighter approach: Skill Creation Guide focuses on keeping skills concise, and Skill Release Gate checks a bundle for structure, trigger quality and safety before release. The skills CLI also has npx skills init [name], which the tool's documentation lists as the command for creating a new skill.

Step 7: publish the skill on GitHub

Publishing is a normal repository push. Put your skill folder in a public repository, include a licence file, and consider setting the optional license field in the frontmatter. A layout such as skills/summarize-changes/SKILL.md lets one repository hold several skills.

Others can then install it with the tools covered in how to add skills to Claude Code:

npx skills add your-name/your-repo --skill summarize-changes -a claude-code
gh skill install your-name/your-repo summarize-changes --agent claude-code

Both commands come from tools documented elsewhere, the skills CLI and GitHub CLI, so check each tool's own help for current options. For the Claude apps on the web and desktop, users instead zip the folder and upload it, and Anthropic's docs say a skill name there cannot contain the reserved words "anthropic" or "claude". A name such as summarize-changes avoids that problem everywhere.

Before you publish, read your own skill the way a stranger would. Remove personal paths and tokens, make sure every script is something you would be comfortable having read aloud, and state requirements such as Python or network access, either in the body or in the optional compatibility field, which the specification caps at 500 characters.

A short checklist before you call it done

• The folder name matches the name field, in lowercase with hyphens.
• The description says what the skill does and when to use it, with the main trigger first.
• SKILL.md is short, and long material sits in references/.
• You ran the skill by name and by natural prompt, and both worked.
• Scripts are readable, documented and free of secrets.
• The repository has a licence and a README that names the agents you tested.

Once the skill is live, the SKILL.md format reference is the page to keep open for field names and limits.