How to Create Custom Slash Commands in Claude Code

This post is a quick memo on how to create custom slash commands in Claude Code.

Introduction
What Are Custom Slash Commands in Claude Code?
How to Create Custom Slash Commands
- Basic Syntax and Example Commands
Conclusion
References

Introduction

I use Claude Code regularly for coding.

However, I’ve never created a custom slash command myself before, so I'm writing this note to document the process.

# Environment
$ claude --version
1.0.113 (Claude Code)

Note: This article was translated from my original post.

What Are Custom Slash Commands in Claude Code?

Claude Code offers a convenient feature called slash commands, like:

/clear
/init
/compact

Custom slash commands are user-defined commands, similar to these built-in commands.

In short, they let you predefine prompts in Markdown files and call them up instantly with a command.

How to Create Custom Slash Commands

You can create custom slash commands by placing Markdown files under .claude/commands/. The file name becomes the slash command name.

Depending on where you place the .claude/commands/ directory, there are two types of commands:

Project Commands:
When you place Markdown files in the .claude/commands/ directory inside your project folder, the commands are only available within that project.
They can be shared across the team using the repository.
Personal Commands:
Commands placed in ~/.claude/commands/ are available across all projects and for your use only.

Now let’s look at some concrete examples of how to create custom slash commands.

Basic Syntax and Example Commands

Prompt Only

To make a simple slash command, just create a Markdown file with the command name in .claude/commands/ and write the prompt inside.

Example:

.claude/commands/analyze.md:

Analyze this code and explain the architecture.

That’s it! You can now run /analyze in Claude Code to trigger this command.

Now, let’s go over other useful features available when defining custom slash commands.

Arguments

Custom slash commands can take arguments like this: /<command-name> [arguments].

You can use positional arguments like $1, $2, or capture all with $ARGUMENTS.

Example:

.claude/commands/fix-issue.md:

Fix issue #$1 with priority $2.

Usage:

/fix-issue 123 high

Running Bash Commands

If you specify allowed-tools in the frontmatter, you can execute bash commands and embed the output in your prompt. (We’ll cover frontmatter in more detail later.)

Prefix the command with ! to execute it.

Example: A command to read Git diffs and explain them.

.claude/commands/git-diff.md:

---
allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)
description: Explain the git diff
---

# Context
- Current git status: !`git status`
- Current git diff: !`git diff HEAD`

# Task
Based on the above changes, explain the git diff

Running /git-diff will fetch the current changes and give an explanation.

File Reference

If you want to embed file contents, use @<file path>.

Example:

Compare @src/old-version.js with @src/new-version.js and summarize the differences.

This reads the actual files and inserts their contents into the prompt.

Frontmatter

As mentioned in the "Running Bash Commands" section, you can use frontmatter to define metadata for your slash command. (Frontmatter is a metadata block at the top of Markdown documents.)

Available metadata fields include:

allowed-tools: Tools allowed for use (Tool docs)
argument-hint: Hints for argument input (shown as autocomplete suggestions)
description: Description of the command
model: Model to be used

Example:

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: Create a git commit
model: claude-3-5-haiku-20241022
---

Create a git commit with message: $ARGUMENTS