building-commands

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

---
description: Brief description of what the command does
---

Recommended Fields

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

All Available Fields

---
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):

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

---
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):

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:

---
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):
2. haiku, sonnet, opus - Only work in agents

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

1. Full IDs with Dates (✅ STABLE for commands):
2. claude-haiku-4-5-20251001 - Locked to specific snapshot
3. claude-sonnet-4-5-20250929 - Locked to specific snapshot
4. 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 for current versions.

Disable Model Invocation

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

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

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

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:

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 vers