Claude Skills

what a skill is

A skill is a directory containing a SKILL.md file — instructions for a specific kind of task that Claude loads on demand instead of you re-typing the same guidance in every conversation. Create one when you keep pasting the same procedure into chat, or when a section of CLAUDE.md has grown into a multi-step process rather than a fact — unlike CLAUDE.md, a skill's body only loads into context when it's actually used, so long reference material costs nothing until then.

writing one


---
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: missing error handling, hardcoded values, tests that need updating.

Save this as ~/.claude/skills/summarize-changes/SKILL.md and it becomes both a command (/summarize-changes) and something Claude reaches for on its own when a request matches the description — which is the single field that determines automatic invocation, so a vague description means a skill that never fires, and an overly broad one fires when it shouldn't.

The !`command` syntax is dynamic context injection: Claude Code runs that shell command and splices its actual output into the skill before Claude ever sees it — the diff above is real, not something Claude has to go fetch itself.

where skills live

Location	Applies to
`~/.claude/skills/<name>/SKILL.md`	every project on your machine
`.claude/skills/<name>/SKILL.md`	this project only — commit it so the team shares it
Enterprise (managed settings)	everyone in the organization

A skill folder can hold more than the one file — templates, example outputs, scripts Claude can run — referenced from SKILL.md so Claude knows they exist and when to open them. In a monorepo, a package can define its own .claude/skills/ that only loads when Claude is working with files in that package.

bundled skills

Claude Code ships with several skills already, invoked the same way as any other: /code-review, /debug, /loop, /run (launch and confirm the app actually works, rather than trusting tests alone), and dataviz (turns "make it look good" into a repeatable procedure for picking a chart form, assigning color by the job it does, and getting the marks and spacing right — see the dedicated page for the full walkthrough). Note /doctor is a separate thing — a built-in CLI diagnostic command, not a SKILL.md-packaged skill, even though it's invoked the same way. A skill you write with the same name as a bundled skill in your own project overrides the bundled one, the same way a local override always beats a default.

writing a good one

Start from a real, recurring pain point — something you find yourself explaining the same way more than twice. Write the instructions as if briefing a competent colleague who has never seen this specific process: the steps, the non-obvious gotchas, and what "done" actually looks like. Claude Code also supports running a skill as its own subagent rather than inline — worth deciding before writing it, since that changes what tools the skill can reach.

reference

code.claude.com — skills