claude-command-authoring

# 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

```bash
# 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

```markdown
---
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

```markdown
---
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

```markdown
---
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`)

```markdown
Fix issues: $ARGUMENTS
```

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

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

```markdown
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

```markdown
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:

```markdown
---
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:

```markdown
---
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:

```markdown
---
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

```markdown
---
# ❌ Too vague
description: Deploy stuff

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

### 2. Helpful Argument Hints

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

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

### 3. Context Before Instructions

```markdown
---
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

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

### 5. Document Complex Commands

```markdown
---
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

```bash
# 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

```markdown
---
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

```markdown
---
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

```markdown
---
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

```markdown
---
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](REFERENCE.md) for:
- SlashCommand tool configuration
- Complex argument parsing
- Multi-step command workflows
- Error handling patterns
- Integration with hooks

See [EXAMPLES.md](EXAMPLES.md) for:
- Real-world command implementations
- Team workflow examples
- Integration patterns
- Common use cases

## Quick Reference

```bash
# 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