Claude Code Custom Commands

Claude Code Custom Commands

Reference documentation for creating and using custom slash commands in Claude Code.

Overview

Custom slash commands are markdown files that define frequently used prompts. They're stored in special directories and invoked using the / prefix.

┌─────────────────────────────────────────────────────────────────┐
│                     Command Invocation Flow                      │
├─────────────────────────────────────────────────────────────────┤
│  User types /command → Claude loads command.md → Executes prompt │
└─────────────────────────────────────────────────────────────────┘

Command Locations

Global Commands (All Projects)

~/.claude/commands/
├── webtest.md        → /webtest
├── review.md         → /review
└── deploy.md         → /deploy

Project Commands (Team Shared)

<project-root>/.claude/commands/
├── fix-issue.md      → /fix-issue
└── frontend/
    └── test.md       → /test (project:frontend)

Priority: Project commands override global commands with the same name.

Basic Syntax

The filename (without .md) becomes the command name:

# Create a simple command
mkdir -p ~/.claude/commands
echo "Review this code for security vulnerabilities:" > ~/.claude/commands/security-review.md

Usage: /security-review

Frontmatter Configuration

Add metadata using YAML frontmatter:

---
description: Test new features using browser automation
allowed-tools: Bash(npm run:*), Bash(playwright:*)
argument-hint: [feature-name]
model: claude-3-5-haiku-20241022
---

Your prompt here with $ARGUMENTS placeholder.

Available Frontmatter Fields

Arguments

All Arguments: $ARGUMENTS

Fix issue #$ARGUMENTS following our coding standards.

Usage: /fix-issue 123 → $ARGUMENTS becomes "123"

Positional Arguments: $1, $2, etc.

Review PR #$1 with priority $2 and assign to $3.

Usage: /review-pr 456 high alice → $1="456", $2="high", $3="alice"

Advanced Features

Bash Command Execution

Include bash output using the ! prefix:

Current branch: !`git branch --show-current`
Current diff: !`git diff HEAD`

Create a commit based on the above changes.

File References

Include file contents using the @ prefix:

Review the implementation in @src/utils/helpers.js
Compare @src/old-version.js with @src/new-version.js

Extended Thinking

Enable thinking mode by including the keyword:

Use extended thinking to thoroughly analyze this architecture.

Current Global Commands

Commands vs Skills vs Hooks

Use commands for:

• Frequently used prompts
• Quick shortcuts for common tasks
• Simple parameterized actions

Use skills for:

• Complex domain knowledge
• Multi-file reference documentation
• Patterns requiring examples and context

Use hooks for:

• Session startup/stop enforcement
• Automatic compliance checks
• Context injection

Creating Custom Commands

Step 1: Create the File

mkdir -p ~/.claude/commands
cat > ~/.claude/commands/my-command.md << 'EOF'
---
description: Brief description for /help
argument-hint: [arg1] [arg2]
---

Your prompt here. Use $ARGUMENTS or $1, $2 for parameters.
EOF

Step 2: Test

> /my-command arg1 arg2

Step 3: Verify in Help

> /help

Your command should appear with "(user)" suffix.

Namespacing with Subdirectories

Organize related commands in subdirectories:

.claude/commands/
├── review.md                → /review
├── frontend/
│   ├── component.md        → /component (project:frontend)
│   └── test.md             → /test (project:frontend)
└── backend/
    └── test.md             → /test (project:backend)

Best Practices

1. Use descriptive filenames for clarity
2. Add frontmatter descriptions so commands appear helpful in /help
3. Commit project commands to git to share with team
4. Keep commands focused - one task per command
5. Test with arguments to ensure placeholders work correctly
6. Use subdirectories to organize related commands

Related Documentation

• Hooks Reference - Lifecycle event handlers
• Skills Reference - Domain-specific knowledge injection
• Config Files - Actual command/hook/skill files for installation
• Official Commands Documentation - Anthropic reference