Create Slash Command Guide

This skill helps you create custom Claude Code slash commands - reusable prompts stored as Markdown files that can be invoked with /command-name syntax. Slash commands are ideal for frequently-used prompts that you want to trigger explicitly.

Quick Start

When creating a new slash command, follow this workflow:

1. Identify the purpose - What reusable prompt do you need?
2. Choose scope - Project-level (.claude/commands/) or personal (~/.claude/commands/)?
3. Select name - Clear, descriptive filename without .md extension
4. Design arguments - Will it use $ARGUMENTS, $1/$2/$3, or none?
5. Add frontmatter - Optional metadata (description, tools, model)
6. Write prompt - The markdown content that becomes the prompt
7. Test invocation - Verify command works with various arguments

Basic Syntax

Commands are invoked with:

/command-name [arguments]

The command name comes from the filename without .md extension.

File Locations

Project Commands (.claude/commands/)

• Scope: Project-specific, shared with team via git
• Label: Shows as "(project)" in help listing
• Use for: Team workflows, project conventions, shared prompts

# Create project command
echo "Review this code for security vulnerabilities" > .claude/commands/security-review.md

Example structure:

.claude/commands/
├── review.md           # /review
├── optimize.md         # /optimize
├── test.md            # /test
└── frontend/
    └── component.md   # /component (project:frontend)

Personal Commands (~/.claude/commands/)

• Scope: Available across all projects
• Label: Shows as "(user)" in help listing
• Use for: Personal productivity, individual workflows, cross-project utilities

# Create personal command
echo "Explain this code in simple terms" > ~/.claude/commands/explain.md

Example structure:

~/.claude/commands/
├── explain.md         # /explain (user)
├── refactor.md        # /refactor (user)
└── snippets/
    └── doc.md         # /doc (user:snippets)

Argument Handling

No Arguments

Simple commands that don't need input:

Review the current codebase for potential improvements and suggest optimizations.

Usage: /review

All Arguments with $ARGUMENTS

Captures everything passed to the command:

Fix issue #$ARGUMENTS following our coding standards and best practices.

Usage:

• /fix-issue 123
• /fix-issue 123 high-priority security

Positional Arguments with $1, $2, $3, etc.

Access specific arguments by position:

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

Usage: /review-pr 456 high alice

Benefits:

• Access arguments in different parts of the prompt
• Provide defaults for missing arguments
• Build structured commands with specific parameter roles
• Clearer intent for multi-parameter commands

Combining Arguments

Use both positional and all arguments:

Create a $1 feature called "$2" with the following requirements:

$ARGUMENTS

Usage: /create-feature backend "user authentication" JWT tokens, role-based access, password hashing

Frontmatter Configuration

Add optional metadata at the top of your command file:

---
allowed-tools: Read, Write, Edit, Bash
argument-hint: <issue-number> [priority]
description: Fix GitHub issue following coding standards
model: claude-3-5-sonnet-20241022
---

Your command prompt content goes here...

Frontmatter Fields

allowed-tools: Restrict which tools Claude can use

allowed-tools: Read, Write, Edit, Bash
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)

argument-hint: Show expected arguments in autocomplete

argument-hint: <file-path>
argument-hint: <pr-number> [priority] [assignee]
argument-hint: [message]

description: Brief command description (overrides first line)

description: Create a git commit with proper formatting

model: Specific model to use for this command

model: claude-3-5-haiku-20241022      # Fast, cheap
model: claude-3-5-sonnet-20241022     # Balanced
model: claude-opus-4-20250514         # Advanced

disable-model-invocation: Prevent auto-invocation via SlashCommand tool

disable-model-invocation: true

Advanced Features

File References with @

Include file contents in your command:

---
description: Review code implementation
---

Review the implementation in @src/utils/helpers.js and compare it with @src/utils/legacy.js.

Identify:
- Code quality improvements
- Performance optimizations
- Security vulnerabilities

Usage: /review-implementation

Bash Command Execution with !

Execute bash commands and include output (requires allowed-tools):

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit
---

Create a git commit with the following context:

**Current Status:**
!`git status`

**Recent Changes:**
!`git diff HEAD`

**Commit Message:** $ARGUMENTS

Usage: /commit "Add user authentication feature"

Extended Thinking

Trigger extended reasoning by including keywords in the command content:

---
description: Analyze complex architectural decisions
---

Please use extended thinking to analyze the following architectural decision:

$ARGUMENTS

Consider:
- Scalability implications
- Maintenance overhead
- Team expertise requirements
- Long-term technical debt

Namespacing with Subdirectories

Organize commands in subdirectories (affects description, not command name):

.claude/commands/
├── git/
│   ├── commit.md     # /commit (project:git)
│   └── review.md     # /review (project:git)
└── frontend/
    └── component.md  # /component (project:frontend)

The subdirectory appears in the description but doesn't change the command invocation.

Complete Examples

1. Simple Code Review Command

File: .claude/commands/review.md

---
description: Comprehensive code review for quality and security
---

Review this code for:
- Code quality and maintainability
- Security vulnerabilities
- Performance optimizations
- Best practices adherence
- Potential bugs or edge cases

Provide specific, actionable feedback with code examples.

Usage: /review

2. Issue Fix Command with Arguments

File: .claude/commands/fix-issue.md

---
argument-hint: <issue-number> [priority]
description: Fix GitHub issue following coding standards
---

Fix issue #$1 following our coding standards.

Priority: $2

Steps:
1. Read the issue details from GitHub
2. Analyze the problem and root cause
3. Implement the fix with tests
4. Update documentation if needed
5. Create a commit with proper message format

Usage:

• /fix-issue 123 high
• /fix-issue 456

3. PR Creation with Template

File: .claude/commands/create-pr.md

---
allowed-tools: Bash(git *), Read, Write
argument-hint: <title> [description]
description: Create GitHub pull request with template
model: claude-3-5-sonnet-20241022
---

Create a GitHub pull request with the following details:

**Title:** $1

**Description:** $2

**Context:**

**Current Branch:**
!`git branch --show-current`

**Changes:**
!`git diff main...HEAD --stat`

**Commits:**
!`git log main..HEAD --oneline`

Generate a comprehensive PR description following our template at @.github/pull_request_template.md

Usage: /create-pr "Add user authentication" "Implements JWT-based authentication system"

4. Test Runner Command

File: .claude/commands/test.md

---
allowed-tools: Bash, Read, Grep
argument-hint: [file-pattern]
description: Run tests and analyze failures
model: claude-3-5-haiku-20241022
---

Run tests matching pattern: $ARGUMENTS

Steps:
1. Execute test suite
2. Analyze any failures
3. Suggest fixes for failing tests
4. Validate fixes and re-run

Provide clear, actionable feedback on test failures.

Usage:

• /test
• /test auth
• /test src/components/Button.test.ts

5. Documentation Generator

File: .claude/commands/document.md

---
allowed-tools: Read, Write, Grep, Glob
description: Generate comprehensive documentation
---

Generate comprehensive documentation for: $ARGUMENTS

Include:
- Overview and purpose
- API reference
- Usage examples
- Configuration options
- Best practices
- Common pitfalls

Format output in clear, professional markdown.

Usage: /document src/utils/api-client.ts

6. Code Optimization Command

File: .claude/commands/optimize.md

---
description: Analyze and optimize code performance
---

Analyze this code for performance optimizations:

$ARGUMENTS

Focus on:
- Algorithm complexity (O(n) analysis)
- Memory usage and allocations
- Database query efficiency
- Caching opportunities
- Parallel processing potential
- Resource cleanup and lifecycle management

Provide specific refactoring suggestions with before/after examples.

Usage: /optimize

7. Multi-Argument PR Review

File: .claude/commands/review-pr.md

---
allowed-tools: Bash(gh *), Read
argument-hint: <pr-number> <priority> [assignee]
description: Review pull request with priority and assignment
---

Review PR #$1 with priority: $2

**PR Details:**
!`gh pr view $1`

**Changes:**
!`gh pr diff $1`

Review focus areas based on priority $2:
- high: Security, breaking changes, data integrity
- medium: Code quality, tests, documentation
- low: Style, minor improvements

Assign to: $3 (if provided)

Provide comprehensive feedback organized by:
1. Critical issues (blocking)
2. Important suggestions
3. Minor improvements
4. Positive observations

Usage: /review-pr 123 high alice

8. Git Workflow Command

File: .claude/commands/git-flow.md

---
allowed-tools: Bash(git *)
argument-hint: <action> <branch-name>
description: Execute git workflow actions
---

Execute git workflow action: $1

Branch: $2

**Current Status:**
!`git status`

**Available Branches:**
!`git branch -a`

Actions:
- start: Create and checkout new branch
- finish: Merge branch and delete
- sync: Pull latest and rebase
- review: Show branch diff

Additional context: $ARGUMENTS

Usage:

• /git-flow start feature/auth
• /git-flow finish bugfix/login
• /git-flow sync

9. Database Query Optimization

File: ~/.claude/commands/optimize-query.md

---
description: Optimize database queries for performance
---

Analyze and optimize this database query:

$ARGUMENTS

Optimization checklist:
- [ ] Execution plan analysis
- [ ] Index usage and recommendations
- [ ] Query rewrite opportunities
- [ ] JOIN optimization
- [ ] Subquery vs JOIN performance
- [ ] Parameter binding and caching
- [ ] Result set size and pagination

Provide:
1. Performance analysis
2. Optimized query
3. Index recommendations
4. Before/after execution plan comparison

Usage: /optimize-query

10. Complex Issue Creation

File: .claude/commands/create-issue.md

---
allowed-tools: Bash(gh *), Read
argument-hint: <title> <type>
description: Create detailed GitHub issue with template
model: claude-3-5-sonnet-20241022
---

Create a GitHub issue with:

**Title:** $1
**Type:** $2 (feature/bug/enhancement/docs)

**Repository Analysis:**
!`gh repo view --json name,description,url`

**Template:**
@.github/ISSUE_TEMPLATE/$2.md

Generate a comprehensive issue following our template structure with:
- Clear problem statement
- Proposed solution
- Acceptance criteria
- Implementation notes
- Related issues/PRs

Additional context: $ARGUMENTS

Usage: /create-issue "Add dark mode support" feature "Users want theme customization"

Slash Commands vs Skills

When to Use Slash Commands

Characteristics:

• Explicit invocation required (/command)
• Quick, frequently-used prompts
• Simple prompt snippets
• Single-file capabilities
• Manual control over execution

Best for:

• Code review workflows (/review)
• Quick explanations (/explain)
• Frequent operations (/optimize, /test)
• Personal productivity shortcuts
• Team-standardized prompts

When to Use Skills

Characteristics:

• Automatic discovery based on context
• Claude decides when to invoke
• Complex workflows with multiple steps
• Multiple files (scripts, templates, docs)
• Advanced capabilities

Best for:

• PDF processing (auto-invoked when user mentions PDFs)
• API documentation generation (auto-invoked for API tasks)
• Complex multi-step workflows
• Capabilities requiring external scripts
• Knowledge organized across multiple files

Can They Coexist?

Yes! Use both approaches:

• Commands: Explicit, manual shortcuts (/review-pr)
• Skills: Automatic, context-driven capabilities (PDF extraction)

Best Practices Checklist

When creating a slash command:

• Filename is descriptive and uses kebab-case
• File location matches scope (project vs personal)
• Description frontmatter is clear and concise
• Arguments are well-documented with argument-hint
• Prompt content is specific and actionable
• File references (@) use correct paths
• Bash commands (!) have proper tool restrictions
• Model selection matches complexity (haiku/sonnet/opus)
• Command tested with various argument combinations
• Related commands organized in subdirectories
• No sensitive data (credentials, API keys) in commands
• Clear examples in comments or description

Testing Slash Commands

1. Verify Command Appears

List all available commands:

# In Claude Code
/help

Look for your command in the output.

2. Test Basic Invocation

/your-command

Verify the prompt expands correctly.

3. Test with Arguments

/your-command arg1
/your-command arg1 arg2 arg3

Verify argument substitution works.

4. Test File References

If using @file.txt, verify the file exists and is readable.

5. Test Bash Commands

If using !command, verify:

• Command executes successfully
• Output is captured correctly
• Tool restrictions are appropriate

Common Issues

Command not appearing:

• Check filename has .md extension
• Verify file is in correct location (.claude/commands/ or ~/.claude/commands/)
• Restart Claude Code to reload commands

Arguments not substituting:

• Ensure $ARGUMENTS, $1, $2 syntax is correct
• Check for extra spaces or special characters
• Verify arguments are passed when invoking

File references not working:

• Confirm file path is correct (relative to project root)
• Check file exists and is readable
• Verify @ prefix is present

Bash commands failing:

• Add allowed-tools: Bash to frontmatter
• Verify command works independently
• Check tool restriction patterns (e.g., Bash(git *))

Description not showing:

• Add description field in frontmatter
• Ensure frontmatter YAML is valid (opening/closing ---)

Organization Strategies

By Feature Area

.claude/commands/
├── git/
│   ├── commit.md
│   ├── review.md
│   └── workflow.md
├── testing/
│   ├── run.md
│   ├── coverage.md
│   └── debug.md
└── docs/
    ├── generate.md
    └── update.md

By Complexity

~/.claude/commands/
├── quick/         # Simple, haiku-model commands
│   ├── explain.md
│   └── format.md
├── standard/      # Regular sonnet commands
│   ├── review.md
│   └── optimize.md
└── complex/       # Advanced opus commands
    └── architect.md

By Team Role

.claude/commands/
├── frontend/
│   ├── component.md
│   └── style.md
├── backend/
│   ├── api.md
│   └── database.md
└── devops/
    ├── deploy.md
    └── monitor.md

Migration from Skills

Converting a skill to a slash command:

Skill (automatic invocation):

---
name: code-explainer
description: Explain code in simple terms when user asks
---

# Code Explainer
Instructions for explaining code...

Slash Command (explicit invocation):

---
description: Explain code in simple terms
---

Explain this code in simple, beginner-friendly terms:

$ARGUMENTS

Include:
- What the code does
- How it works
- Why it's structured this way
- Common use cases

Usage: /explain

Security Considerations

Avoid:

• Hardcoding credentials or API keys
• Network calls without encryption
• Destructive commands without confirmation
• Accessing sensitive files unnecessarily

Safe practices:

• Use environment variables for secrets
• Validate file paths before access
• Restrict bash command patterns
• Log command execution for audit trails

Advanced Patterns

Template-Based Commands

---
description: Create component from template
---

Create a new $1 component named $2:

**Template:**
@templates/$1-template.tsx

**Destination:**
src/components/$2/

Generate files:
1. Component implementation
2. Test file
3. Styles
4. Documentation
5. Storybook story

Usage: /create-component button UserProfileButton

Multi-Step Workflows

---
allowed-tools: Bash, Read, Write, Edit
description: Complete feature implementation workflow
---

Implement feature: $ARGUMENTS

Workflow:
1. Create feature branch
2. Generate boilerplate code
3. Implement core logic
4. Add tests
5. Update documentation
6. Run quality checks
7. Create PR

Execute each step with confirmation.

Usage: /feature-workflow "user authentication"

Context-Rich Commands

---
allowed-tools: Bash(git *), Read
description: Comprehensive code review with full context
---

Review code with full context:

**Project Structure:**
!`find . -type f -name "*.ts" -o -name "*.tsx" | head -20`

**Recent Changes:**
!`git log --oneline -10`

**Modified Files:**
!`git diff --name-only HEAD~5..HEAD`

**Code to Review:**
$ARGUMENTS

Provide comprehensive feedback considering project context.

Key Principles

1. Descriptive names - Clear, action-oriented command names
2. Explicit invocation - Users trigger commands intentionally
3. Argument clarity - Use argument-hint for discoverability
4. Scope appropriately - Project commands for team, personal for you
5. Tool restrictions - Only grant necessary tool access
6. Model selection - Match model to task complexity
7. Organization - Use subdirectories for related commands
8. Documentation - Clear descriptions and argument hints
9. Testing - Verify with various inputs before sharing
10. Security - Never hardcode sensitive data

Workflow Summary

When user asks to create a slash command:

1. Clarify purpose - What prompt should be reusable?
2. Choose scope - Project or personal command?
3. Design arguments - $ARGUMENTS, $1/$2/$3, or none?
4. Select name - Descriptive, kebab-case filename
5. Add frontmatter - Description, tools, model, argument-hint
6. Write prompt - Clear, actionable command content
7. Add features - File references (@), bash commands (!)
8. Test thoroughly - Various arguments, edge cases
9. Document usage - Examples in comments or description
10. Share if needed - Commit project commands to git

Remember: Slash commands are for explicit, manual invocation of frequently-used prompts. Use skills for automatic, context-driven capabilities.