Claude Command Authoring

Create custom slash commands that extend Claude Code with frequently-used prompts and workflows.

Overview

Slash commands are Markdown files that define reusable prompts. They support:

• Arguments: $1, $2, $ARGUMENTS
• Bash execution: ! prefix for command output
• File references: @ prefix to include file contents
• Frontmatter: Metadata for configuration
• Namespacing: Organize in subdirectories

Quick Start

Basic Command

# Create a simple command
mkdir -p .claude/commands
cat > .claude/commands/review.md << 'EOF'
---
description: Review code for best practices and potential issues
---

Review the following code for:
- Code quality and readability
- Potential bugs or edge cases
- Performance considerations
- Security concerns
EOF

# Use it
/review

Command with Arguments

---
description: Fix a specific issue by number
argument-hint: <issue-number>
---

Fix issue #$1 following our coding standards and best practices.
Review the issue details, implement a fix, add tests, and create a commit.

Command with Bash Execution

---
description: Create a git commit from staged changes
allowed-tools: Bash(git *)
---

## Context

Current branch: !`git branch --show-current`
Staged changes: !`git diff --staged`
Recent commits: !`git log --oneline -5`

## Task

Create a single commit with a clear message based on the staged changes above.

Command with File References

---
description: Compare two implementations
argument-hint: <file1> <file2>
---

Compare these two implementations and explain the differences:

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

Provide a detailed comparison focusing on architecture, performance, and maintainability.

Command Scopes

Project Commands (.claude/commands/)

• Shared with your team via git
• Show "(project)" in /help
• Team-specific workflows

Personal Commands (~/.claude/commands/)

• Available across all your projects
• Show "(user)" in /help
• Individual preferences

Plugin Commands (plugin/commands/)

• Bundled with plugins
• Show "(plugin-name)" in /help
• Distributed via marketplaces

Frontmatter Options

| Field | Purpose | Example | |-------|---------|---------| | description | Brief description shown in /help | "Deploy to staging environment" | | argument-hint | Expected arguments for autocomplete | "<environment> [--skip-tests]" | | allowed-tools | Restrict tool usage | "Bash(git *), Read, Write" | | model | Specific model to use | "claude-3-5-haiku-20241022" | | disable-model-invocation | Prevent SlashCommand tool usage | true |

Argument Handling

All Arguments ($ARGUMENTS)

Fix issues: $ARGUMENTS

Usage: /fix-issues 123 456 789 → $ARGUMENTS = "123 456 789"

Individual Arguments ($1, $2, $3, ...)

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

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

Combining Arguments with Files

Compare @$1 with @$2 and summarize differences

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

Bash Execution with !

Execute bash commands before the prompt runs:

---
description: Show current project status
---

## Git Status
!`git status`

## Recent Activity
!`git log --oneline -10`

## Uncommitted Changes
!`git diff`

Based on the above, provide a summary of the current project state.

Output truncation: Commands producing >15,000 chars are truncated by default. Set SLASH_COMMAND_TOOL_CHAR_BUDGET environment variable to adjust.

File References with @

Include file contents in your command:

---
description: Explain a specific file
argument-hint: <file-path>
---

# File Analysis

**File**: @$1

Provide a detailed explanation of:
1. Purpose and responsibility
2. Key functions and methods
3. Dependencies and imports
4. Potential improvements

Namespacing

Organize commands in subdirectories:

.claude/commands/
├── frontend/
│   ├── component.md      → /component (project:frontend)
│   └── styling.md        → /styling (project:frontend)
└── backend/
    ├── migration.md      → /migration (project:backend)
    └── testing.md        → /testing (project:backend)

Access: /component or /frontend/component

Tool Restrictions

Limit what tools Claude can use:

---
description: Safe code review (read-only)
allowed-tools: Read, Grep, Glob
---

Review the codebase for issues without making any changes.

Claude can only use specified tools without asking permission.

Best Practices

1. Clear Descriptions

---
# ❌ Too vague
description: Deploy stuff

# ✅ Specific and helpful
description: Deploy to staging with health checks and Slack notification
---

2. Helpful Argument Hints

---
# ❌ Not helpful
argument-hint: args

# ✅ Clear expectations
argument-hint: <environment> [--skip-tests] [--no-notify]
---

3. Context Before Instructions

---
description: Create feature branch from issue
---

## Context
Current branch: !`git branch --show-current`
Issue: $1

## Task
1. Fetch latest changes
2. Create feature branch: feature/$1
3. Push to remote with tracking

4. Use Tool Restrictions

---
description: Security audit (read-only)
allowed-tools: Read, Grep, Glob, Bash(find:*)
---

5. Document Complex Commands

---
description: Full deployment pipeline with validation
---

# Deployment Pipeline

This command runs the complete deployment process:

1. **Pre-flight**: Runs test suite
2. **Build**: Creates Docker image
3. **Deploy**: Updates Kubernetes
4. **Validate**: Health checks
5. **Notify**: Posts to Slack

## Usage
- `/deploy staging` - Deploy to staging
- `/deploy production` - Deploy to production
- `/deploy staging --skip-tests` - Skip test suite

## Requirements
- Docker installed and running
- kubectl configured for target environment
- SLACK_WEBHOOK in .env file

---

[Command implementation here...]

Testing Commands

# 1. Register command
# Create the .md file in .claude/commands/

# 2. Verify registration
/help
# Should see your command listed

# 3. Test invocation
/your-command arg1 arg2

# 4. Check bash execution (if using !)
# Enable transcript mode: Ctrl-R
# Look for bash command output

# 5. Test with different arguments
/your-command different args

# 6. Validate tool restrictions (if using allowed-tools)
# Try operations outside allowed list
# Should ask permission or be blocked

Common Patterns

Code Review

---
description: Review code changes with security focus
allowed-tools: Read, Grep, Glob, Bash(git *)
---

Review changes: !`git diff $1`

Focus on:
1. Security vulnerabilities
2. Input validation
3. Authentication/authorization
4. Data sanitization
5. Error handling

Issue Handling

---
description: Create feature branch and link issue
argument-hint: <issue-number>
---

Issue #$1 details: !`gh issue view $1`

1. Create feature branch: `feature/$1`
2. Update issue with branch link
3. Provide implementation plan

Testing Workflow

---
description: Run tests and analyze failures
allowed-tools: Bash(bun test:*, npm test:*)
---

Test results: !`bun test`

Analyze any failures and suggest fixes.

Documentation Generation

---
description: Generate API docs from code
argument-hint: <file-or-directory>
---

Code to document: @$1

Generate comprehensive API documentation including:
- Function signatures with types
- Parameter descriptions
- Return value documentation
- Usage examples
- Edge cases and error handling

Troubleshooting

Command Not Found

• Verify file location: .claude/commands/your-command.md
• Check filename: no spaces, lowercase, .md extension
• Restart Claude Code if needed

Arguments Not Working

• Use $1, $2, not {1}, {2}
• Use $ARGUMENTS for all arguments
• Quote arguments if they contain spaces

Bash Commands Failing

• Use ! prefix before backticks: !\command``
• Verify command works in terminal first
• Check command output length (<15k chars)

File References Not Working

• Use @ prefix: @path/to/file.ts
• Verify file paths are relative to project root
• Combine with arguments: @$1

Tool Restrictions Not Applied

• Verify frontmatter syntax (YAML format)
• Check tool names match exactly: Read, not read
• Use wildcards for bash: Bash(git *)

Advanced Patterns

See REFERENCE.md for:

• SlashCommand tool configuration
• Complex argument parsing
• Multi-step command workflows
• Error handling patterns
• Integration with hooks

See EXAMPLES.md for:

• Real-world command implementations
• Team workflow examples
• Integration patterns
• Common use cases

Quick Reference

# Scaffold new command
./scripts/scaffold-command.sh my-command "Description here"

# Validate command
./scripts/validate-command.sh .claude/commands/my-command.md

# Test command
/my-command test args

Related Skills

• claude-hook-authoring: Add automation to commands with hooks
• claude-plugin-authoring: Bundle commands into distributable plugins
• claude-config-management: Configure command behavior globally