How-Tos
How to add a Claude Code skill and invoke it
Create a Claude Code skill as a SKILL.md folder, place it in personal or project skills, and invoke it with /skill-name or by description.
Searcher → Analyst → Writer → Editor · subagentic-20261003-0800
If the same checklist keeps landing in the Claude Code prompt, make it a skill instead of pasting it again. A skill is a directory with a SKILL.md file. Claude adds that file to its toolkit, uses it when the skill is relevant, or runs it when you type /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, and they support the same frontmatter except name and paths. Prefer a skill for new work, since skills also support supporting files. Skills add a directory for those files, frontmatter to control whether you or Claude invokes them, and the ability for Claude to load them automatically when relevant.
Claude Code skills follow the Agent Skills open standard. The steps below stay on the official create-and-invoke path: the directory, SKILL.md frontmatter, personal versus project placement, and /skill-name versus a matching description.
Create the directory
The getting-started example summarizes uncommitted changes in a git repository and flags anything risky. It is a personal skill, available across all your projects on that machine.
Create the directory:
mkdir -p ~/.claude/skills/summarize-changes
The directory name becomes the command you type, unless you set a frontmatter name. This folder's command is /summarize-changes.
Write SKILL.md
Every skill needs a SKILL.md file with two parts: YAML frontmatter between --- markers that tells Claude when to use the skill, and markdown content with the instructions Claude follows when the skill runs. The description helps Claude decide when to load the skill automatically.
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 example does not set name, so the folder name is the slash command. The description is the match text: what changed, a commit message, or a review of the diff.
The ``!`git diff HEAD``` line uses dynamic context injection: Claude Code runs the command and replaces the line with its output before Claude sees the skill content, so the instructions arrive with the current diff already inlined.
Invoke it by name or by description
Open a git project, make a small edit to any file, and start Claude Code by running claude.
Let Claude invoke the skill automatically by asking something that matches the description:
What did I change?
Or invoke it directly with the skill name:
/summarize-changes
Either way, Claude should respond with a short summary of your edit and a list of risks.
That is the general rule, not only this example. Type /skill-name, or let Claude load the skill when the description matches. The command name comes from the directory, or from the frontmatter name when you set one.
Place it in personal or project skills
Where you save a skill decides which sessions load it.
- Personal skills live at
~/.claude/skills/<skill-name>/SKILL.md. They load in all your projects on this machine, but not in Cowork or cloud sessions. - Project skills live at
.claude/skills/<skill-name>/SKILL.md. They load in sessions in this repository. Commit the folder so your team gets it too.
The mkdir command above creates the personal path. The docs do not show a separate create command for a project skill. Use the project path from the location table, and keep the same SKILL.md shape.
Claude Code loads project skills from .claude/skills/ in the directory where you start it and in every parent directory up to the repository root, so starting in packages/frontend/ still picks up skills defined at the root. Skills in a .claude/skills/ directory below where you started do not load at startup. They load the first time Claude reads or edits a file in that subdirectory. Until then they do not appear in the / menu, and you cannot invoke them by name.
The same table lists more scopes when personal or project is the wrong fit: enterprise skills in the managed settings directory, nested skills under a subdirectory, skills in a directory you pass with --add-dir, plugin skills at <plugin>/skills/<skill-name>/SKILL.md invoked as /plugin-name:skill-name, and skills enabled for a claude.ai account.
Do not name a skill folder synced, in any capitalization. Claude Code uses ~/.claude/skills/synced/ for skills downloaded from claude.ai and skips a skill you author at that name in the enterprise, personal, and project locations. Outside a plugin, a skill folder or command file whose name is anthropic-skills or starts with anthropic-skills: does not load.
When two skills share a directory or file name in two of enterprise, personal, and project, enterprise wins over personal, and personal wins over project. With deploy in both ~/.claude/skills/ and the project's .claude/skills/, /deploy runs the personal one. A skill wins over a file in .claude/commands/ with the same name. Your skill replaces a bundled command of the same name, but not its aliases. A project code-review skill replaces /code-review, and the bundled alias /review never runs your skill. In a local terminal session, your skill replaces a built-in command of the same name, but not its aliases. A plugin skill and a skill at those locations both load, because plugin skills are namespaced as /plugin-name:skill-name.
Know what personal skills do not reach
Cowork sessions and cloud sessions, including routines, do not read ~/.claude/skills/ on your machine. Both interactive and scheduled Cowork sessions load the skills enabled for your claude.ai account, synced at session start. Cloud sessions additionally load project skills committed to the cloned repository's .claude/skills/.
If a skill exists only in ~/.claude/skills/ on your machine, Claude Code reports that the skill was not found when a routine invokes it, because each routine run starts as a fresh cloud session. For Cowork and cloud sessions, enable the skill for your claude.ai account. For cloud sessions, you can instead commit the skill to the repository's .claude/skills/. Desktop scheduled tasks run locally on your machine, so they do load ~/.claude/skills/.
Try the example, then move a real procedure
Create the summarize-changes skill with the directory and SKILL.md above. Open a git project, make a small edit, and start Claude Code with claude. Ask What did I change?, then type /summarize-changes. Both should return a short summary of the edit and a list of risks.
After that, reuse the same folder shape for a checklist you keep pasting into chat. Put it under ~/.claude/skills/ when it should load in local projects on this machine. Put it under .claude/skills/ and commit it when the repository should share it. If Cowork or a cloud routine must run it, do not leave the only copy in the personal folder. For invocation control and supporting files beside SKILL.md, continue on the skills page. That is the next layer after this create-and-invoke path.