Custom Slash Commands

Custom Slash Commands

Create reusable prompts and workflows as slash commands that Claude Code can execute on demand.

Quick Reference

Frontmatter Options

Command vs Skill Decision Guide

Rule of thumb: If it fits in one file and you want explicit control, use a command. If it needs structure or auto-discovery, use a Skill.

File Structure

Project Commands (Team-Shared)

.claude/
  commands/
    commit.md           # /commit
    review.md           # /review
    frontend/
      component.md      # /component (project:frontend)
      test.md           # /test (project:frontend)
    backend/
      endpoint.md       # /endpoint (project:backend)
      test.md           # /test (project:backend)

User Commands (Personal)

~/.claude/
  commands/
    standup.md          # /standup (user)
    journal.md          # /journal (user)
    tools/
      format.md         # /format (user:tools)

Core Patterns

Pattern 1: Simple Prompt Command

# .claude/commands/review.md
Review this code for:
- Security vulnerabilities
- Performance issues
- Code style violations

Usage: /review

Pattern 2: Command with Arguments

# .claude/commands/fix-issue.md
---
argument-hint: <issue-number>
description: Fix a GitHub issue by number
---

Fix issue #$ARGUMENTS following our coding standards.
Check the issue description and implement the fix.

Usage: /fix-issue 123

Pattern 3: Positional Arguments

# .claude/commands/review-pr.md
---
argument-hint: [pr-number] [priority] [assignee]
description: Review pull request with priority
---

Review PR #$1 with priority $2 and assign to $3.
Focus on security, performance, and code style.

Usage: /review-pr 456 high alice

Pattern 4: Bash Execution

# .claude/commands/commit.md
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: Create a git commit with context
---

## Context

- Current git status: !`git status`
- Staged changes: !`git diff --cached`
- Recent commits: !`git log --oneline -5`

## Task

Create a commit message based on the staged changes.
Follow conventional commit format.

Usage: /commit

Pattern 5: File References

# .claude/commands/compare.md
---
argument-hint: <file1> <file2>
description: Compare two files
---

Compare the following files and highlight differences:

File 1: @$1
File 2: @$2

Focus on:
- API changes
- Breaking changes
- Logic differences

Usage: /compare src/old.ts src/new.ts

Pattern 6: Tool Restrictions

# .claude/commands/analyze.md
---
allowed-tools: Read, Glob, Grep
description: Analyze code without making changes
---

Analyze the codebase for patterns and issues.
Do NOT modify any files - read-only analysis.

Pattern 7: Model Override

# .claude/commands/quick-answer.md
---
model: claude-3-5-haiku-20241022
description: Quick answer using faster model
---

Quickly answer: $ARGUMENTS

Be concise. No code changes.

Pattern 8: Command with Hooks

# .claude/commands/deploy.md
---
description: Deploy with pre-flight validation
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/preflight-check.sh"
          once: true
  Stop:
    - hooks:
        - type: command
          command: "./scripts/notify-deploy.sh"
---

Deploy the current branch to the staging environment.
Ensure all tests pass before deploying.

Hooks in commands are lifecycle-scoped and only active during command execution.

Namespacing

Subdirectories group related commands and appear in descriptions:

Conflict Resolution:

• Project commands override user commands with same name
• Same-name commands in different subdirectories coexist (distinguished by description)

Variables Reference

Workflow: Creating a Command

Prerequisites

• Identify the repeated prompt or workflow
• Decide: project or user scope
• Plan arguments if dynamic

Steps

1. Create command file

   • Choose location (.claude/commands/ or ~/.claude/commands/)
   • Name file (lowercase, hyphens, .md)
   • Add frontmatter if needed

2. Write command content

   • Clear instructions for Claude
   • Add argument placeholders if needed
   • Include bash execution if needed

3. Test

   • Run /help to verify command appears
   • Execute command with test arguments
   • Verify output is as expected

Validation Checklist

• Filename is lowercase with hyphens
• Command appears in /help
• Arguments work correctly
• Bash execution has allowed-tools
• Description is helpful

Skill Tool Integration

Claude can invoke custom commands and skills programmatically via the Skill tool (replaces the deprecated SlashCommand tool).

Requirements for Skill tool invocation:

• Must have description in frontmatter
• Cannot be a built-in command
• Not blocked by disable-model-invocation: true

Character budget: Default 15,000 characters. Override with SLASH_COMMAND_TOOL_CHAR_BUDGET env var.

To encourage usage:

# In CLAUDE.md
Run /write-test when starting to write tests.

To disable:

---
disable-model-invocation: true
---

Permission Rules

Control which commands Claude can invoke via the Skill tool:

// settings.json
{
  "permissions": {
    "allow": ["Skill(/commit)", "Skill(/review-pr:*)"],
    "deny": ["Skill(/deploy:*)"]
  }
}

Migration: If you have existing SlashCommand permission rules, update them to use Skill.

Security Considerations

• Be careful with allowed-tools: Bash(*) - prefer specific patterns
• Don't expose secrets in command files
• Review project commands before committing
• Consider disable-model-invocation for sensitive commands

Reference Files