Blog
Claude Code skills: how they work and how to write them
What a skill is, the SKILL.md format, where skills live, how Claude picks one, and three skills you can copy, including a pre-PR checklist.
Alex Mercer
Claude Code skills are folders with a SKILL.md file: YAML frontmatter that tells Claude when to use the skill, followed by Markdown instructions that Claude follows when it runs. Claude loads a skill on its own when your request matches the skill's description, and you can run any skill yourself by typing /skill-name.
Skills are the right home for anything you keep pasting into chat: a checklist, a release procedure, the conventions for one part of the codebase. CLAUDE.md loads in every session, but a skill's body loads only when it's used, so a long procedure costs almost nothing until you need it.
Skill details come from Anthropic's skills documentation as of October 12, 2026. For the rest of Claude Code (setup, CLAUDE.md, permissions, daily workflow), start with our guide on how to use Claude Code.
What a Claude Code skill is
A skill is a directory with one required file, SKILL.md, plus any supporting files you want Claude to have on hand. The directory name becomes the command, so a skill at .claude/skills/deploy/SKILL.md runs as /deploy.
Custom commands are now skills. A file at
.claude/commands/deploy.mdand a skill at.claude/skills/deploy/SKILL.mdboth create/deploy. Old command files keep working. Skills add supporting files, control over who can invoke them, and automatic loading.Claude Code skills follow the Agent Skills open standard. Claude Code adds features on top, such as invocation control, running a skill in a subagent and injecting command output into a skill.
Some skills ship with Claude Code. Bundled skills such as
/debug,/loopand/claude-apiare prompt-based, and you run them like any skill you write./runand/verifylaunch your app so Claude can check a change against the running app instead of tests alone.
The SKILL.md format
Every SKILL.md has two parts: YAML frontmatter between --- markers, and Markdown instructions after the closing marker. This is a complete example skill:
Every frontmatter field is optional, but always write a description, because it is what Claude matches your requests against. Claude Code reads frontmatter only when the opening --- is the first line of the file. It also ignores field names it doesn't recognize without reporting an error, so a typo such as disable_model_invocation silently does nothing.
Frontmatter fields you will use
Field | What it does |
|---|---|
| Command name in the |
| What the skill does and when to use it. Claude uses it to decide when to load the skill |
| Extra trigger phrases or example requests, appended to the description |
| Hint shown in autocomplete, such as |
| Named positional arguments, used as |
|
|
|
|
| Tools Claude can use without asking during the turn that runs the skill |
| Model and effort level while the skill is active |
|
|
| Glob patterns. Claude loads the skill automatically only when it works with matching files |
| Hooks registered when the skill is invoked, kept for the rest of the session |
The frontmatter reference lists the rest, including disallowed-tools, background and shell. If you pin a model on a skill, our ranking of the best LLMs for coding on Bug Bench compares models by the bugs found in their code.
Arguments and placeholders
Text after the skill name becomes $ARGUMENTS, so /fix-issue 123 turns "Fix GitHub issue $ARGUMENTS" into "Fix GitHub issue 123". You can also take arguments by position with $0, $1 and so on, or name them in the arguments field and write $issue or $branch. A named argument with no value expands to an empty string.
Skills that ship scripts can use a few variables: ${CLAUDE_SKILL_DIR} is the skill's own directory, ${CLAUDE_PROJECT_DIR} is the project root, and ${CLAUDE_SESSION_ID} is the current session ID.
Injecting live data
!`command` at the start of a line, or after whitespace, runs the command before Claude sees the skill, and the output replaces the placeholder. For multi-line commands, open a fenced code block with ! right after the three backticks. This is how a skill can arrive with the current diff already in it.
A failing command aborts the whole skill. With the default bash shell, any non-zero exit counts as a failure, except exit code 1 from search and comparison commands, which Claude Code treats as a normal result. Append
|| trueto any other command you expect to exit non-zero, such as a check script that exits 1 when it finds problems.Injected commands never prompt for permission. Outside auto mode, a command that your permission rules don't already allow aborts the skill. List the commands in
allowed-toolsto pre-approve them.
Supporting files
Keep SKILL.md under 500 lines and move detail into other files in the same folder:
Link each file from SKILL.md and say what it contains, so Claude knows it exists and opens it only when the task needs it.
Where skills live
Where you save a skill decides who gets it:
Location | Path | Who gets it |
|---|---|---|
Personal |
| You, in every project on this machine |
Project |
| Everyone in the repo, once you commit it |
Nested |
| Sessions working in that part of a monorepo |
Plugin |
| Anyone with the plugin enabled, as |
Enterprise |
| Every user on machines where your organization deploys it |
claude.ai account | Skills enabled on claude.ai | Cowork and cloud sessions, and terminal sessions signed in with that account |
When two skills share a name, enterprise beats personal and personal beats project. A skill also wins over a .claude/commands/ file with the same name, and a skill you write replaces a bundled skill of the same name. Plugin skills never collide with yours, because they carry the plugin's prefix.
A few more loading rules:
In a monorepo, Claude Code loads project skills from the directory where you start it and from every parent up to the repository root. Skills in a subdirectory below that load the first time Claude reads or edits a file there.
Cloud sessions, including Claude Code on the web, don't read
~/.claude/skills/on your machine. Commit the skill to the repo's.claude/skills/, or enable it on your claude.ai account.Claude Code watches skill directories, so adding, editing or removing a skill takes effect in the current session without a restart. If you create a top-level skills directory mid-session, run
/reload-skills.
How Claude decides to load a skill
Claude Code keeps a listing of skill names and descriptions in Claude's context. The full SKILL.md stays on disk until the skill is invoked. When your request matches a description, Claude invokes the skill through its Skill tool, and the rendered content enters the conversation as one message.
Two frontmatter fields decide who can trigger a skill:
Frontmatter | You can run it | Claude can run it | In Claude's listing |
|---|---|---|---|
(default) | Yes | Yes | Name and description |
| Yes | Not on its own | Not listed |
| No | Yes | Name and description |
Whether Claude matches a request to a skill depends on its description, its paths and the listing budget:
Claude matches against
descriptionpluswhen_to_use. The combined text is cut at 1,536 characters in the listing, so put the main use case first.With glob patterns set in
paths, Claude loads the skill automatically only when it works with matching files.The listing gets about 1% of the model's context window. With many skills, Claude Code drops descriptions, starting with the skills you invoke least, and a skill without a description is hard to match. The Skills row in
/contextshows the listing's size, and/skill-doctorreports each skill's cost and how often it's used.
Typing the name yourself works differently. /deploy staging at the start of a message runs the skill directly. The same name later in a sentence, as in "go ahead and /deploy to staging", only gives Claude permission to run it.
Once loaded, a skill's text stays in the conversation, and Claude Code doesn't re-read the file on later turns. When the conversation is compacted, Claude Code re-attaches the most recent invocation of each skill, but keeps only its first 5,000 tokens, within a 25,000-token budget shared by all skills.
To limit which skills Claude can use, add permission rules. Skill(deploy) matches one skill, Skill(deploy *) matches it with any arguments, and a deny rule on Skill turns skills off.
How to write a skill that works
Anthropic's troubleshooting notes come back to the same few failures: a description that doesn't match how people ask, a skill that triggers too often, and rules Claude stops following later in a session. These habits prevent most of them:
Start from repetition. Turn a prompt you keep pasting, or a CLAUDE.md section that has grown into a procedure, into a skill.
Write the description for matching. Lead with what the skill does, then the words people type when they need it, such as "Use when the user asks what changed or wants a commit message." If the skill fires when it shouldn't, make the description narrower.
Decide who presses the button. Set
disable-model-invocation: trueon anything with side effects, such as deploys, commits or messages to other people. Setuser-invocable: falseon background knowledge that isn't an action.Keep the body short and direct. Once loaded, every line costs tokens on every turn. Say what to do rather than narrating how or why.
Write standing instructions. Claude doesn't re-read the file, so "run the tests after every edit" holds up better than "run the tests".
Put the important rules first. After compaction, only the start of a long skill survives.
Move detail out. Keep
SKILL.mdunder 500 lines and put reference material in linked files.Pre-approve only what the skill needs. The
allowed-toolsgrant covers the turn that invokes the skill and clears with your next message. A skill can grant itself broad access, so read theallowed-toolsof skills checked into a repo before you run Claude Code there.Enforce hard rules with hooks. A skill can't guarantee that a rule holds every time. Claude Code runs a hook every time its event occurs, so a must-hold rule belongs there. Our guide to Claude Code hooks covers how to write them.
Test it
A skill that triggers has only been found; it hasn't been shown to help. To check, run a few realistic prompts in a fresh session with the skill on, then again with it set to "off" in the skillOverrides setting, and compare the results. Anthropic's skill-creator plugin automates that loop, including tuning the description, after you run /plugin install skill-creator@claude-plugins-official.
When a skill doesn't trigger, ask Claude "What skills are available?" to confirm it loaded. Run claude plugin validate ~/.claude/skills (or .claude/skills for project skills) to find frontmatter that doesn't parse, or start Claude Code with --debug to see the parse error. Broken YAML doesn't stop /skill-name from working, but Claude can no longer match the description.
Three example Claude Code skills to copy
These are examples. Their syntax follows Anthropic's skills docs, but test each one in your own setup before you rely on it. Save each one as .claude/skills/<name>/SKILL.md in your repo, or under ~/.claude/skills/ to use it everywhere. Swap in your own commands and paths.
1. A pre-PR checklist
AI-written code needs a check before it goes up for review, like any other code. In the latest full week, Claude Code wrote 78.1% of the AI-written code that cubic reviewed, according to Bug Bench. That share covers code reviewed by cubic, not the whole market. Inside Claude Code, the model with the lowest relative bug rate is Claude Fable 5.1 at 1.09 (1.00 is average), statistically tied with Claude Sonnet 5.5 at 1.24. Fable 5.1 is ranked on six weeks of data and Sonnet 5.5 on two. Every model ranked there is above that average. A counted bug is a cubic review finding that a developer upvoted or a coding agent addressed.
This skill has Claude check the branch before you open the pull request. It pulls in the state of the working tree up front, goes through a checklist and reports instead of fixing.
Why it's built this way:
It leaves out
disable-model-invocation, so Claude can reach for it when you ask "is this ready for a PR?", not only when you remember the command.allowed-toolscovers the injected git commands. Outside auto mode, an injected command without a matching allow rule aborts the skill.It reports before fixing. You decide what's worth changing, and the list doubles as notes for the PR description.
To run checks on every commit as well, use a skill named verify. When a skill named verify sits in your personal or project skills at the start of a session, and Claude is allowed to invoke it, Claude Code's commit instructions tell Claude to run it right before each commit, except for changes to docs or tests. This needs Claude Code v2.1.286 or later, and a personal or project skill named verify replaces the bundled /verify that launches your app. Keep that skill to fast, mechanical checks such as lint, types and tests, and leave the judgment items for the pre-PR pass.
A checklist catches what you already know to look for. It doesn't replace a second reader; see our guide to AI code review and a pre-review safety gate for AI-generated code for what comes after it.
2. Open a draft pull request
This skill has side effects, so only you can trigger it. It takes the base branch as an argument.
Run it as /open-pr or /open-pr develop. The allowed-tools grant lasts only for the turn that invokes the skill, so the push and gh pr create run without prompts this time, and your normal permission rules apply again afterwards. The skill uses the GitHub CLI, so gh must be installed and signed in.
3. Team rules that load only where they apply
Reference skills hold knowledge rather than steps. This one carries migration rules, stays out of the / menu, and loads only when Claude works on migration files.
Change the paths glob to where your migrations live. The same pattern fits any area with local rules: API handlers, infrastructure code, a legacy module only two people understand. For more on writing conventions that agents follow, see how to configure coding agents that follow your team's standards.
cubic's skills for Claude Code
cubic's docs list six skills that cubic publishes for coding agents, including Claude Code: run-review, check-pr-comments, cubic-loop, codebase-context, review-patterns and handle-codebase-scan. run-review, for example, reviews your uncommitted changes or current branch through the cubic CLI, then offers to fix what it finds. Our Claude Code review guide walks through a review run with these skills, from the findings to the fixes.
cubic's docs also show installing them in Claude Code as a plugin:
The plugin adds the skills, namespaced commands such as /cubic:run-review, and the connection to cubic's MCP server. Local reviews need the cubic CLI installed and signed in.
Share skills with your team
There are three ways to get a skill to other people:
Commit it. Project skills in
.claude/skills/reach everyone who works in the repo, including cloud sessions that clone it.Package it in a plugin. A plugin can carry skills alongside subagents, hooks and MCP servers, with updates from a marketplace. Our guide to Claude Code plugins covers building and distributing one.
Deploy it through managed settings. Enterprise skills reach every user on machines where your organization deploys them.
FAQ
What is the difference between Claude Code skills and slash commands?
Custom slash commands have been merged into skills. A file in .claude/commands/ and a skill in .claude/skills/ with the same name both create the same /name command, and if both exist, the skill wins. Skills add supporting files, invocation control and automatic loading, so use them for anything new.
How are skills different from CLAUDE.md?
Claude reads CLAUDE.md at the start of every session, so it suits facts Claude always needs, such as build commands, conventions and project layout. A skill's body loads only when it's used. Anthropic's memory docs suggest moving a CLAUDE.md entry into a skill once it becomes a multi-step procedure or only matters for one part of the codebase.
How do skills relate to subagents?
A skill is a set of instructions, while a subagent runs in its own context window with its own system prompt, tool access and permissions. You can combine them: context: fork in a skill's frontmatter runs the skill in a subagent of the type named in agent, such as the built-in Explore. The subagent doesn't see your conversation, so the skill has to stand on its own.
Do Claude Code skills work in claude.ai or other tools?
The format follows the Agent Skills open standard, so it carries over. claude.ai uploads and the Skills API accept only six frontmatter fields (name, description, license, compatibility, metadata and allowed-tools) and reject the rest, and Claude Code features such as command injection don't work there. Skills you enable on your claude.ai account also sync into Claude Code sessions signed in with that account.
Do skills use up context?
Every skill Claude can invoke adds its name and description to the context on every turn, and its full body only when it's used. The listing is capped at about 1% of the context window. Run /skill-doctor to see each skill's cost and how often it's used, then turn off the ones you don't need.
