A Claude Code skill is a folder with a SKILL.md file: YAML frontmatter that says when to use it, then the instructions Claude follows. Claude loads it when your request matches its description or you type /skill-name, and .claude/skills/ shares it with the repo.
A skill is a SKILL.md file of instructions, plus any scripts, templates or reference files kept in the same folder. Claude uses it when your request matches its description, and you can run it yourself as /skill-name. Skills follow the open Agent Skills standard, which Codex skills use too.
Custom slash commands are now skills. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy, and if both exist the skill wins. The built-in commands are on Claude Code commands.
CLAUDE.md loads into every session, while a skill's body loads only when it is used, so a long procedure costs little until you need it. A hook runs every time its event fires, while a skill runs when Claude or you decide it fits.
Where Claude Code skills live
Each skill is a folder with a SKILL.md inside, and the folder's location decides who gets it. When two skills share a name, enterprise beats personal and personal beats project; plugin skills never clash, because they carry the plugin's name. Claude Code also reads .claude/skills/ in every parent folder up to the repository root, and picks up SKILL.md edits without a restart.
Skill locations in Anthropic's skills docs, read October 5, 2026.
Location
Path
Who gets it
Personal
~/.claude/skills/<name>/SKILL.md
You, in every project on this machine
Project
.claude/skills/<name>/SKILL.md
Everyone who clones the repository
Nested
<subdir>/.claude/skills/<name>/SKILL.md
Sessions started in that folder, or once Claude works on a file there
Plugin
<plugin>/skills/<name>/SKILL.md
Anyone with the plugin enabled, as /plugin-name:name
Enterprise
.claude/skills/<name>/SKILL.md in the managed settings directory
Every user on machines your organization manages
SKILL.md format, with a working example
A SKILL.md is YAML frontmatter between two --- lines, then Markdown instructions. The first --- must be the file's first line, or Claude Code reads the whole file as instructions. Every field is optional, and description is the one Anthropic recommends.
Claude Code reads more fields than the Agent Skills standard, which has six: name, description, license, compatibility, metadata and allowed-tools. Keep to those six when the skill must also work in claude.ai or the Skills API, which reject any other field.
This skill reviews the current branch. Its ! line runs before Claude reads the skill and pastes in the diff, and allowed-tools lets that git command run without a prompt:
.claude/skills/review-pr/SKILL.md
---
name: review-pr
description: Reviews the current branch against main for missing tests, risky changes and unclear names. Use when the user asks for a review before opening a pull request.
allowed-tools: Bash(git diff *)
---
## The change
!`git diff main...HEAD`
## Instructions
List up to five problems, most severe first. For each one, name the file
and line, say why it matters and suggest the fix. If the diff is empty,
say there is nothing to review and stop.
Frontmatter fields, and the placeholder for bundled scripts, in Anthropic's skills docs.
Field or placeholder
What it does
name
The command you type. Defaults to the folder name
description
What the skill does and when to use it: Claude matches requests against it. With when_to_use, cut at 1,536 characters
disable-model-invocation: true
Only you can run it, by typing /name
user-invocable: false
Hidden from the / menu: only Claude runs it
allowed-tools
Tools Claude may use without asking during the turn that runs the skill, such as Bash(git diff *)
model, effort
Model and effort level while the skill runs
context: fork
Runs the skill in a subagent (agent picks which), which doesn't see your conversation
paths
Globs: Claude loads the skill on its own only for matching files
hooks
Hooks that stay on for the rest of the session once the skill runs
${CLAUDE_SKILL_DIR}
In the body: the skill's folder, for running a bundled script
How Claude decides to use a skill
Skills load in three steps, which Anthropic calls progressive disclosure. That is why the description matters more than anything else in the file:
At startup Claude sees only each skill's name and description, about 100 tokens a skill. The whole listing gets 1% of the context window; past that, the least-used skills lose their descriptions and Claude can't match them.
When a request matches, or you type /name at the start of a message, the SKILL.md body loads and stays in the conversation. Claude Code doesn't re-read the file later, and after compaction it keeps the first 5,000 tokens of each skill.
Files the skill links to are read only when needed, and a bundled script runs without its code entering context: only its output does. Anthropic suggests keeping SKILL.md under 500 lines, with reference files linked one level deep.
Why a skill doesn't trigger, and other mistakes
Treat a skill from someone else as code. Claude Code applies its allowed-tools even in a folder you haven't trusted, and Anthropic warns that a malicious skill can exfiltrate data.
When a skill misbehaves, /skills shows what loaded and claude --debug logs frontmatter errors. The usual causes:
Skill problems and their fixes, from Anthropic's skills and configuration-debugging docs.
Symptom
Cause and fix
Missing from /skills
The file is .claude/skills/name.md. Use a folder: .claude/skills/name/SKILL.md
/name works, but Claude never picks it
YAML that doesn't parse loads with no description. claude plugin validate .claude/skills finds it
A field has no effect
Names must match exactly, hyphens included; unknown fields are ignored without an error
Some skills never trigger
Too many skills, so descriptions were dropped. /doctor estimates the listing's size and /skill-doctor shows each skill's use
Aborts before Claude sees it
A ! command exited non-zero. Append || true when that is expected
An installed skill is not a used one. In one engineer's 323 Claude Code sessions (September 2 to October 3, 2026), a skill loaded in 49 (15%). Thirteen skills loaded 58 times: two browser-automation skills made up 25 of them, and the Stripe plugin, enabled the whole time, used none of its 10 skills or its MCP tools.
Zest's Claude Code plugin records every Skill call and every SKILL.md a session loads, from project, personal and plugin folders. The AI Stack view lists each engineer's skills next to their models and agents, so a lead sees which skills spread across the team and which stay on one laptop. More on Claude Code usage.
An engineer's Plan Stack in Zest
TRY IT ON YOUR TEAM
See what your team ships with AI.
Starter is free (3 seats, no credit card). Pro is $49 a month with 5 seats and Max is $149 a month with 10 seats — priced per workspace, not per engineer, with extra seats at $19 a month.
The file that defines a Claude Code skill: YAML frontmatter, where description is the field Anthropic recommends, then Markdown instructions. It sits in a folder named after the skill, next to any scripts or reference files the skill uses.
How do I share a Claude Code skill with my team?+
Commit it under .claude/skills/ so everyone who clones the repository gets it. For several repositories, package it in a plugin and publish the plugin through a marketplace your team adds once.
Can I stop Claude from running a skill on its own?+
Yes. disable-model-invocation: true in the skill's frontmatter makes it manual-only: it runs when someone types /skill-name. user-invocable: false does the opposite and leaves it to Claude.
Do I need to restart Claude Code after editing a skill?+
No. Claude Code watches the skill folders and picks up SKILL.md changes in the running session. Run /reload-skills only after creating a skills folder that didn't exist when the session started.
