Skills

A Skill is a reusable set of instructions you package once and Claude loads on demand — solving the problem of pasting the same checklist or procedure into every chat session.

What a skill is

Think of a skill like a saved recipe. Instead of explaining how to make the dish every time, you write it down once and hand it to the chef whenever you need it. In Claude Code, a skill is a directory containing a SKILL.md file. When relevant to the conversation, Claude reads those instructions automatically — or you can call it directly by typing /skill-name. Unlike content in CLAUDE.md (which loads every session), a skill's body only loads when it runs, so long reference material costs almost nothing until you need it.

Anatomy of a skill

Every skill is a directory. The directory name becomes the slash command you type. Inside that directory, SKILL.md is the required file — it has two parts: a YAML frontmatter block (between --- markers) that tells Claude about the skill, and markdown content with the actual instructions Claude follows when the skill runs.

yaml

---
name: 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.
---

## Instructions

Summarize the uncommitted changes in two or three bullet points.
Then list any risks you notice, such as missing error handling or hardcoded values.

description (recommended) — the most important field. Claude reads this to decide when to load the skill automatically. Write it as a plain-English statement of what the skill does and when to use it.
name (optional) — a display label shown in skill listings. It does NOT change the slash command name; only the directory name does that.
disable-model-invocation: true — prevents Claude from loading the skill automatically. Use this for actions with side effects (like /deploy) that you want to trigger yourself.
allowed-tools — tools Claude can use without asking for your approval while the skill is active.

Where skills live

Where you put a skill controls who can use it. Personal skills (under ~/.claude/skills/) are available across every project you work in. Project skills (under .claude/skills/ inside a repo) apply only to that project and can be committed to version control so your whole team shares them. Plugins can also bundle skills, namespaced as /plugin-name:skill-name to avoid conflicts.

Personal — ~/.claude/skills/<skill-name>/SKILL.md — available in all your projects
Project — .claude/skills/<skill-name>/SKILL.md — this project only; commit to share with teammates
Plugin — <plugin>/skills/<skill-name>/SKILL.md — available wherever the plugin is enabled
Enterprise — managed settings — deployed organization-wide by admins

Live reloading

Claude Code watches skill directories for changes. Editing a SKILL.md takes effect in the current session without restarting. Creating a brand-new skills directory (one that did not exist when the session started) requires a restart.

When skills trigger

Claude loads skill descriptions into context at the start of every session so it knows what tools are available. When your message matches a skill's description, Claude invokes the skill automatically — the full SKILL.md content loads into the conversation and Claude follows the instructions. You can also invoke any user-invocable skill directly by typing /skill-name, with optional arguments after the name.

Automatic — Claude reads description keywords and loads the skill when your message is a match.
Manual slash command — type /skill-name (or /skill-name some argument) to invoke directly.
Arguments — use the $ARGUMENTS placeholder in SKILL.md; /fix-issue 123 passes '123' as $ARGUMENTS.
disable-model-invocation: true — removes the skill from Claude's auto-loading and keeps it user-only.

If a skill is not triggering

The most common cause is a vague description. Claude matches your words against the description text, so put the key use case first and use the natural phrasing a user would say ('summarize my diff', 'review uncommitted changes'). You can always invoke manually with /skill-name to bypass discovery.

Write a minimal skill

Here is a complete working skill that summarizes your uncommitted git changes. Create the directory and file, then try asking Claude 'What did I change?' — it should load the skill automatically.

bash

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

Save the following to ~/.claude/skills/summarize-changes/SKILL.md:

yaml

---
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 line starting with !` is dynamic context injection — Claude Code runs that shell command before sending the skill to Claude, replacing the line with the actual diff output. Claude sees real data, not a placeholder. You can now trigger the skill two ways: ask 'What did I change?' (automatic) or type /summarize-changes (direct).

Key takeaways

A skill is a directory with a SKILL.md file — the directory name becomes the /command. The description field drives automatic discovery, so write it in plain language matching what users would actually say. Personal skills (~/.claude/skills/) work across all projects; project skills (.claude/skills/) are scoped to one repo and can be committed for your team. Use disable-model-invocation: true for actions you want to trigger yourself. Full reference: code.claude.com/docs/en/skills.