How to Create a Claude Skill
Updated September 17, 2026
A Claude skill is a folder holding a SKILL.md file that teaches Claude a task you keep repeating. To create a Claude skill you need no code: a folder, a short file with two required fields, and a test. This guide covers the five steps, with the rules from the published format, and points to the deeper guides where a step needs one.
The short answer
Five steps, in order. Each is expanded below.
- Pick one task you explain to Claude more than a few times a month.
- Make a folder named after the skill: lowercase words joined by hyphens.
- Write SKILL.md inside it: a name, a description that says what the skill does and when to use it, then the instructions.
- Test the trigger by asking for the task in your own words and checking the skill loads.
- Share it by committing the folder, packaging it as a plugin, or uploading a zip to claude.ai.
Step 1: Pick a task worth a skill
Skills earn their keep on procedures: a release-notes format, a review checklist, a migration sequence, a report template. Anthropic's own guidance is to notice what context you keep retyping in conversation, then capture exactly that. Facts and conventions that apply to every conversation belong in CLAUDE.md instead, which is always loaded; a skill loads only when triggered, so it can be longer without costing anything until it is used.
Before writing anything, jot down three requests you would expect the skill to handle. Anthropic's authoring guide calls this building evaluations first, and the reason is practical: you will use those three requests in step 4 to check that the skill triggers and does what you meant.
Step 2: Make the folder
The folder name is the skill's name, and the specification requires the name field inside SKILL.md to match it. Names are 1 to 64 characters of lowercase letters, numbers, and hyphens, with no leading, trailing, or doubled hyphens. Anthropic additionally reserves the words “anthropic” and “claude”, so claude-helper is rejected. Gerund forms such as writing-release-notes or reviewing-pull-requests read well and are what Anthropic's guide suggests.
Where the folder goes depends on where you use Claude. In Claude Code, .claude/skills/writing-release-notes/ inside a project makes the skill available to everyone who clones the repo, and ~/.claude/skills/ makes it available to you in every project. For claude.ai the folder is zipped and uploaded. How to install a Claude skill covers every location.
Step 3: Write SKILL.md
The file opens with YAML frontmatter between two lines of three dashes, then Markdown instructions. Only two fields are required:
| Field | Rule | Why it matters |
|---|---|---|
| name | Matches the folder; 1 to 64 chars; a-z, 0-9, hyphens | How the skill is listed and invoked |
| description | 1 to 1024 chars, no XML tags, third person, says what the skill does and when to use it | Claude reads every skill's description at startup and matches your request against it |
The description carries the most weight in the whole file. Claude loads only names and descriptions when a session starts, and reads the full SKILL.md after a request matches one, so a vague description means a skill that never fires. Anthropic's example of a good one: “Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.” Its example of a bad one: “Helps with documents.”
Below the frontmatter, write for a reader who is already capable. Step-by-step instructions, an example of the input and the output you want, and the edge cases that catch people are the three sections the specification recommends. Keep the body under 500 lines. How to write a SKILL.md file covers the wording, how to structure a SKILL.md file covers sections and supporting files, and the SKILL.md format explained lists every field.
If a blank file is the obstacle, the SKILL.md Generator drafts one from a plain description and checks the frontmatter against these rules as you edit. Treat what it produces as a first draft: read it, correct anything it assumed, and only then save it.
Step 4: Test that it triggers
Ask for the task using one of the three requests from step 1, phrased the way you naturally would. In Claude Code the skill folders are watched, so a new or edited skill is picked up within the session without a restart, and typing /skills lists everything Claude can see along with its description. If the skill does not load, the description is almost always the reason: add the words a real request would contain.
Then check the result, not just the trigger. Did Claude follow the steps in order? Did it skip a check you consider essential? Anthropic's guide suggests fixing that by making the rule more prominent or the wording firmer, and re-testing. It also recommends testing with each model you plan to use, since a skill that is enough for a larger model may need more detail for a smaller one.
Step 5: Share or install it elsewhere
A project skill is shared by committing the folder. Teammates who clone the repository get it on their next session. For wider distribution, Claude Code plugins bundle skills and are installed with /plugin install name@marketplace, after which the skill is invoked as /plugin-name:skill-name.
For claude.ai, zip the folder and upload it under Settings, on a plan with code execution enabled. For the API, upload it through the Skills endpoints, where it becomes available to the whole workspace. One rule matters here: only the six fields in the specification (name, description, license, compatibility, metadata, allowed-tools) are accepted by claude.ai and the API. Claude Code accepts extra fields such as model and paths, and a file containing them fails to upload elsewhere. Skills also do not sync between surfaces; each is uploaded separately.
Three ways to create a skill, compared
| Method | Best for | What you still have to do |
|---|---|---|
| Write it by hand | Short procedural skills where you know the steps | Everything, but the file is small |
| Ask Claude in conversation | Turning a task you just completed together into a skill; claude.ai also offers a create-with-Claude flow under its Skills settings | Review for padding: ask Claude to remove explanations it already knows |
| Use a generator | Getting a correctly formatted first draft from a description | Read every line; correct assumptions; test as in step 4 |
Common questions
- Do I need to know how to code to create a Claude skill?
- No. A skill is a folder with a Markdown file. Scripts are optional, and most skills are instructions only. The rules you must follow are about the name and description fields, and both are plain text.
- What is the difference between a skill and CLAUDE.md?
- CLAUDE.md is always in context and holds conventions and facts that apply to all work. A skill loads only when its description matches a request or you invoke it by name, so it suits multi-step procedures. Anthropic's rule of thumb: when a CLAUDE.md section grows into a procedure, move it to a skill.
- Why does my skill not trigger?
- Usually the description. It must say what the skill does and when to use it, in third person, with the words a real request would contain. Also check the folder name matches the name field and the frontmatter starts on line one. In Claude Code, /skills shows whether the skill loaded at all.
- Can one skill work in Claude Code and claude.ai?
- Yes, if the frontmatter uses only the six fields in the specification. Fields that Claude Code alone understands, such as model, effort, paths, or context, cause the file to be rejected when uploaded to claude.ai or the API.
- How long should a skill be?
- Under 500 lines in SKILL.md, per both the specification and Anthropic's guide. Longer material goes into separate files in the same folder that the SKILL.md points to, so Claude reads them only when a task needs them.
Try it yourself
These live under Developer tools, alongside the rest of the claude skills & skill.md guides on the guides page.