SU8 Codes
< Back to blog
Official article 19 min read

How to Create Claude Code Custom Slash Commands

A step-by-step guide to Claude Code custom slash commands: project and personal file locations, frontmatter fields, $ARGUMENTS and positional parameters, namespaces, three copyable examples, and fixes for common errors. Checked against the official documentation on November 15, 2026.

#claude-code#slash-commands#tutorial
How to Create Claude Code Custom Slash Commands

A Claude Code custom slash command is a Markdown file you write. Put it in your project or home directory, and its filename or folder name becomes a /command you can run in a session. The body is the instruction Claude follows each time the command runs.

One change matters if you are following an older tutorial: the official documentation now says custom commands have been merged into skills. Existing .claude/commands/*.md files still work, but new commands are better placed in .claude/skills/<name>/SKILL.md. If a tutorial only shows the old layout, the command still runs, but it misses skill features such as supporting files and path-based activation.

This guide answers one question: how do you create Claude Code custom slash commands? It covers where files go, how frontmatter works, how arguments are passed, how namespaces behave, three copyable examples (code review, pre-commit checks, test generation), and the three common failure modes. Command and field names are checked against the official documentation on November 15, 2026. When a release changes them, the documentation wins. For built-in commands such as /clear and /model, see the Claude Code commands cheat sheet. This article is about the commands you write.

What a Claude Code custom slash command is

A slash command is something you type at the start of a message with a leading /. Built-in commands such as /clear and /model ship with Claude Code. A custom command is one you add: the /name syntax is the same, but the instructions come from your file.

Each command has two parts:

  • YAML frontmatter. This is the configuration between --- markers at the top of the file. YAML is a plain-text format that uses indentation; frontmatter is the metadata block at the start of the file. It tells Claude Code the command's name, when to use it, and which tools it may use.
  • A Markdown body. This is the instruction Claude reads when the command runs.

The official documentation now treats custom commands and skills as the same mechanism. A command can be a single file at .claude/commands/<name>.md, or a skill directory at .claude/skills/<name>/SKILL.md. Both are Markdown plus frontmatter. A skill directory can also hold scripts, templates, and reference files, and it supports activation based on file paths.

Write a command when you keep pasting the same prompt, when a procedure needs the same steps every time, or when a team should run a check in the same order. If Claude should always know a fact or rule, put it in CLAUDE.md. If something must happen automatically on every edit, use a hook: a shell command, HTTP request, MCP tool call, prompt, or subagent that Claude Code runs at a lifecycle event. The differences are covered below.

Where custom commands live: project vs personal

Pick a scope first, then a format.

ScopeRecommended (skill)Older format (command file)Who gets it
Project.claude/skills/<name>/SKILL.md.claude/commands/<name>.mdSessions in this repository; commit it to share with the team
Personal~/.claude/skills/<name>/SKILL.md~/.claude/commands/<name>.mdAll your projects on this machine

The official .claude directory reference lists both skills/<name>/SKILL.md and commands/*.md as "Project and global" and describes command files as "single-file prompts; same mechanism as skills." Project files go under the repository's .claude/ directory; personal files go under ~/.claude/ in your home directory.

A few rules matter in practice:

  • A skill wins over a command file with the same name. The documentation's conflict table says: a skill and a file in .claude/commands/ → the skill.
  • Same name at several scopes: enterprise beats personal, and personal beats project. A command in your home directory can therefore override one checked into the repository.
  • Monorepos: project skills load from .claude/skills/ in the directory where you start Claude Code and in every parent directory up to the repository root. Starting in packages/frontend/ still picks up the root's skills.
  • Added directories: adding a directory with --add-dir or /add-dir also loads that directory's .claude/skills/ and .claude/commands/. Claude Code watches .claude/skills/ for live changes, but it does not watch the added directory's .claude/commands/, so restart the session after editing a command file there.

For new work, use a skill directory. The official docs say to prefer a skill because skills also support supporting files. Command files are fine for a short, single-file prompt you already have.

File format and frontmatter

A minimal skill looks like this:

---
description: Summarize the uncommitted changes and flag risky ones. Use when the user asks what changed or wants a commit message.
---

Summarize the current git diff in three bullets or fewer, then list any risks you notice, such as missing error handling, hardcoded values, or tests that need updating.

The frontmatter is YAML, a configuration format where indentation defines the structure. A few rules decide whether the command loads:

  • The opening --- must be the first line of the file. If it is not, Claude Code treats the whole file, markers included, as command content and ignores the frontmatter.
  • Every field is optional; only description is recommended. Field names must match the documentation exactly, hyphens included. Claude Code silently ignores a field it does not recognize.
  • Boolean fields accept true / false, and also yes / no, on / off, and 1 / 0, in any letter case.

Key fields:

FieldWhat it doesNotes
nameCommand name shown in the / menuDefaults to the directory name; command files do not support it
descriptionWhat the command does and when to use itClaude uses it to decide when to load the command automatically; if omitted, the first non-empty line of the body is used
argument-hintHint shown during autocompleteFor example [issue-number] or [filename] [format]
argumentsNames positional arguments for $name substitutionA space-separated string or a YAML list; names map to positions in order
disable-model-invocationStops Claude from invoking the command on its ownSet to true for workflows with side effects; you can still run /name
allowed-toolsPre-approves tools for the turn that invokes the commandThe grant clears on your next message; it does not restrict other tools
modelSwitches the model while the command runsApplies for the rest of the current turn and is not saved; accepts the same values as /model, or inherit
context / agentRuns the command in a forked subagentUse context: fork with agent when the task needs isolated context
pathsActivates the skill only for matching filesSkill directories only; command files do not support it

Command files support the same fields except name and paths; the rest behave the same. Angle brackets in description and when_to_use show as &lt; and &gt;. To show a placeholder such as <branch>, use square brackets or put it in argument-hint.

A few more fields are useful for control. when_to_use adds trigger phrases to the description. user-invocable: false hides the command from the / menu so only Claude can invoke it. disallowed-tools removes tools while the command is active. Keep the description short: the combined description and when_to_use text is truncated at 1,536 characters in the skill listing.

If you plan to upload the same skill to claude.ai or distribute it through the Skills API, the frontmatter can use only the six fields allowed by the Agent Skills spec: name, description, license, compatibility, metadata, and allowed-tools. A Claude Code-only field such as argument-hint causes packaging or upload to fail with an explicit error. Inside Claude Code, all the fields above are accepted.

Arguments: $ARGUMENTS and positional parameters

Everything after the command name is an argument. Claude Code substitutes it into the body with a few placeholders:

PlaceholderExpands toExample
$ARGUMENTSThe full argument string as typed/fix-issue 123 makes $ARGUMENTS equal 123
$ARGUMENTS[0]The first argument (zero-based index)/migrate SearchBar JavaScript TypeScript gives SearchBar
$0, $1Shorthand for $ARGUMENTS[0], $ARGUMENTS[1]Same example: $0 is SearchBar, $1 is JavaScript
$nameA named argument declared in argumentsWith arguments: [issue, branch], $issue is the first argument and $branch the second

Rules worth knowing:

  • If no placeholder receives an argument, Claude Code appends ARGUMENTS: <your input> to the end of the command content. Claude still sees what you typed, just not where you expected it.
  • Positional indexes start at 0. $0 is the first argument, $1 is the second. If you are used to shell $1, this is an easy off-by-one.
  • Quote multi-word values. Claude Code uses shell-style quoting: /my-skill "hello world" second makes $0 equal hello world and $1 equal second.
  • A missing positional placeholder stays in the content as literal text, such as $2 when only one argument was passed. A missing named placeholder expands to an empty string.
  • To write a literal amount such as $1.00, escape the dollar sign with a backslash: \$1.00.
  • A command is recognized only at the start of a message. /review by itself runs the command. In a sentence such as "please /review this", it does not run directly; the name gives Claude permission to run it while it responds.

Here is a command with positional arguments:

---
description: Migrate a component from one language to another. Use when the user asks to migrate a named component.
argument-hint: [component] [from] [to]
---

Migrate the $0 component from $1 to $2. Preserve existing behavior and tests.

Run /migrate-component SearchBar JavaScript TypeScript, and the three placeholders expand in order.

Namespaces and subdirectories

Once you have more than a handful of commands, filenames alone stop being enough. Claude Code uses directories and colons for namespacing:

Where the file livesWhat you type
.claude/commands/deploy.md/deploy
.claude/commands/frontend/component.md/frontend:component
.claude/skills/deploy/SKILL.md/deploy (directory name, or name: deploy in frontmatter)
apps/web/.claude/skills/deploy/SKILL.md (monorepo, same name as the root skill)/apps/web:deploy
A plugin's skills/review/SKILL.md/my-plugin:review

Two rules cover the common cases:

  • Command-file subdirectories become prefixes. The path under commands/ replaces each / with :, then adds the filename. frontend/component.md becomes /frontend:component.
  • Skills use the directory name by default. A nested skill whose name clashes with a root skill gets a path prefix so both remain available. The exact prefix depends on where the session started, so the same monorepo can show different command names from the root and from apps/web/.

Name limits are enforced at load time:

  • A name cannot contain zero-width spaces, control characters, private-use or unassigned characters, direction-changing characters, < or >, or blank-like whitespace such as a no-break space, two spaces in a row, or leading or trailing spaces. It also cannot exceed 256 characters. A refused file or folder name means the command does not load; a refused frontmatter name means the command still loads, but the / menu does not show that name. A startup notice names the first problem, and --debug writes the specific name to the log.
  • anthropic-skills is reserved across skills, command files, and workflows. A skill folder named synced does not load either, in any capitalization.
  • When names collide, enterprise beats personal and personal beats project; a skill beats a command file.

Three examples you can copy

The examples use both formats on purpose: a single-file command for a short read-only review, a skill for a workflow with side effects, and a command with a positional argument. Change paths and test commands to match your repository before use.

1. Review the current diff

.claude/commands/review-diff.md:

---
description: Review the current diff for correctness bugs. Use when the user asks for a review of uncommitted changes.
argument-hint: [path]
allowed-tools: Bash(git status *) Bash(git diff *)
---

Review the current diff for correctness bugs only.

- Scope: $ARGUMENTS (leave empty to review all changes).
- Start with `git status --short` and `git diff`; include staged changes with `git diff --cached`. If the scope is not empty, add `-- <path>` to both commands.
- Report each finding with the file, line, what breaks, and a minimal fix.
- Do not edit files. Do not comment on style unless it changes behavior.

Run /review-diff, or /review-diff src/api to limit the scope. This command is read-only, so it does not set disable-model-invocation; Claude can also load it when you ask for a review. Add disable-model-invocation: true if you want manual control.

2. Pre-commit checks

.claude/skills/precommit/SKILL.md:

---
name: precommit
description: Run this repository's pre-commit checks before a commit. Use when the user is about to commit and wants the checks run.
disable-model-invocation: true
allowed-tools: Bash(git status *) Bash(git diff *) Bash(npm test *) Bash(npm run lint *)
---

Run the checks this repository uses before a commit.

1. Run `git status --short` and `git diff --cached` to see what will be committed.
2. Run the fast test command documented in CLAUDE.md or the README. This example assumes `npm test`; use your project's command instead.
3. Run the linter if the project has one. This example assumes `npm run lint`.
4. If a check fails, stop and report the full command, the relevant output, and the file and line. Do not commit.
5. If all checks pass, summarize what ran and say the change is ready to commit.

Set disable-model-invocation: true because a pre-commit check should not be something Claude starts on its own and then follows with a commit. Run /precommit to trigger it; the allowed-tools list pre-approves only those command patterns. If your test command is different, change the patterns or remove them and let the normal permission prompt appear.

3. Generate tests for one file

.claude/commands/test-file.md:

---
description: Generate tests for one source file. Use when the user asks for tests for a specific file.
argument-hint: [file]
disable-model-invocation: true
allowed-tools: Read Grep Glob
---

Write tests for the file at `$0`.

1. Read `$0` and the existing tests near it.
2. Follow the test framework, naming style, and assertion style already used in this repository.
3. Cover the public behavior, including at least one failure case.
4. Add the tests to the matching test file; do not change production code.
5. Run the test command and report the result. If a test fails, decide whether the test or the code is wrong before changing either.

Run /test-file src/utils/parse.ts. This example pre-approves only read-only tools; running the test command still goes through your normal permission rules, which is intentional. If the command needs scripts or templates, convert it to a skill directory and keep the extra files next to SKILL.md.

Troubleshooting: command not showing, arguments missing, permissions

The command does not appear in the / menu

Check these in order:

  1. Location and filename. Project commands go under .claude/commands/ or .claude/skills/; personal commands go under ~/.claude/. A skill needs a folder and a SKILL.md; a command file is a single .md file.
  2. Frontmatter starts on line 1. If the first line is blank or contains something else, the --- block is treated as body text and the metadata is ignored.
  3. The name was refused. Hidden characters, < or >, blank-like whitespace, or a name longer than 256 characters cause a startup notice. Run claude --debug and search the log for [names] to see which item was refused, then rename it and restart.
  4. A reserved name. anthropic-skills is reserved, and synced cannot be a skill folder name.
  5. A new top-level skills directory. If you created ~/.claude/skills/ or .claude/skills/ after the session started, run /reload-skills or restart. A .claude/commands/ directory in an added directory is not watched, so restart after changing it.
  6. A nested skill. A skill in a subdirectory below where you started does not load at startup. It loads the first time Claude reads or edits a file in that subdirectory. Use /add-dir to load it sooner.
  7. Visibility settings. user-invocable: false hides the command from the / menu. A skillOverrides entry of "off" hides it too. disable-model-invocation: true does not hide it from you; it only stops Claude from invoking it on its own.
  8. A typo. A misspelled command produces Unknown command: /hepl. Did you mean /help?.
  9. Startup mode. --safe-mode disables all customizations, and --bare skips skills and other auto-discovery. Start in normal mode and check again.

If the YAML does not parse, Claude Code still loads the skill body with empty metadata. /name still works, but Claude cannot match the description. Run with --debug to see the parse error. Run /skills to see which skills are available in the current session; /reload-skills rescans the directories.

Arguments are not showing up

  • No placeholder. If the body has no $ARGUMENTS, $0, or named placeholder, Claude Code appends ARGUMENTS: <your input> at the end. Add the placeholder where you want the value.
  • Off-by-one index. $0 is the first argument, not $1.
  • Multi-word argument not quoted. /cmd hello world is two arguments; /cmd "hello world" is one.
  • Missing positional stays literal. If you pass one argument and the body uses $2, the text $2 remains.
  • Named argument missing. It expands to an empty string.
  • A literal dollar amount. Escape it as \$1.00.
  • The command was not at the start of the message. After plain text, the name grants permission to run the skill but does not run it directly.
  • arguments order. With arguments: [issue, branch], the first value goes to $issue and the second to $branch.

Permissions block the command

  • allowed-tools is per turn. It pre-approves listed tools only during the turn that invokes the command. The grant clears when you send your next message, so a later run may prompt again.
  • It does not restrict tools. Every tool remains callable; your permission settings still govern the ones you did not list. Use disallowed-tools to remove tools while the command is active.
  • Deny and ask rules still win. An injected ! command that a deny rule matches aborts the invocation with Shell command permission check failed for pattern "...".
  • Managed policy can ignore allowed-tools. If your organization sets allowManagedPermissionRulesOnly, project and personal allowed-tools grants are ignored. /status lists the affected commands.
  • Shell execution may be disabled. With disableSkillShellExecution: true, each ! command is replaced by [shell command execution disabled by policy].
  • Use /permissions for standing rules. Add an allow rule there if you want a tool approved every time, not just for one turn.
  • Review repository skills before running them. A project skill's allowed-tools applies even in a -p run in a folder you have never trusted, so a checked-in skill can grant itself broad tool access. Read the frontmatter before you run Claude Code in an unfamiliar repository.

Custom commands vs skills and hooks

Three concepts do different jobs:

What you wantUseWhy
Reuse a prompt or procedureA custom command (now a skill)You type /name, or Claude loads it from the description
Make something happen on every edit, without Claude rememberingA hookClaude Code fires it at a lifecycle event, before or after a tool call
Teach Claude a rule it should know every sessionCLAUDE.mdIt loads at session start, with no trigger

Custom commands and skills are no longer separate systems. The old command file is a single-file format; a skill is a directory that can include supporting files, use paths to activate only for matching files, and run in a forked subagent with context: fork. New work should use a skill; existing command files keep working.

Hooks are different. A hook is a shell command, HTTP request, MCP tool call, prompt, or subagent that Claude Code runs automatically at a lifecycle event such as SessionStart, PreToolUse, PostToolUse, or Stop. The official comparison puts it plainly: a hook runs at an event, while a skill runs when you type /name or Claude matches the description. A hook costs no context unless it returns output; a skill's description is loaded into context each session. Use a hook when the action must happen the same way every time and does not need Claude to think, such as running a linter after every edit or blocking a dangerous command. Use a skill when Claude should decide how to apply the steps. A rule written in a skill or CLAUDE.md is a request; a hook is enforcement.

For built-in commands, see the Claude Code commands cheat sheet. This article is about the commands you write.

Once these pieces are in place, a working custom command is one file plus a short frontmatter block. The rest is tuning it to your team's workflow.

Pre-flight checklist

  • The file is in the right scope: .claude/... for the project, ~/.claude/... for personal use.
  • The opening --- is the first line of the file.
  • description says what the command does and when to use it, in words users actually type.
  • The command appears in the / menu; if not, work through the troubleshooting section.
  • One argument round-trips correctly through $ARGUMENTS or $0.
  • allowed-tools covers the tools you want pre-approved, and nothing broader.
  • Side-effect workflows set disable-model-invocation: true.
  • Shared commands are committed to git.
  • You have read the allowed-tools and body of any skill you copied from someone else.

Sources

All sources were checked on November 15, 2026. The legacy docs.claude.com and docs.anthropic.com URLs redirect to code.claude.com, so the links below use the canonical destination.