Skills: Reusable Expertise for Claude

You have probably done this: pasted the same five-step deploy checklist into chat for the third time this week, or re-explained how your team writes API endpoints to a fresh session that has no memory of the last one. A skill is how you stop. Write the procedure down once as a SKILL.md file, and Claude adds it to its toolkit — it reaches for that expertise on its own when the moment calls for it, or you summon it directly with /skill-name.

Anthropic announced Agent Skills on October 16, 2025, and the framing is worth keeping in mind: a skill is a folder of instructions, scripts, and resources that Claude loads only when it needs them. That last clause is the whole trick. A skill can carry a thousand lines of reference material and cost almost nothing until the moment it is relevant.

What a skill actually is

Strip away the features and a skill is a directory with one required file, SKILL.md, that has two parts: YAML frontmatter that tells Claude when to use the skill, and a markdown body that tells Claude what to do once it does. The directory name becomes the command you type. Drop SKILL.md into ~/.claude/skills/changelog/ and you have a /changelog skill, available across every project on your machine.

The mental model that matters: CLAUDE.md is a fact that rides in context every single session whether you need it or not. A skill is a capability that sits dormant until it is summoned. When a checklist or multi-step procedure has outgrown a line in CLAUDE.md, that is the signal to move it into a skill.

Anatomy: frontmatter and body

In the example above, only one frontmatter field is present — description — and that is by design. Every frontmatter field is technically optional, but description is the one field Anthropic recommends you always write, because it is the single thing Claude reads to decide whether the skill is relevant. If you omit it, Claude falls back to the first paragraph of the body, which is rarely as sharp.

Two more fields shape behavior. name sets the display label in skill listings; if you leave it off, it defaults to the directory name. (On the Claude API and claude.ai, where there is no directory, name is required and must be lowercase letters, numbers, and hyphens, max 64 characters, and may not contain the reserved words "anthropic" or "claude".) And allowed-tools pre-approves specific tools so Claude can use them without stopping to ask you — more on that below.

Notice the !git diff HEAD`` line. That is dynamic context injection: Claude Code runs the command and splices its output into the skill before Claude ever reads it. The skill arrives with your actual working-tree diff already inlined, so Claude reasons over real data instead of guessing. This is preprocessing, not something Claude executes — it only sees the finished, rendered prompt.

Progressive disclosure: the three levels

This is why skills scale. A skill loads in stages, and each stage only pays for itself when it is actually used.

The genius is in Level 1. Because only the name and description sit in context at startup — roughly a hundred tokens each — you can install dozens of skills with almost no overhead. Claude knows each one exists and when to use it, but the actual instructions stay on disk. When your request matches a description, Claude reads the SKILL.md body off the filesystem and only then does Level 2 enter the context window. Level 3 goes further still: a skill can bundle a 2,000-line API reference, a database schema, and a Python script, and those cost zero tokens until Claude reads the specific one a task needs. When Claude runs a bundled script via bash, the script's code never enters context — only its output does, which makes a tested script far cheaper and more reliable than regenerating the same logic from scratch every time.

Letting Claude discover and invoke skills

When a session starts, Claude Code injects every available skill's metadata into context. From then on, two paths trigger a skill. You can invoke it explicitly by typing /skill-name. Or Claude can invoke it automatically: when something you ask matches a skill's description, Claude pulls the body in on its own. Both paths can pass arguments — /fix-issue 123 substitutes 123 into the skill's $ARGUMENTS placeholder.

This makes the description the single most important sentence you will write. It is the matching surface. A vague description means Claude never reaches for the skill; an overeager one means it fires when you did not want it. The official guidance is concrete: state both what the skill does and when to use it, and lead with concrete trigger phrases a user would actually say. "Use when the user asks what changed or wants a commit message" gives Claude real anchors. "Helps with git stuff" gives it nothing. If Claude ever ignores a skill you expected it to use, the description is almost always the culprit — add keywords a user would naturally say, confirm the skill is even visible by asking "What skills are available?", and as a fallback invoke it directly with /skill-name. The mirror problem, a skill firing too often, is fixed by making the description more specific or by adding disable-model-invocation: true so only you can trigger it.

Where skills live: personal, project, plugin

Where you put a skill decides who can use it. Personal skills in ~/.claude/skills/<name>/ follow you across every project on your machine — your private toolkit of commit helpers and research routines. Project skills in .claude/skills/<name>/ ship to your whole team through version control, so everyone who clones the repo gets the same /deploy or /review-pr. Plugin skills live in a plugin's skills/ directory and load wherever the plugin is enabled — that is how Anthropic and the community distribute skills as installable packages. (Organizations get a fourth, enterprise scope deployed through managed settings.)

When two skills share a name, the more specific wins by override order: enterprise over personal, personal over project. Plugin skills sidestep conflicts entirely under a plugin-name:skill-name namespace. And project skills don't only load from your starting directory — Claude Code walks up to the repo root and discovers nested .claude/skills/ directories on demand, which is what makes monorepos work cleanly.

Scoping tools with allowed-tools

By default, a skill running its instructions still hits your normal permission prompts every time it wants to run a command. The allowed-tools field smooths that over: list the tools a skill may use, and Claude can use exactly those without asking while the skill is active. A /commit skill might declare allowed-tools: Bash(git add *) Bash(git commit *) Bash(git status *) so it stages and commits in one clean pass.

Read allowed-tools carefully, though, because it is permissive, not restrictive. It does not limit what tools are available — every other tool is still callable, governed by your normal permission settings. It only pre-approves the ones you list. (To remove a tool from the pool while a skill runs, that is a different field, disallowed-tools.) The security consequence is real: a project skill checked into someone else's repo can grant itself broad tool access, and that grant only takes effect after you accept the workspace trust dialog. Review project skills before you trust a repository — treat installing a skill like installing software, and only use skills from sources you trust.

When to reach for a skill

Skills are not a replacement for CLAUDE.md, hooks, or subagents — they sit alongside them, and the art is matching the tool to the job. Reach for a skill when you have a repeatable procedure or body of expertise — a deploy checklist, your API conventions, a research routine — that you want available on demand without paying for it every session. Reach for CLAUDE.md when you have a stable fact every session needs, like the build command or project layout. And reach for a hook when something must happen with zero exceptions, because a skill, like CLAUDE.md, is guidance Claude chooses to follow, not an enforcement layer.

The honest failure mode: a skill that loaded once can stop influencing behavior if Claude starts preferring other approaches mid-session. The content is usually still there — strengthen the description and instructions so Claude keeps choosing it, re-invoke it after a compaction if the session has grown long, or move the truly non-negotiable part into a hook. Used well, a small library of sharp skills turns Claude from a capable generalist into a specialist who already knows how your team ships software.

Running a skill in its own subagent

Everything so far assumed a skill runs inline — its rendered body drops into your main conversation and shares all the context that came before. Two frontmatter fields flip that. [V] Set context: fork and the skill runs in a forked subagent context instead: the SKILL.md content becomes the prompt that drives an isolated agent, and that agent does not have access to your conversation history. [V] The companion field agent names which subagent type executes it — a built-in Explore, Plan, or general-purpose, or any custom subagent you have defined in .claude/agents/. Omit agent and it defaults to general-purpose.

The point of forking is to keep heavy, self-contained work off your main context window. A research sweep or a PR summary can read dozens of files, burn through tool calls, and return just its conclusion — the intermediate churn never touches the session you are working in. [V] The official docs are blunt about one constraint, though: context: fork only makes sense for skills that carry explicit instructions. A skill that is pure reference material ("use these API conventions") gives the subagent guidelines but no actionable task, so it returns without meaningful output. [P] The tell is whether your skill body reads as a command or as background knowledge — fork the former, leave the latter inline.

One subtlety worth internalizing: [V] the built-in Explore and Plan agents skip CLAUDE.md and git status at startup to stay lean, so a skill forked with agent: Explore sees only its own SKILL.md content plus that agent's system prompt — nothing from your project memory. general-purpose and custom agents still load CLAUDE.md. Pick the agent type to match how much project context the task actually needs.

Hiding a skill without touching its SKILL.md

Sometimes the skill you want to quiet is not yours to edit — it is checked into a shared project repo, or it arrives from an MCP server. [V] The skillOverrides setting solves this from your own settings.json instead of the frontmatter. It is a map keyed by skill name, where each value is one of four states, and the /skills menu writes it for you: highlight a skill, press Space to cycle states, then Enter to save it to .claude/settings.local.json. [V] A skill that is absent from the map is treated as on. [V] skillOverrides does not apply to plugin skills — manage those through /plugin instead.

This is the precise lever for the "skill descriptions are getting cut short" problem: drop a low-priority skill to name-only and it still appears in the / menu but stops spending description budget that your everyday skills need.

The skills that ship in the box

You do not have to write a skill to use one. [V] Claude Code bundles a set of prompt-based skills that are available in every session unless you disable them with the disableBundledSkills setting. The distinction from built-in commands matters: most built-ins run fixed logic directly, but a bundled skill hands Claude detailed instructions and lets it orchestrate the work with its own tools. You invoke them the same way as any other skill — type / then the name. [V] In the commands reference they are marked Skill in the Purpose column to set them apart from ordinary built-ins.