building-commands

What this skill does

# Building Commands Skill

You are an expert at creating Claude Code slash commands. Slash commands are user-triggered workflows that provide parameterized, action-oriented functionality.

## When to Create a Command vs Other Components

**Use a COMMAND when:**
- The user explicitly triggers a specific workflow
- You need parameterized inputs via arguments
- The action is discrete and well-defined
- Users need a simple way to invoke complex operations

**Use a SKILL instead when:**
- You want automatic, context-aware assistance
- The functionality should be "always on"

**Use an AGENT instead when:**
- You need dedicated context and isolation
- The task requires heavy computation

## Command Schema & Structure

### File Location
- **Project-level**: `.claude/commands/command-name.md`
- **User-level**: `~/.claude/commands/command-name.md`
- **Plugin-level**: `plugin-dir/commands/command-name.md`
- **Supports namespacing**: `.claude/commands/git/commit.md` → `/project:git:commit`

### File Format
Single Markdown file with YAML frontmatter and Markdown body.

### Required Fields
```yaml
---
description: Brief description of what the command does
---
```

### Recommended Fields
```yaml
---
description: Brief description of what the command does
allowed-tools: Read, Grep, Glob, Bash
argument-hint: [parameter-description]
---
```

### All Available Fields
```yaml
---
description: Brief description of command functionality            # Required
allowed-tools: Read, Write, Edit, Grep, Glob, Bash               # Optional: Pre-approved tools
argument-hint: [filename] [options]                               # Optional: Parameter guide for users
model: claude-3-5-haiku-20241022                                  # Optional: Specific model (see warning below)
disable-model-invocation: false                                   # Optional: Prevent auto-invocation
---
```

### ⚠️ CRITICAL: Model Field - Commands vs Agents

**Commands support VERSION ALIASES or FULL IDs** (but NOT short aliases):

```yaml
---
description: Fast operation
model: claude-haiku-4-5  # ✅ Recommended - version alias (auto-updates)
---
```

```yaml
---
description: Stable operation
model: claude-haiku-4-5-20251001  # ✅ Also valid - full ID (locked version)
---
```

**DO NOT use SHORT ALIASES** in commands (they cause API 404 errors):
```yaml
model: haiku   # ❌ WRONG - causes "model not found" error
model: sonnet  # ❌ WRONG - causes "model not found" error
model: opus    # ❌ WRONG - causes "model not found" error
```

**Best Practice**: Omit model field to inherit from conversation:
```yaml
---
description: Inherits conversation model automatically
# No model field - will use whatever model the conversation uses
---
```

**Model Format Options**:

1. **Short Aliases** (❌ DON'T WORK in commands):
   - `haiku`, `sonnet`, `opus` - Only work in agents

2. **Version Aliases** (✅ RECOMMENDED for commands):
   - `claude-haiku-4-5` - Auto-updates to latest snapshot
   - `claude-sonnet-4-5` - Auto-updates to latest snapshot
   - `claude-opus-4-1` - Auto-updates to latest snapshot

3. **Full IDs with Dates** (✅ STABLE for commands):
   - `claude-haiku-4-5-20251001` - Locked to specific snapshot
   - `claude-sonnet-4-5-20250929` - Locked to specific snapshot
   - `claude-opus-4-1-20250805` - Locked to specific snapshot

**Why the Difference?**
- **Agents**: Claude Code translates short aliases (`haiku` → `claude-haiku-4-5-20251001`)
- **Commands**: Passed directly to API (only recognizes `claude-*` format)
- **Result**: Short aliases work in agents, fail in commands

**When to Specify Model**:
- ✅ Performance-critical fast operations (use haiku for speed)
- ✅ Complex reasoning requiring specific capabilities (use opus)
- ✅ Stable behavior needed (use full ID with date)
- ❌ Most cases (inheritance is better - more flexible)

**Recommendation**:
- **General use**: Omit model field (inherit from conversation)
- **Need speed**: Use `claude-haiku-4-5` (version alias)
- **Need stability**: Use full ID with date

**Finding Current Model IDs**:
Check [Anthropic's model documentation](https://docs.anthropic.com/claude/docs/models-overview) for current versions.

### Disable Model Invocation

The `disable-model-invocation` field prevents Claude from autonomously triggering the command via the SlashCommand tool.

```yaml
---
description: Delete all test data from database
disable-model-invocation: true  # ✅ Prevents accidental invocation by Claude
allowed-tools: Bash
---
```

**When to Use**:
- ✅ Destructive operations (delete, drop, remove)
- ✅ Commands requiring explicit user confirmation
- ✅ Testing/debugging commands
- ✅ Manual-only workflows
- ❌ Normal automation-friendly commands

**Effect**: Command still appears in `/help` and can be manually invoked by users, but Claude won't suggest or execute it automatically.

### Naming Conventions
- **Lowercase letters, numbers, and hyphens only**
- **No underscores or special characters**
- **Action-oriented**: Use verbs (`review-pr`, `run-tests`, `deploy-app`)
- **Descriptive**: Name should indicate what the command does
- **Namespacing**: Use directories for organization (`git/commit`, `test/run`)

## Command Body Content

The Markdown body contains instructions for Claude to execute when the command is invoked.

### Command Variables

Commands support special variables for arguments:

- **`$1`, `$2`, `$3`, etc.**: Positional arguments
- **`$ARGUMENTS`**: All arguments as a single string

### Template Structure

```markdown
---
description: One-line description of what this command does
allowed-tools: Read, Grep, Bash
argument-hint: [arg1] [arg2]
---

# Command Name

[Brief description of the command's purpose]

## Arguments

- `$1`: Description of first argument
- `$2`: Description of second argument
- Or use `$ARGUMENTS` for all arguments

## Workflow

When this command is invoked:

1. **Step 1**: Action to perform
2. **Step 2**: Action to perform
3. **Step 3**: Action to perform

## Examples

### Example Usage: /command-name value1 value2
Expected behavior:
1. [What happens]
2. [What happens]
3. [Result]

## Important Notes

- Note about usage or constraints
- Note about required context or setup
```

## Creating a Command

### Step 1: Gather Requirements
Ask the user:
1. What action should the command perform?
2. What arguments does it need?
3. What tools are required?
4. Should it work with specific file types or contexts?

### Step 2: Design the Command
- Choose an action-oriented name (lowercase-hyphens)
- Write a clear description for the help system
- Define argument structure
- Select necessary tools
- Plan the workflow

### Step 3: Write the Command File
- Use proper YAML frontmatter
- Document arguments clearly
- Provide step-by-step workflow
- Include usage examples
- Add important notes

### Step 4: Validate the Command
- Check naming convention
- Verify YAML syntax
- Test argument handling
- Review tool permissions
- Ensure description is clear

### Step 5: Test the Command
- Place in `.claude/commands/` directory
- Invoke with arguments: `/command-name arg1 arg2`
- Verify behavior matches expectations
- Test edge cases
- Iterate based on results

## Validation Script

This skill includes a validation script:

### validate-command.py - Schema Validator

Python script for validating command files.

**Usage:**
```bash
python3 {baseDir}/scripts/validate-command.py <command-file.md>
```

**What It Checks:**
- Filename format (lowercase-hyphens)
- Required fields (description)
- Model field format (CRITICAL: must use version aliases, not short aliases)
- Tool names validity
- Argument handling documentation
- Security patterns

**Returns:**
- Exit code 0 if valid
- Exit code 1 with error messages if invalid

**Example:**
```bash
python3 validate-command.py .claude/commands/run-tests.md

✅ Command validation passed
   Name: run-tests
   Description: Runs test suite and reports results
   Allowed tools: Read, Grep, Bash
   Model: claude-haiku-4-5 (valid ver