Creating Custom Slash Commands in Claude Code — Tailor Your Workflow

What Are Custom Slash Commands?

Claude Code ships with built-in slash commands like /help and /clear, but did you know you can easily add your own commands? Custom slash commands let you invoke frequently used prompts or routine tasks with a short keyword, and mastering them can dramatically speed up your daily development.

Instead of typing a long prompt like “Review the code on the current branch” every time, you can just type /review to trigger the same behavior. Share commands across your team and you can standardize review criteria or release procedures.

File Location and Format

Custom slash commands are plain Markdown files. There are two storage locations:

• Project-specific: .claude/commands/<command-name>.md
• User-wide: ~/.claude/commands/<command-name>.md

Project-specific commands can be committed to your repository and shared with teammates, while user-wide commands are available across all of your projects. The filename becomes the command name, so review.md becomes /review.

Creating Your First Command

Let’s start with the simplest possible command. Run this from your project root:

mkdir -p .claude/commands
cat > .claude/commands/review.md <<'EOF'
Read all changes currently in the Git staging area and review them
from the following perspectives:

- Potential bugs
- Naming consistency
- Missing test coverage
- Security concerns

If you find issues, report them with file names and line numbers.
EOF

That’s it. When you type /review in Claude Code, the file contents are sent as the prompt.

Accepting Arguments

To make commands more useful, let them accept arguments. Use the $ARGUMENTS placeholder inside your Markdown and whatever string you pass at invocation will be injected there.

# .claude/commands/explain.md

Please explain the following file or symbol carefully, in a way
that beginners can follow.

Target: $ARGUMENTS

Your explanation should include:
1. A one or two sentence summary of what the code does
2. A step-by-step walk-through of the important lines
3. A realistic usage example
4. Common pitfalls to avoid

Invoke it with /explain src/utils/parser.ts. The $ARGUMENTS token is replaced with src/utils/parser.ts before execution.

Commands That Reference Multiple Files

Beyond passing file paths as arguments, you can use the @ syntax inside a command to explicitly load specific files.

# .claude/commands/check-types.md

After reading @tsconfig.json and @package.json, find all type errors
across the project.

Steps:
1. Run `npx tsc --noEmit`
2. Group errors by file
3. Suggest a fix priority order
4. Sort by the size of the impacted area first

Please output the result as a table.

Claude automatically reads tsconfig.json and package.json before starting work on the command.

In Practice: A Release Prep Command

Here’s an example that wraps a typical release workflow into a single command.

# .claude/commands/release.md

Prepare the release for version $ARGUMENTS.

Steps:
1. Update the `version` field in package.json to $ARGUMENTS
2. Prepend a new section to CHANGELOG.md
   - Reference the git log since the previous tag
   - Categorize into feat / fix / docs / chore
3. Run `npm run test` and confirm all tests pass
4. Run `npm run build` and confirm there are no build errors
5. Summarize the changes and propose a commit message

Important: Do not run `git push` or `npm publish` yourself.
Leave the final confirmation to the user.

Typing /release 1.4.0 handles everything from version bumps to running tests. For safety, avoid destructive operations and let a human confirm the final step.

Simulating Flags and Options

You can describe branching logic in Markdown to simulate flags.

# .claude/commands/test.md

Arguments: $ARGUMENTS

Follow these rules:

- If the arguments are empty: run all tests
- If arguments contain `--unit`: run only unit tests
- If arguments contain `--e2e`: run only E2E tests
- If a file path is included: run only tests related to that file

After running, analyze the cause of any failing tests.

Calls like /test --unit or /test src/auth.ts become possible.

Best Practices for Team Sharing

Put project-specific commands under .claude/commands/ and manage them with Git so every team member uses the same commands. Keep these in mind:

• Use a consistent naming convention: verb-first, short names (review, fix, explain)
• Document them in the README: make commands easy to discover
• Avoid destructive operations: explicitly forbid things like git push --force or rm -rf
• Specify the output format: keep review results consistent with tables or checklists

Wrapping Up

Custom slash commands are the shortest path to turning Claude Code into “your own personal AI assistant.” Start with one or two simple commands and add more whenever you spot a repetitive task. Before long, they’ll become an indispensable part of your workflow.

For Claude Code basics, see the getting started guide. For more advanced automation, see Getting Started with Agent SDK, and for tips on context, check out Context Management.

For official documentation, refer to the Anthropic documentation.