Claude Code Slash Commands: Create Custom Commands from A to Z (2026)

- This guide follows the official docs at code.claude.com/docs/slash-commands (accessed 09/08/2026). Claude Code docs move fast, so a few fields need a recent build (Claude Code v2.1.x or later).

What is a slash command in Claude Code? (built-in vs custom)

In Claude Code, a slash command is any command that starts with / and that you type right inside a chat session to trigger something fast. There are two kinds, and they are easy to mix up.

Built-in commands ship with Claude Code from Anthropic - nothing to install. A few you will reach for almost every day:

• /help - list every available command
• /clear - wipe the conversation history and start with a clean context
• /compact - compress the conversation to save context
• /init - generate a CLAUDE.md file for the project
• /model - switch the model you are using
• /status - check session, account, and context status

Custom commands are ones you create yourself to package a prompt you use often into a single keystroke. Put plainly: a custom slash command is a Markdown file in .claude/commands/ - the filename is the command name, and the file body is the prompt Claude runs when you call it. Instead of re-pasting "review the current diff against this checklist..." every time, you save it once and type /review.

Here is the nice part: custom commands live in the same menu as built-ins. Type / and the menu pops up suggesting both the built-in commands and yours. If you commit the .claude/commands/ folder to your repo, the whole team shares one set of commands - which is exactly why custom commands beat "copy-paste prompts" by a mile.

So why not just paste the prompt each time? Three practical reasons. A prompt you reach for often is usually long, and you will drop a line if you type it from memory. Everyone on the team writes it slightly differently, so results are uneven. And when you improve the prompt, there is no way to push that improvement to the rest of the group. Turning it into a command file fixes all three: the prompt lives in one place, everyone calls the same command, and editing the file updates it for everybody. In other words, a custom command turns a "personal trick" into a "shared tool" you can version-control like code.

Create your first custom slash command (.claude/commands)

Let's build a /review command that has Claude review your code changes. Three steps, each one copy-paste ready.

Step 1 - Create the commands folder at the root of your project:

mkdir -p .claude/commands

Windows PowerShell has no mkdir -p, so use:

New-Item -ItemType Directory -Force .claude/commands

Step 2 - Create review.md inside that folder. The filename (minus the .md) is the command name. The file body is the prompt:

You are a strict reviewer. Review the current code changes.

Focus on:
- Logic bugs and unhandled edge cases
- Security holes (unvalidated input, leaked secrets)
- Naming, clarity, and duplicated code

For each issue: give the file + line, the severity,
and a concrete fix. No vague praise.

Step 3 - Run the command in your Claude Code session:

/review

Claude loads the file contents as the prompt and runs it right away. Done. You just built your first custom command without writing a single line of code.

Tip: if you just created the file but the / menu doesn't show the command yet, jump to the "Common problems" section near the end - usually it's just the wrong folder or a session that needs restarting.

Passing arguments to a command ($ARGUMENTS, $1, named arguments)

A rigid command doesn't get reused much. The real power comes from arguments - the text you type after the command name gets injected into the prompt.

Grab everything - $ARGUMENTS. This variable captures all the text after the command name. Create .claude/commands/fix-issue.md:

Fix GitHub issue #$ARGUMENTS. Read the issue description,
find the root cause in the code, then write a fix with tests.

Type /fix-issue 123 and $ARGUMENTS becomes 123. Type /fix-issue 123 security first and $ARGUMENTS becomes the whole string 123 security first.

Positional arguments - $1, $2... When you need each argument separated, use positional variables. For example, .claude/commands/rename.md:

Rename the variable `$1` to `$2` across every open file,
keeping the logic intact and updating all references.

Type /rename oldName newName and $1 is oldName, $2 is newName. For multi-word arguments, wrap them in quotes: /rename "user id" "customer id".

Named arguments - the arguments frontmatter. If you want meaningful names instead of $1/$2, declare them in frontmatter (see the next section) and reference them by name. Declare arguments: [from, to] and you can use $from and $to - mapped in argument order.

Quick reference for substitution variables:

Which one should you use? Simple rule. If the command just takes "one block of free text" (an issue description, a question, a snippet to explain), $ARGUMENTS is enough and the most flexible. If the command needs an exact number of arguments in a fixed order (rename: from what -> to what), positional $1/$2 is clearer. Named arguments only earn their keep when a command has several arguments that are easy to confuse - then $from/$to reads better than $1/$2.

Full details on $ARGUMENTS and positional arguments live in the Claude Code docs (accessed 09/08/2026). For a fast look at every command syntax, I keep it handy in the Claude Code cheat sheet.

Frontmatter: configure a command with YAML

At the top of a command file, you can add a frontmatter block of YAML (between two --- lines) to configure behavior. This is the piece most guides skip entirely, even though it decides how safe and convenient the command actually is.

Everything is optional; in practice only description is worth adding every time. Here's a .claude/commands/commit.md that only lets the command touch git and nothing else:

---
description: Create a conventional commit from staged changes
argument-hint: [optional scope]
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
---

Look at the staged changes and write one tight, accurate
conventional commit (feat/fix/docs/refactor...).
If nothing is staged, tell me to `git add` first.

With allowed-tools set correctly, the command can only run a few predefined git commands - far safer than leaving Claude free to run whatever it wants. This is a habit worth building for any command that touches the shell.

Injecting live data with !`bash` (and file references)

A command gets much stronger when it can grab the current context itself instead of making you paste it in. Claude Code lets you inject the output of a bash command right into the prompt with the !`<command>` syntax.

The key thing to understand: the command inside !`...` runs BEFORE Claude reads the prompt, and its output is spliced straight into the content. This is not Claude deciding to run a command - it has already run. Here's a /review command that grabs the current diff for itself:

Review the diff below and point out bugs + security risks:

!`git diff HEAD`

When you type /review, Claude Code runs git diff HEAD, takes the result, pastes it in place, and only then hands the whole prompt to Claude. You never copy the diff by hand again.

For a multi-line bash block, use a fenced block that opens with !:

```!
git status --short
git log --oneline -5
```

Note: keep !`...` at the start of a line or after whitespace. If you want a literal $ (say, a price like \$1.00 in your text), escape it with a \ so it isn't read as an argument.

Sharing commands: Project vs Personal + subfolders

Custom commands live in two places that differ by scope:

• Project - .claude/commands/ at the repo root. Commit it to git and the whole team shares the set. Great for project-specific commands: /deploy, /test, your team's commit conventions.
• Personal - ~/.claude/commands/ in your home directory. Just your machine, but usable in every project. Great for personal habits: /explain, /tldr.

When names collide, the project-level command usually wins because it's closer to the project context.

Subfolders to group commands (namespacing). As your command set grows, create subfolders to group them. For example, .claude/commands/git/commit.md surfaces the command under a git group, keeping the / menu tidy and easy to search.

This "configure per repo, commit to share with the team" mechanism is exactly the spirit of the CLAUDE.md file. If that's new to you, read up on how to write a CLAUDE.md for your repo so the two complement each other: CLAUDE.md states the shared conventions, and .claude/commands/ packages the repetitive actions.

5 copy-paste command templates (ready to run)

Here's the set I actually use day to day. Copy them into .claude/commands/ and tweak for your stack.

1. /review - review the current diff (review.md):

---
description: Review current changes for bugs and security risks
---

Review the diff below, prioritizing logic bugs and security holes:

!`git diff HEAD`

For each issue: give file:line, severity, and a concrete fix.

2. /commit - conventional commit (commit.md):

---
description: Write a conventional commit from staged changes
allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git diff:*)
---

Look at `git diff --staged` and write one accurate
conventional commit. Do not add AI references to the message.

3. /test - run tests and fix failures (test.md):

---
description: Run the test suite and fix failing tests
argument-hint: [optional test file path]
---

Run the tests for $ARGUMENTS (run everything if empty).
If any test fails: read the error, find the root cause, fix
the code or the test, then rerun until green.

4. /docs - write docstrings (docs.md):

---
description: Write docstrings for the open file
---

Write docstrings for the functions/classes in the open file.
Follow the language's convention, list parameters, return
values, and errors that can be thrown. Keep it short, don't
repeat the function name.

5. /fix-issue - fix an issue by number (fix-issue.md):

---
description: Fix a GitHub issue by number
argument-hint: <issue-number>
---

Fix issue #$ARGUMENTS: read the description, find the root
cause, write a fix with tests, briefly explain the fix.

[New in 2026] Custom commands now merge with Skills

This is the big change most current guides still haven't caught up with. Per the official Claude Code Skills docs (accessed 09/08/2026), custom commands have been merged into Skills.

Concretely: a .claude/commands/deploy.md file and a .claude/skills/deploy/SKILL.md skill both create the /deploy command, using the same frontmatter mechanism. What matters for you: your old .claude/commands/*.md files still run fine - there's nothing to migrate in a hurry.

So when should you graduate to a Skill? A Skill differs from a command in two ways: (1) it's a folder, so it can hold supporting files (scripts, templates, reference docs) next to the prompt; and (2) Claude can load it automatically when it's relevant to the task at hand, without you typing a command. In short: commands are best for single, manually-invoked actions; skills are best for complex, multi-file capabilities you want to trigger on their own.

To go deeper, read what Skills are in Claude Code and then how to create a custom skill. If the concepts still blur together, the piece on skills vs subagents vs hooks vs MCP untangles them for you.

Common problems & tips

• Command doesn't show in the / menu. Check you're in the right folder - .claude/commands/ (plural, leading dot) - and the file has a .md extension. The first time you create a subfolder, restart the Claude Code session so it re-scans.
• Arguments don't expand. If your prompt has $2 but you only pass one argument, $2 stays as literal text. Use $ARGUMENTS when the number of arguments isn't fixed.
• A $ gets misread as a variable. Write \$1.00 (with a \) when you want a literal dollar sign in ordinary text.
• When NOT to make a command. If it's a one-off, or it's different every time, typing the prompt directly is faster. A command only earns its place when the action is repeated and stable. Don't package everything into commands - a bloated, rarely-used command set just clutters the / menu.

Don't want to write your own? Use a ready-made command set

Writing commands yourself is the best way to understand the mechanics and stay in control - I'd tell anyone to build at least their first few by hand. But if you'd rather have a set of commands and skills already designed and tested for common workflows, take a look at the ready-made command and skill set from AgentKit: per its homepage, it bundles 108+ skills and 45 AI agents for Claude Code, split into an Engineer Kit and a Marketing Kit. You can still customize everything like any normal .claude/commands/ file - you just don't start from zero. To see it directly, you can try AgentKit here (20% off via link); the site lists a money-back guarantee (no specific conditions stated) and lifetime updates for the kits.

Frequently asked questions (FAQ)

Where are custom slash commands stored?

In .claude/commands/ at your project root (shared with the team when you commit it to git), or ~/.claude/commands/ in your home directory (just your machine, but usable in every project). The filename minus the .md extension is the command name.

How do I pass multiple arguments to a command?

Use $ARGUMENTS to grab all the text after the command name at once, or $1, $2... for each positional argument. Wrap multi-word arguments in quotes: /rename "old id" new.

How is a custom command different from a built-in one?

Built-in commands (/help, /clear, /compact...) ship with Claude Code from Anthropic. Custom commands are ones you create as Markdown files, packaging your own or your team's prompt. Both appear together in the / menu.

Can I run terminal commands inside a command?

Yes. Use the !`<command>` syntax - the bash command runs first and its output is spliced into the prompt before Claude reads it. For example, !`git diff HEAD` lets the command grab the current diff itself.

Can commands be committed and shared with the whole team?

Yes. Put the command in .claude/commands/ at the repo root and commit it to git. Everyone who clones the repo gets the same command set, keeping the team's workflow in sync.

How is a custom command different from Skills?

As of 2026 the two have merged, and old command files still run. The difference: a command is a single prompt file, invoked by hand; a skill is a folder that can hold supporting files and can load automatically when Claude finds it relevant. Commands suit single actions, skills suit complex capabilities.

Conclusion + next steps

Custom slash commands are the cheapest way to turn repeated prompts into a shared tool: one Markdown file, one keystroke, and the whole team benefits. Start with /review and /commit, add frontmatter when you need safety, then graduate to a Skill as your workflow gets more complex. Read on with what Skills are in Claude Code and how to create a custom skill, or pop open the Claude Code cheat sheet to look up syntax anytime.