How to create a Claude skill (SKILL.md)
A Claude skill is a folder with a SKILL.md file. Where to put it, which frontmatter fields matter and how to write a description Claude matches.
To create a Claude skill, make a folder named after the skill and put a file called SKILL.md in it. The file starts with a short YAML block that names and describes the skill, followed by the instructions Claude should follow. Everything below summarizes Anthropic's documentation as read in November 2026. Nothing here was run or tested.
What a skill is
Anthropic's documentation describes a custom skill as a folder with a SKILL.md file of instructions, and optionally scripts and reference files, that Claude loads when a task matches the skill's description.
Claude does not read every skill in full. According to the skills overview, it first sees each skill's name and description, reads the SKILL.md instructions when a request matches, and opens extra files only when the instructions point to them. For how skills differ from plugins and connectors, see plugins vs skills vs connectors.
The SKILL.md file and its frontmatter
The frontmatter sits between two --- lines at the top of the file. A minimal example from the docs looks like this, one line each:
---name: brand-guidelinesdescription: Apply Acme Corp brand guidelines to presentations and documents, including official colors, fonts, and logo usage.---
The instructions follow as ordinary Markdown.
Which fields are required depends on where the skill will be used, and the two documentation sites differ:
- Skills you upload to Claude. The Create custom skills page says both
nameanddescriptionare required.nametakes lowercase letters, numbers and hyphens only, up to 64 characters, and must match the skill's directory name.descriptioncan be up to 1,024 characters. - Skills in Claude Code. The Claude Code page says all fields are optional and only
descriptionis recommended.namedefaults to the directory name. Ifdescriptionis left out, Claude Code uses the first non-empty line of the content.
Claude Code also reads extra fields such as when_to_use, disable-model-invocation and paths. Take care if the skill will also be uploaded: the docs say claude.ai uploads and the Skills API accept only name, description, license, compatibility, metadata and allowed-tools, and any other field fails the upload with an error.
Where skills live in Claude Code
Where you save the skill decides which sessions load it. The docs list these paths:
- Personal:
~/.claude/skills/<skill-name>/SKILL.md. All your projects on this machine, but not Cowork or cloud sessions, which load the skills enabled for your claude.ai account. - Project:
.claude/skills/<skill-name>/SKILL.md. Sessions in that repository. Commit it so your team gets it too. - Plugin:
<plugin>/skills/<skill-name>/SKILL.md. Wherever the plugin is enabled.
To start a personal skill, the docs give this command:
mkdir -p ~/.claude/skills/summarize-changes
The docs say Claude Code picks up an added or edited skill in the current session, without a restart. One exception they give: if the skills directory itself was created after the session started, run /reload-skills.
How to add supporting files
Keep SKILL.md under 500 lines and move long material into other files in the same folder. The Create custom skills page uses three optional folders:
references/for documentation Claude reads when a step calls for itassets/for templates, images and lookup tablesscripts/for code Claude runs
Mention each file in SKILL.md at the step where Claude should use it, so it knows when to open it. For scripts, the docs say to write the path with ${CLAUDE_SKILL_DIR}, for example python3 ${CLAUDE_SKILL_DIR}/scripts/render.py. They warn against putting API keys or passwords in a skill, because everyone you share it with receives its files.
How to invoke a skill
Describe a task that matches the description and Claude loads the skill itself, or type / and the skill name at the start of your message, such as /summarize-changes.
In Claude Code, two frontmatter fields change this. disable-model-invocation: true means only you can invoke the skill, which the docs suggest for workflows with side effects. user-invocable: false hides it from the / menu so only Claude invokes it.
Inside a plugin, the skill is namespaced as /plugin-name:skill-name. The docs' example: my-plugin/skills/review/SKILL.md becomes /my-plugin:review, and name: fancy in its frontmatter makes it /my-plugin:fancy. Packaging a skill as a plugin is covered in how to build a plugin.
Create a skill in the Claude app
Outside Claude Code, the docs describe uploading the skill as a ZIP file. They state that skills are available on Pro, Max, Ultra, Team and Enterprise plans and need Code execution and file creation turned on under Settings > Capabilities.
- Zip the folder from its parent directory so the folder is the top level of the archive:
zip -r my-skill.zip my-skill/ - Confirm every entry starts with the folder name:
unzip -l my-skill.zip - Upload the ZIP, then turn the skill on at
Customize > Skillsin claude.ai or the desktop app. - Send prompts that should trigger it and revise the description if Claude does not load it.
A SKILL.md at the root of the ZIP is not recognized as a skill. The pages read for this post do not name the exact button used to upload the ZIP.
How to write a good description
The description is the only part Claude reads before deciding to load the skill, so most of the documented advice is about it:
- Say what the skill does and when to use it.
- Include the words a request for that task would naturally use.
- Put the key use case first. In Claude Code the combined
descriptionandwhen_to_usetext is cut at 1,536 characters in the skill listing. - Write in the third person. Anthropic's best-practices page gives "Processes Excel files and generates reports" as the good form.
If Claude still ignores the skill, the docs suggest asking What skills are available? to confirm it is listed. More causes are in plugin skills missing, and ready-made examples are in the skills hub.
Sources
Read more
Claude plugins vs skills vs connectors (MCP), explained
A skill tells Claude how to do a task. A connector gives it access to a service. A plugin packages both. How to tell them apart and which you need.
Plugin installed but skills are missing: what to check
The plugin shows as installed but Claude never uses its skills. The documented causes, in check order.
Claude plugins not working? Every documented fix
Every documented reason a Claude plugin won't install, sync, load or work in Claude, Cowork or Claude Code, with the exact error messages and the fix for each.
The most-starred Claude plugins: November 2026
The ten community Claude plugins in this directory with the most GitHub stars, what each one does, and what to know before installing it. Updated monthly.