Skills · Build your own
Write a skill from scratch
The naming rules are fussy and a bad description means the skill never fires, so this checks both as you type. If you just want a finished one, take a ready-made skill instead.
It all runs in your browser. Nothing you type leaves the page.
Skill
More fields All optional. Tools, who can invoke it, model, paths, licence, metadata.
Folders in the zip Each one gets a README.md saying what belongs there, so the folder survives the zip.
SKILL.md
Where to put it
Just for you, every project: ~/.claude/skills/<name>/SKILL.md
One project, committed with the repo: .claude/skills/<name>/SKILL.md
In a plugin: <plugin>/skills/<name>/SKILL.md, invoked as /plugin-name:name. Plugins get shared through a marketplace: /plugin marketplace add owner/repo, then /plugin install name@marketplace.
On claude.ai: turn on code execution in Settings → Capabilities, then upload the zip at Customize → Skills.
What goes in SKILL.md frontmatter?
A skill is a folder with a SKILL.md in it: YAML frontmatter between --- lines, then a markdown body. Every host loads the frontmatter at startup and only reads the body once the skill fires. The rules come from the Agent Skills spec, which Claude Code extends.
| Field | Required | Rule |
|---|---|---|
name | Yes in the spec and the API. Claude Code falls back to the folder name. | 1 to 64 characters; lowercase letters, digits and hyphens; no leading, trailing or double hyphen; must equal the folder name. claude.ai and the Skills API also reject the words anthropic and claude. |
description | Yes | 1 to 1,024 characters in the spec, and claude.ai's own upload guide says 200. No XML tags, third person. Say what the skill does and when to use it: this line is the trigger. Claude Code shows description plus when_to_use truncated at 1,536 characters. |
allowed-tools | No | Tools pre-approved while the skill runs. Space-separated in the spec; Claude Code also takes commas or a YAML list. Patterns such as Bash(git:*) work. |
license | No | A licence name or the name of a bundled licence file. |
compatibility | No | Up to 500 characters of environment requirements. Most skills leave it out. |
metadata | No | A map of string keys to string values for your own tooling. Claude does not act on it. |
argument-hint | Claude Code only | Hint shown in the / autocomplete, e.g. [issue-number]. |
disable-model-invocation | Claude Code only | true means Claude never loads the skill on its own; only /name runs it. Default false. |
user-invocable | Claude Code only | false hides the skill from the / menu so only Claude uses it. Default true. |
model | Claude Code only | Model while the skill runs, same values as /model, or inherit. |
context, agent | Claude Code only | context: fork runs the skill in a subagent; agent picks which subagent type. |
paths | Claude Code only | Glob patterns. The skill auto-loads only when Claude is working on matching files. |
when_to_use, effort, hooks, disallowed-tools, arguments, shell, background | Claude Code only | See the Claude Code skills reference. Not offered in the form above. |
Portability is the thing to watch. Claude Code accepts every field. A claude.ai upload, the Skills API and package_skill.py take only the six spec fields and reject anything else with Unexpected key(s) in SKILL.md frontmatter. We flag your file "Claude Code only" the moment it uses one.
The body has no format rules at all. Keep it under 500 lines, link supporting files with relative paths one level deep, and for every script say whether Claude should run it or read it.
SKILL.md vs CLAUDE.md vs AGENTS.md
CLAUDE.md is memory. It's read at the start of every conversation and costs you context on every turn. SKILL.md is a procedure: only its name and description load at startup, and the body arrives when the description matches the task or you type /name. Claude Code's docs suggest moving a chunk of CLAUDE.md into a skill once it's grown into a checklist.
AGENTS.md plays the CLAUDE.md role for Codex, Cursor, Copilot and others, with no on-demand loading. A CLAUDE.md can pull it in with an @AGENTS.md line.
How does Claude decide to use a skill?
At startup, every skill's name and description go into the system prompt. Claude matches your request against those descriptions and reads the SKILL.md that fits. Linked files open only when a step needs them, so a big skill costs almost nothing until you use it.
Which means the description does all the work. Write it in third person, name the task and the phrases someone would actually say, and say when not to use it if a neighbouring skill overlaps. Put the key use case first: Claude Code gives the listing about 1% of the context window, and when that overflows it shortens the descriptions of the skills you use least.
Where do I put a SKILL.md file?
| Scope | Path | Applies to |
|---|---|---|
| Personal | ~/.claude/skills/<name>/SKILL.md | Every project on the machine |
| Project | .claude/skills/<name>/SKILL.md | That repository; commit it to share |
| Plugin | <plugin>/skills/<name>/SKILL.md | Wherever the plugin is enabled, as /plugin:name |
| claude.ai | Uploaded zip, folder at the root | Your account, once code execution is on |
The command name comes from the folder, so .claude/skills/deploy-staging/SKILL.md gives you /deploy-staging. If two levels define the same name, enterprise beats personal and personal beats project. Plugin skills are namespaced, so they never collide.