How-Tos
How to create and install Claude Code skills
Official steps to add a Claude Code skill: SKILL.md, install paths, live diff injection, and /skill-name invocation.
Searcher → Analyst → Writer → Editor · subagentic-20260830-2000
If you keep pasting the same checklist into Claude Code, stop stuffing it into CLAUDE.md. Put it in a skill.
Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses a skill when the work matches, or you invoke it directly with /skill-name. Create one when you keep pasting the same instructions, checklist, or multi-step procedure into chat, or when a section of CLAUDE.md has grown into a procedure rather than a fact. Unlike CLAUDE.md content, a skill's body loads only when it is used, so long reference material costs almost nothing until you need it.
Custom commands have been merged into skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way. Existing .claude/commands/ files keep working. Skills add a directory for supporting files, frontmatter that controls whether you or Claude invokes them, and automatic loading when the description matches.
Create your first skill
The official example summarizes uncommitted git changes and flags anything risky. It pulls the live diff into the prompt before Claude reads the skill, so the answer is grounded in your working tree. Claude loads it when you ask about your changes, or you type /summarize-changes.
Personal skills are available across all your projects. Create the folder:
mkdir -p ~/.claude/skills/summarize-changes
The directory name becomes the command you type.
Every skill needs a SKILL.md with YAML frontmatter between --- markers, plus markdown instructions. The description is how Claude decides when to load the skill automatically. Claude Code reads the frontmatter only when the opening --- is the file's first line; otherwise it treats the whole file, markers included, as skill content. All fields are optional. Only description is recommended.
Save this to ~/.claude/skills/summarize-changes/SKILL.md:
---
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 injection line runs git diff HEAD and replaces itself with that output before Claude sees the skill, so the instructions arrive with the current diff already inlined. That is dynamic context injection.
Keep the body concise. Once a skill loads, its content stays in context across turns, so every line is a recurring token cost. State what to do rather than narrating how or why.
Test the skill
Open a git project, make a small edit, and start Claude Code with claude.
Ask something that matches the description:
What did I change?
Or invoke it directly:
/summarize-changes
Either way, Claude should respond with a short summary of your edit and a list of risks.
Choose a location
Where you store a skill determines who can use it:
- Enterprise — managed settings; all users in your organization
- Personal —
~/.claude/skills/<skill-name>/SKILL.md; all your projects - Project —
.claude/skills/<skill-name>/SKILL.md; this project only - Plugin —
<plugin>/skills/<skill-name>/SKILL.md; where the plugin is enabled
When names collide, Claude Code resolves by source. Across levels, enterprise overrides personal, and personal overrides project. With a deploy skill in both ~/.claude/skills/ and the project's .claude/skills/, /deploy runs the personal one.
A skill at any of those levels also overrides a bundled skill with the same name, but not the bundled skill's aliases. A project code-review skill replaces bundled /code-review; the alias /review never runs your skill.
Plugin skills use a plugin-name:skill-name namespace, so they cannot collide with other levels. my-plugin/skills/deploy/SKILL.md becomes /my-plugin:deploy and loads alongside a project deploy skill.
If a skill and a command share a name, the skill takes precedence. With both .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md, /deploy runs the skill.
Live change detection
Claude Code watches skill directories. Add, edit, or remove a skill under ~/.claude/skills/, the project .claude/skills/, or a .claude/skills/ inside an --add-dir directory, and the change is picked up in the current session without a restart. If you create a top-level skills directory that did not exist when the session started, restart Claude Code so it can watch the new directory.
Live detection covers SKILL.md text only. For a skill folder that is also a plugin, changes to hooks/, .mcp.json, agents/, and output-styles/ need /reload-plugins to take effect.
To remove a personal or project skill, delete its directory. Claude Code drops it from /skills in the current session.
Control how the skill runs
Reference content—conventions, patterns, style guides—runs inline so Claude can apply it alongside the conversation. Task content is a step-by-step action you usually fire with /skill-name. Add disable-model-invocation: true to stop Claude from triggering it automatically. The official deploy example also sets context: fork, which runs the skill in its own subagent context.
Create summarize-changes, dirty a tracked file, then ask what changed or type /summarize-changes. If the summary matches the live diff, the skill is installed. Next, move a repeated procedure out of CLAUDE.md into its own SKILL.md so it loads only when you use it.