How to make custom slash commands (skills) in Claude Code

Guide · checked against the docs on Oct 16, 2026

If you keep typing the same long instructions into Claude Code, you can save them once and run them with a short command like /review-changes. Claude Code calls these saved instructions skills. This guide shows how to make one, where to put it, and what to watch out for. Everything below comes from Anthropic's skills page in the Claude Code docs, read on October 16, 2026. We haven't tested these steps ourselves.

Not affiliated with or endorsed by Anthropic. Claude Code changes often, so check the docs for your version.

Slash commands and skills are now the same thing

You may have seen older guides that talk about "custom slash commands" in a .claude/commands/ folder. Anthropic's docs say: "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. Your existing .claude/commands/ files keep working." (checked Oct 2026)

So if you already have command files, you don't need to move them. For new ones, this guide uses the skill format, because the docs call .claude/commands/ "the older format" and suggest a skill "for new work". (checked Oct 2026)

The docs describe what a skill is like this: "Skills extend what Claude can do. Create a SKILL.md file with instructions, and Claude adds it to its toolkit. Claude uses skills when relevant, or you can invoke one directly with /skill-name." (checked Oct 2026)

When a skill is worth making

The docs give a simple test: "Create a skill when you keep pasting the same instructions, checklist, or multi-step procedure into chat". (checked Oct 2026)

Our advice, not a vendor quote: good first skills for beginners are the boring, repeated ones. Examples:

"Explain what I changed and flag anything risky."
"Write tests for this file in our usual style."
"Check this page for missing error handling."

Where to save a skill

Where you save the skill decides where it works. The docs list several locations. The two you'll use most are these (checked Oct 2026):

Location	Path	Where the docs say it loads
Personal	`~/.claude/skills/<skill-name>/SKILL.md`	"All your projects on this machine, but not Cowork or cloud sessions"
Project	`.claude/skills/<skill-name>/SKILL.md`	"Sessions in this repository. Commit it so your team gets it too"

The docs also say: "Personal skills are available across all your projects." (checked Oct 2026)

If a personal skill and a project skill have the same name, the docs' rule is "Enterprise over personal, and personal over project." (checked Oct 2026) So your personal copy wins over the project's copy.

Our advice, not a vendor quote: start with a personal skill while you experiment. Move it into the project's .claude/skills/ folder once it works and you want teammates to have it.

Make your first skill

Step 1: Create the folder

The folder name becomes the command name. For a skill called review-changes, on macOS or Linux run:

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

Step 2: Write SKILL.md

The docs explain the file's shape: "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." (checked Oct 2026)

They also say: "The directory name, or the frontmatter name when you set one, becomes the command you type, and the description helps Claude decide when to load the skill automatically." (checked Oct 2026)

Save this as ~/.claude/skills/review-changes/SKILL.md. It's our own example, modeled on the one in the docs:

---
description: Summarize my uncommitted changes and flag risks. Use when I ask what changed or want a review of my diff.
---

Look at my uncommitted changes with git diff.
Summarize them in two or three bullet points.
Then list any risks: missing error handling, hardcoded values,
secrets, or tests that need updating.
If there are no changes, say so.

Step 3: Try it

Open a project in your terminal, start Claude Code with claude, and type:

/review-changes

You don't need to restart after editing the file. For the usual skill folders, the docs say "Claude Code picks up the change within the current session, without a restart." (checked Oct 2026)

The frontmatter fields beginners need

The docs say: "All fields are optional. Only description is recommended so Claude knows when to use the skill." (checked Oct 2026)

Three fields cover most beginner needs:

description: what the skill does and when to use it. Put the main use first.
name: changes the command name. Without it, the folder name is used.
disable-model-invocation: true: only you can start the skill. Claude won't run it on its own.

Spell field names exactly. The docs warn that "Claude Code ignores a field it doesn't recognize without reporting an error." (checked Oct 2026) A typo won't show an error. The setting just won't apply.

Stop Claude running a skill on its own

The docs say: "By default, both you and Claude can invoke any skill." (checked Oct 2026)

That's fine for a review skill. It's not fine for anything that changes things outside your editor. For disable-model-invocation: true, the docs say: "Use this for workflows with side effects or that you want to control timing, like /commit, /deploy, or /send-slack-message. You don't want Claude deciding to deploy because your code looks ready." (checked Oct 2026)

Our advice, not a vendor quote: if a skill commits, pushes, deploys, sends messages or deletes anything, add disable-model-invocation: true. Then it only runs when you type the command.

Pass extra details to a skill

Skills can take arguments. Anything you type after the command name replaces $ARGUMENTS in the skill's text. The docs' example is a fix-issue skill whose body starts "Fix GitHub issue $ARGUMENTS following our coding standards." Then: "When you run /fix-issue 123, Claude receives "Fix GitHub issue 123 following our coding standards..."" (checked Oct 2026)

A small example of our own:

---
description: Write tests for one file
disable-model-invocation: true
---

Write tests for $ARGUMENTS using the test framework this project already uses.
Don't change the file under test.

Then run /write-tests src/cart.js.

Keep skills short

The docs say: "Keep the body itself concise. Once a skill loads, its content stays in context across turns, so every line is a recurring token cost." (checked Oct 2026) They also say: "Keep SKILL.md under 500 lines. Move detailed reference material to separate files." (checked Oct 2026)

Be careful with skills you didn't write

Skills can pre-approve tools with an allowed-tools field, so Claude can use them without asking you first. The docs warn: "A skill can grant itself broad tool access, so review the allowed-tools of skills checked into a repository before you run Claude Code there." (checked Oct 2026)

Our advice, not a vendor quote: before you run Claude Code in a repo you cloned, open its .claude/skills/ and .claude/commands/ folders and read them. Treat a skill like a script someone handed you. If it pre-approves shell commands you don't understand, don't run it.

If your skill doesn't show up

The docs' troubleshooting list includes "Check the description includes keywords users would naturally say" and "Verify the skill appears in What skills are available?" (checked Oct 2026)

Other things to check:

The file is named SKILL.md and sits inside its own folder under skills/.
The --- line is the very first line of the file.
If the frontmatter might be broken, the docs say: "Run with --debug to see the parse error." (checked Oct 2026)
You can always type / plus the skill name to run it yourself.

What the docs don't say

The page we read doesn't say how many skills is too many for a beginner, or which skills to start with. The suggestions above are ours. We don't cover plugins, enterprise settings or skills synced from claude.ai here. See the docs for those.

We haven't tested these steps hands-on. This guide collects what Anthropic's own docs say.

Not affiliated with or endorsed by Anthropic. Claude Code changes often, so check the docs for your version.