custom-slash-commands

Comprehensive guide to creating and using custom slash commands in Claude Code.

Overview

Custom slash commands allow you to create reusable prompts that can be invoked quickly with a simple syntax. Commands are markdown files that get expanded into full prompts when executed.

Invocation Pattern:

/<command-name> [arguments]

File Structure & Locations

Project-Level Commands

.claude/commands/command-name.md
.claude/commands/category/command-name.md  # Organized in subdirectories

• Shared with team members via version control
• Project-specific workflows

Personal Commands

~/.claude/commands/command-name.md
~/.claude/commands/category/command-name.md

• Available across all projects
• Personal preferences and workflows

Key Points:

• Filename (without .md) becomes the command name
• Subdirectories organize commands without affecting invocation
• optimize.md → /optimize command

Basic Command Creation

Simple Command:

Review the current changes and provide feedback on:
1. Code quality and best practices
2. Potential bugs or edge cases
3. Performance considerations
4. Test coverage

Usage: /review

Arguments

Capture All Arguments with $ARGUMENTS

Use $ARGUMENTS as a placeholder for all arguments passed to the command:

Find and fix issue #$ARGUMENTS. Follow these steps:
1. Understand the issue described in the ticket
2. Locate the relevant code
3. Implement a solution
4. Add appropriate tests
5. Prepare a PR description

Usage: /fix-issue 123 → replaces $ARGUMENTS with “123”

Positional Arguments

Access individual arguments using $1, $2, $3, etc.:

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

Focus areas:
- Code quality
- Test coverage
- Documentation updates

Usage: /review-pr 456 high @engineer

Benefits:

• Use arguments in different parts of the command
• Provide default values
• More granular control

Advanced Features

Frontmatter Configuration

Commands support optional YAML frontmatter for metadata and configuration:

---
description: Bootstrap project architecture documentation
model: claude-sonnet-4-5-20250929
allowed-tools: Bash(git status:*), Bash(git log:*)
argument-hint: [project-type]
disable-model-invocation: false
---

Initialize complete architecture documentation for this $1 project:

1. Analyze entire codebase for technology stack
2. Generate C4 architecture documentation
3. Create ADRs for discovered technology decisions
4. Validate that architectural entities are documented

Frontmatter Fields

Bash Integration

Execute shell commands within slash commands using the ! prefix:

---
description: Create feature branch and initial commit
allowed-tools: Bash(git checkout:*), Bash(git commit:*)
argument-hint: <feature-name>
---

Create a new feature branch for: $ARGUMENTS

!git checkout -b feature/$ARGUMENTS
!git commit --allow-empty -m "feat: Initialize $ARGUMENTS feature"

Branch created! Ready to start development.

Important: Must declare allowed Bash commands in frontmatter for security.

File References

Include file contents using the @ prefix:

---
description: Analyze component for optimization opportunities
---

Analyze this component for performance improvements:

@src/components/$ARGUMENTS.tsx

Focus on:
- Unnecessary re-renders
- Memoization opportunities
- Bundle size impact

Usage: /analyze-component Header includes contents of src/components/Header.tsx

Command Organization Patterns

By Workflow Type

.claude/commands/
├── dev/
│   ├── fix-issue.md
│   ├── review-pr.md
│   └── refactor.md
├── docs/
│   ├── bootstrap.md
│   ├── update-readme.md
│   └── generate-api-docs.md
└── testing/
    ├── generate-tests.md
    └── run-coverage.md

By Technology

.claude/commands/
├── react/
│   ├── create-component.md
│   └── optimize-component.md
├── node/
│   ├── add-endpoint.md
│   └── update-deps.md
└── python/
    ├── add-test.md
    └── profile-function.md

Plugin & MCP Commands

Plugin Commands

Format: /plugin-name:command-name

• Automatically discovered when plugins installed
• Provided by plugin authors

MCP Commands

Format: /mcp__<server-name>__<prompt-name>

• Dynamically exposed by MCP servers
• Follow MCP protocol conventions

Example: /mcp__temporal-bridge__search_personal

SlashCommand Tool

Claude can programmatically invoke slash commands during conversations using the SlashCommand tool:

// Claude's internal tool usage
SlashCommand("/review-pr 123")

Permission Rules:

• Exact match: SlashCommand:/review-pr
• Prefix-based: SlashCommand:/review-pr:*

Built-in Commands (Reference)

Claude Code provides ~25 built-in commands:

Conversation Control

• /clear - Clear conversation history
• /compact - Compact conversation to save tokens
• /rewind - Rewind to previous state

Configuration

• /config - View/edit configuration
• /status - Show current status
• /model - Change model
• /permissions - Manage permissions

Development Tools

• /review - Code review mode
• /sandbox - Sandbox environment
• /terminal-setup - Terminal configuration

Account Management

• /login - Authenticate
• /logout - Sign out

Utilities

• /help - Show help
• /cost - Show API costs
• /usage - Show usage stats
• /doctor - Diagnose issues

Best Practices

Command Design

1. Single Responsibility: Each command should do one thing well
2. Clear Naming: Use descriptive, action-oriented names
3. Good Defaults: Minimize required arguments when possible
4. Documentation: Include clear descriptions in frontmatter

Argument Usage

1. Use $ARGUMENTS for single, flexible inputs
2. Use positional $1, $2, etc. for structured multi-part inputs
3. Always provide argument-hint in frontmatter for discoverability

Organization

1. Group related commands in subdirectories
2. Use consistent naming conventions
3. Keep project commands focused on team workflows
4. Use personal commands for individual preferences

Security

1. Always specify allowed-tools when using Bash
2. Be specific about allowed commands (use patterns like git status:*)
3. Avoid exposing sensitive information in version-controlled commands

Example Commands

Bootstrap Architecture Documentation

---
description: Bootstrap project architecture documentation
model: claude-sonnet-4-5-20250929
argument-hint: [project-type]
---

Initialize complete architecture documentation for this project:

1. **Analyze entire codebase** for technology stack, patterns, and components
2. **Generate C4 documentation** (Context, Container, Component, Code levels)
3. **Create ADRs** for discovered technology and architectural decisions
4. **Validate** that architectural entities are searchable

Project type: $1

Use proper YAML frontmatter with component_type, c4_layer, and status values.

Fix GitHub Issue

---
description: Find and fix a GitHub issue end-to-end
argument-hint: <issue-number>
allowed-tools: Bash(git:*)
---

Find and fix issue #$ARGUMENTS:

1. **Understand** the issue from the GitHub ticket
2. **Locate** the relevant code files
3. **Implement** a solution following our coding standards
4. **Add tests** to prevent regression
5. **Commit** with conventional commit message
6. **Prepare** PR description with testing steps

!git branch feature/issue-$ARGUMENTS
!git checkout feature/issue-$ARGUMENTS

Generate Component Tests

---
description: Generate comprehensive tests for a component
argument-hint: <component-path>
---

Generate tests for the component at: $ARGUMENTS

Include:
- **Unit tests** for all exported functions
- **Integration tests** for component behavior
- **Edge cases** and error scenarios
- **Snapshot tests** for UI components
- **Accessibility tests** where applicable

Use existing test patterns from the codebase.
@$ARGUMENTS

Code Translation

---
description: Translate code between languages
argument-hint: <from-language> <to-language>
---

Translate the following code from $1 to $2:

$3

Ensure:
- Idiomatic patterns for target language
- Appropriate type safety
- Performance considerations
- Comments explaining non-obvious conversions

Comparison: Slash Commands vs Agents

Recommendation: Use slash commands for standard, repeatable workflows. Use agents for complex scenarios requiring natural language flexibility.

Resources

Official Documentation:

• Common Workflows - Custom Slash Commands
• Slash Commands Reference
• Documentation Index

Getting Started:

1. Create .claude/commands/ directory in your project
2. Add a simple .md file (e.g., hello.md with content “Say hello!”)
3. Type / in Claude Code to see your command
4. Invoke with /hello

Last Updated: 2025-11-05 Claude Code Version: Latest (Sonnet 4.5 Compatible)