Claude Code skills: how to add and install them, and how Claude picks one

A Claude Code skill is a folder with a SKILL.md file in it: a description that tells Claude when the skill applies, and instructions Claude follows when it does. Claude loads a skill on its own when your request matches the description, or you run it yourself as /skill-name. Custom slash commands are now skills.

What Claude Code skills are

A skill is Markdown that Claude reads only when it needs it. Anthropic's docs describe two kinds:

• Reference content: conventions, a style guide, your database schema. Claude applies it alongside your conversation.
• Task content: step-by-step instructions for one action — a deploy, a commit, a release. Usually something you run as /deploy rather than something Claude starts on its own.

Claude Code ships bundled skills too, among them /code-review, /batch, /debug, /loop and /claude-api. They are prompts that Claude carries out with its tools; most built-in commands, such as /compact, run fixed logic instead. Skills follow the Agent Skills open standard; Claude Code adds fields of its own on top.

How to add skills to Claude Code

Make a folder named after the skill and put a SKILL.md in it. This is Anthropic's own first example, a skill that summarizes your uncommitted changes:

$ mkdir -p ~/.claude/skills/summarize-changes

---
description: Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff.
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks you notice such as missing error handling, hardcoded values, or tests that need updating. If the diff is empty, say there are no uncommitted changes.

The !-prefixed line runs before Claude sees the skill, so the current diff arrives inlined. Ask "What did I change?" and Claude loads the skill, or type /summarize-changes.

Where you save it decides which sessions load it:

• Personal: ~/.claude/skills/<name>/SKILL.md — all your projects on this machine.
• Project: .claude/skills/<name>/SKILL.md — sessions in this repository. Commit it and your team gets it.
• Plugin: <plugin>/skills/<name>/SKILL.md — wherever the plugin is enabled, as /plugin-name:skill-name.
• Your claude.ai account: skills enabled there sync to terminal sessions signed in with that account.

The command name is the folder name, or the name field when you set one. When personal and project skills share a name, the personal one runs. Claude Code watches these folders, so a new or edited skill works in the running session; a top-level skills folder created mid-session needs /reload-skills. Keep SKILL.md under 500 lines and move long reference material into files next to it, linked from SKILL.md.

SKILL.md frontmatter

Every field is optional; Anthropic recommends description. A field name Claude Code does not recognise is ignored without an error, and the frontmatter is read only when the opening --- is the file's first line.

Text after the skill name becomes $ARGUMENTS: /fix-issue 123 turns "Fix GitHub issue $ARGUMENTS" into "Fix GitHub issue 123".

Claude Code skills marketplace: install skills from a plugin

Skills someone else packaged come in plugins: a folder of skills, subagents, hooks and MCP servers that loads as one unit. A marketplace is a catalog of plugins. Claude Code adds Anthropic's official one, claude-plugins-official, the first time you start an interactive terminal session.

• Scope: user scope enables it for you in every project; project scope writes it into .claude/settings.json for everyone in the repository; local scope is you in this repository only.
• On the web: claude.com/marketplace lists the full catalog with install counts; its Claude Code button copies the install command.
• Not the official one: anthropics/claude-code adds a demo marketplace, claude-code-plugins, which old tutorials still cite.
• Read before you install: a plugin can run hooks and MCP servers. A project skill's allowed-tools applies even in a folder you never trusted, so check the skills in a repository before you run Claude Code there.
• Remove it: /plugin uninstall <plugin>@<marketplace>. A personal or project skill goes when you delete its folder.

How Claude decides to use a skill

Claude sees a listing of skill names and descriptions in each request (skills with disable-model-invocation: true are left out), and matches your task against it. The full SKILL.md loads only when the skill is invoked, then stays in the conversation for later turns. With many skills, the listing is held to 1% of the model's context window, and the descriptions of the skills you use least are dropped first.

• Run it yourself: put /deploy staging at the start of your message. The same name after plain text only gives Claude permission to run it.
• Keep Claude off it: disable-model-invocation: true, or deny Skill(deploy *) in /permissions. Denying Skill turns off every skill.
• It does not trigger: put the words people type in the description, check that it is listed when you ask "What skills are available?", and run claude plugin validate .claude/skills to find frontmatter that does not parse. A skill with broken YAML still runs as /name, but Claude cannot match its description.
• Claude stops following it: after compaction Claude Code keeps the first 5,000 tokens of each invoked skill, 25,000 in all. Put what matters at the top, or invoke it again. A rule that must hold every time belongs in a hook.

Claude Code commands vs skills

They are one feature now. .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy and work the same way, and your old command files keep working. A skill adds a folder for supporting files, the frontmatter that decides who may invoke it, and loading by Claude when relevant. When both exist with one name, the skill wins.

Built-in commands are different: most, such as /compact, run fixed logic, and Claude cannot call them through the Skill tool, apart from a few such as /init and /security-review. A skill of yours with a built-in command's name replaces it in a local terminal session, but not its aliases.

Skills vs subagents, CLAUDE.md, hooks and MCP

• CLAUDE.md loads in every session; a skill loads on demand. "Always do X" goes in CLAUDE.md; reference material and workflows you run by name go in a skill.
• A subagent works in its own context and returns a summary; a skill adds to your main context. They combine: a subagent can preload skills, and context: fork runs a skill in a subagent. Claude Code subagents.
• A hook runs every time its event fires; a skill is a prompt Claude applies with judgment. A guardrail is a hook.
• MCP connects Claude to a service; a skill teaches it how to use that service well. Claude Code MCP.

Do skills cost anything?

Skills are files; nothing to buy. The cost is context, which counts against your plan limits, or your bill on an API key:

• Every request: the names and descriptions of skills Claude may invoke. A skill with disable-model-invocation: true costs nothing until you run it.
• When invoked: the full SKILL.md, which then stays in the conversation. Every line of a loaded skill is a recurring cost.
• To see it: /skill-doctor shows each skill's context cost and how often it is used. On a paid plan, /usage attributes recent usage to skills, subagents, plugins and MCP servers. claude plugin details <name> shows what an installed plugin adds to every session.

Which skills Claude actually invoked on my machine

Anthropic's docs explain how Claude picks a skill, not how often it does. Here is one machine's answer, read from Caprock's export on 5 October 2026: every Skill tool call in Claude Code from 18 July to 5 October.

85

Skill tool calls, in 24 sessions

58

of those 85 came from subagents

<0.1%

of all 99,414 tool calls

By name, counted on the 77 calls whose input parsed:

• deep-research: 32
• claude-api: 17
• claude-in-chrome: 12
• artifact-design: 8

Skills I typed as /name arrive as my own prompt rather than as a Skill tool call, so these counts are the calls Claude chose to make. Most of the calls Claude made itself came from subagents, which can invoke skills through the Skill tool too. This is one heavy user's machine, not a benchmark.

See which skill a session is using

/skill-doctor reports cost and use for your skills, other than bundled and enterprise ones. To watch a skill load while a session runs, or to count every call across sessions, Caprock reads the same Skill calls from Claude Code's hooks and transcripts:

• Live: Caprock's Home screen, its live view, describes a session calling the Skill tool as "using skill deep-research", with the skill's name, and the Live activity feed shows "invoked skill" with the name.
• Your own numbers: caprock export writes one row per tool call with tool set to Skill; with --payload the skill's name is in payload.tool_input.skill, and subagent_id says whether a subagent made the call. That is how the figures above were read.

$ caprock export --agent claude --since 90d --format jsonl --payload --out events.jsonl
$ jq -r 'select(.tool=="Skill" and .kind=="tool.pre") | .payload.tool_input.skill' events.jsonl | sort | uniq -c | sort -rn

Caprock is free and open source. It records every coding agent on your machine, the sessions it did not start included: who is waiting on you, who is stuck, how close each subscription is to its limit, and what each pull request cost. Nothing leaves your machine. Install Caprock.