creating-commands

Creating Commands

Overview

Writing commands IS Test-Driven Development applied to workflow automation.

You write test cases (invocation scenarios), watch them fail (baseline behavior), write the command (markdown file), watch tests pass (correct execution), and refactor (improve argument handling and skill references).

Core principle: Commands are the interface, skills are the methodology. Commands should be thin wrappers that invoke skills for complex guidance.

Official guidance: For Anthropic's official command specification, see anthropic-command-docs.md

REQUIRED (standard/critical artifacts): See testing-commands-with-subagents.md for the complete testing methodology

What is a Command?

A command is a manually-invoked shortcut to a stored prompt or workflow. Commands start with / and provide quick access to repetitive tasks.

Commands are: Manual triggers, workflow shortcuts, parameterized prompts

Commands are NOT: Auto-discovered (use skills), specialized workers (use agents), project conventions (use CLAUDE.md)

Commands vs Skills vs Agents

Aspect	Command	Skill	Agent
Invocation	Manual (/command)	Manual or auto	Auto or manual
Purpose	Quick workflow trigger	Reference guide/methodology	Specialized worker
Has identity	No	No	Yes ("You are...")
Tool restrictions	Yes (frontmatter)	No	Yes
Model override	Yes	No	Yes
Arguments	Yes ($ARGUMENTS)	No	Via prompt
Best for	Daily workflows	Detailed methodology	Task isolation

The Command-Skill Pattern

Commands reference skills for methodology:

# .claude/commands/commit.md

---
description: Create a git commit following conventions
---

Create a commit for the staged changes.

**REQUIRED:** Follow the methodology in the `git-workflow` skill.
```text

This keeps commands thin while leveraging detailed skill guidance.

## TDD Mapping for Commands

| TDD Concept             | Command Creation                                    |
|-------------------------|-----------------------------------------------------|
| **Test case**           | Invocation scenario with arguments                  |
| **Production code**     | Command file (.md)                                  |
| **Test fails (RED)**    | Command not found or wrong behavior                 |
| **Test passes (GREEN)** | Correct execution with expected output              |
| **Refactor**            | Close loopholes in argument handling and skill compliance |
| **Write test first**    | Run baseline scenario BEFORE writing command        |
| **Watch it fail**       | Verify command doesn't exist or behaves wrong       |
| **Minimal code**        | Write command addressing specific needs             |
| **Watch it pass**       | Verify invocation produces correct result           |
| **Refactor cycle**      | Find new failure modes → fix → re-verify            |

## When to Create a Command

**Create when:**

- Task is invoked manually and repeatedly
- Task benefits from arguments/parameters
- Task is a workflow trigger (not detailed methodology)
- You want `/command` convenience

**Don't create for:**

- One-off tasks
- Auto-discovery scenarios (use skills)
- Detailed methodology documentation (use skills)
- Task isolation needs (use agents)

## Directory Structure

Commands can be placed at two levels:

```text

# Project level (recommended - version controlled)

.claude/commands/command-name.md
.claude/commands/category/command-name.md

# User level (personal commands across projects)

~/.claude/commands/command-name.md
```text

### Naming Conventions

```text

# Direct command

.claude/commands/commit.md          → /project:commit

# Categorized command

.claude/commands/git/commit.md      → /project:git:commit
.claude/commands/test/unit.md       → /project:test:unit

# User command

~/.claude/commands/standup.md       → /user:standup
```text

## Command File Structure

### Basic Command (No Frontmatter)

```markdown

# .claude/commands/review.md

Review the code in $ARGUMENTS for:

1. Code quality and readability
2. Security vulnerabilities
3. Performance issues

Provide specific, actionable feedback.
```text

Usage: `/project:review src/auth/login.ts`

### Command with Frontmatter

```markdown
---
allowed-tools: Read, Grep, Glob, Bash(git diff:*)
description: Comprehensive code review
model: claude-sonnet-4-5-20250929
argument-hint: [file-or-directory]
---

Review the code in $ARGUMENTS for quality, security, and performance.
```text

### Frontmatter Fields

| Field | Required | Description |
|-------|----------|-------------|
| `description` | No | Shown in `/help`, aids discoverability |
| `allowed-tools` | No | Restrict tools command can use |
| `model` | No | Override model for this command |
| `argument-hint` | No | Shows expected arguments in help |

## Dynamic Features

### $ARGUMENTS Placeholder

Captures everything after the command name:

```markdown
Fix the GitHub issue: $ARGUMENTS

1. Read the issue description
2. Understand the problem
3. Implement the fix
4. Write tests

```text

Usage: `/project:fix-issue 123` → "Fix the GitHub issue: 123"

**Best practice:** Structure command so it works even without arguments:

```markdown

# Good - works with or without arguments

Review the code $ARGUMENTS for quality issues.

If no specific files provided, review recently changed files:
!`git diff --name-only HEAD~1`
```text

### Positional Arguments ($1, $2, $3)

For commands with multiple parameters:

```markdown
---
argument-hint: [issue-number] [priority]
---

Fix issue #$1 with priority $2.

Priority levels:

- high: Fix immediately
- medium: Fix this sprint
- low: Add to backlog

```text

Usage: `/project:fix-issue 123 high`

### Bash Execution (!`command`)

Include live command output in the prompt:

```markdown

## Current Context

- Branch: !`git branch --show-current`
- Status: !`git status --short`
- Recent commits: !`git log --oneline -5`

## Task

Create a commit message for the staged changes.
```text

The bash commands execute when the command is invoked, injecting live output.

### File References (@path)

Include file contents:

```markdown
Review the following configuration:

- Package: @package.json
- TypeScript: @tsconfig.json
- ESLint: @.eslintrc.js

Check for inconsistencies and outdated settings.
```text

### Combining Features

```markdown
---
allowed-tools: Read, Grep, Glob, Edit, Bash(npm:*), Bash(git:*)
description: Add a new dependency with proper setup
argument-hint: [package-name]
---

## Context

- Current dependencies: @package.json
- Lock file exists: !`test -f package-lock.json && echo "yes" || echo "no"`

## Task

Add the package `$ARGUMENTS` to the project:

1. Install with npm
2. Update TypeScript config if needed
3. Add to .gitignore if it creates cache files
4. Create example usage in README

**REQUIRED:** Follow the `dependency-management` skill for version pinning conventions.
```text

## Referencing Skills

Commands should reference skills for detailed methodology:

### Pattern: Thin Command + Rich Skill

```markdown

# .claude/commands/test.md

---
description: Run tests with TDD methodology
argument-hint: [test-pattern]
---

Run tests matching: $ARGUMENTS

**REQUIRED:** Follow the `testing-conventions` skill for:

- Test file naming
- Fixture patterns
- Coverage requirements

```text

```markdown

# .claude/commands/commit.md

---
description: Create conventional commit
---

Create a commit for staged changes.

**REQUIRED METHODOLOGY:** Use the `git-workflow` skill for:

- Commit message format
- Scope conventions
- Breaking change notation

```text

### When to Reference vs Inline

**Reference a skill when:**

- Methodology is >20 lines
- Methodology is reused across commands
- Methodology needs its own testing/maintenance

**Inline when:**

- Instructions are <10 lines
- Instructions are command-specific
- No reuse anticipated

## Tool Restrictions

### Read-Only Command

```markdown
---
allowed-tools: Read, Grep, Glob, LS
description: Explore codebase without modifications
---
```text

### Git-Only Command

```markdown
---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*), Bash(git diff:*)
description: Git operations only
---
```text

### Full Access (Default)

Omit `allowed-tools` to inherit all tools.

## Model Selection

```markdown
---
model: claude-sonnet-4-5-20250929
---
```text

| Model | Use When |
|-------|----------|
| `haiku` | Fast, simple commands (file listing, quick checks) |
| `sonnet` | Balanced (most commands) |
| `opus` | Complex reasoning (architecture, planning) |

## The Iron Law (Same as TDD)

```text
NO COMMAND WITHOUT A FAILING TEST FIRST
```text

This applies to NEW commands AND EDITS to existing commands.

Write command before testing? Delete it. Start over.
Edit command without testing? Same violation.

**No exceptions:**

- Not for "simple commands"
- Not for "just changing the description"
- Not for "minor argument updates"
- Don't keep untested changes as "reference"
- Don't "adapt" while running tests
- Delete means delete

**Test scenarios:**

- With arguments
- Without arguments
- With wrong arguments
- Edge cases

## Testing Commands

**Note:** Commands don't need pressure testing like discipline-enforcing skills. Commands are workflow triggers, not rules to follow under stress. Focus testing on:

- **Invocation**: Does `/project:command` execute?
- **Arguments**: Does `$ARGUMENTS` handle all cases (present, missing, multiple)?
- **Skill loading**: Does the referenced skill get used?

### Invocation Testing

Does the command execute correctly?

```markdown
Test: /project:commit
Expected: Creates commit with conventional message
Actual: [Run and observe]
```text

### Argument Testing

Do arguments work correctly?

```markdown
Test: /project:fix-issue 123
Expected: $ARGUMENTS = "123"

Test: /project:fix-issue 123 high
Expected: $1 = "123", $2 = "high"

Test: /project:fix-issue
Expected: Command handles missing argument gracefully
```text

### Skill Reference Testing

Does the command use referenced skills?

```markdown
Test: /project:commit (with git-workflow skill available)
Expected: Follows commit conventions from skill
Verify: Commit message format matches skill specification
```text

## Common Rationalizations for Skipping Testing

| Excuse | Reality |
|--------|---------|
| "Command is simple" | Simple commands still need argument testing |
| "It's just a prompt" | Prompts can have edge cases |
| "I'll test when problems emerge" | Problems = broken workflows. Test first. |
| "Skill handles the complexity" | Still need to verify skill is loaded |
| "Too tedious to test" | Testing is less tedious than debugging broken workflows in production. |
| "I'm confident it's good" | Overconfidence guarantees argument edge cases. Test anyway. |
| "No time to test" | Deploying untested command wastes more time fixing it later. |
| "I copied from a working command" | Your changes may break it. Test anyway. |

## Command Categories

### Workflow Commands

Multi-step processes triggered manually:

```markdown

# .claude/commands/workflows/feature.md

---
description: Complete feature development workflow
argument-hint: [feature-description]
---

Implement feature: $ARGUMENTS

1. Create feature branch
2. Write tests first (TDD)
3. Implement feature
4. Run all tests
5. Create PR

**REQUIRED:** Follow `tdd` skill for test-first methodology.
```text

### Tool Commands

Single-purpose utilities:

```markdown

# .claude/commands/tools/deps-check.md

---
allowed-tools: Bash(npm:*), Read
description: Check for outdated dependencies
---

Check for outdated dependencies:
!`npm outdated`

Summarize which packages need updates and their breaking change risk.
```text

### Context Commands

Commands that provide context:

```markdown

# .claude/commands/context/standup.md

---
description: Generate standup summary
---

## Yesterday's Work

!`git log --oneline --since="yesterday" --author="$(git config user.email)"`

## Changed Files

!`git diff --stat HEAD~5`

Summarize this as a standup update.
```text

## Common Mistakes

| Mistake | Symptom | Fix |
|---------|---------|-----|
| Fat command | >50 lines of methodology | Move to skill, reference from command |
| No argument handling | Breaks without args | Add fallback with !`git diff` or default |
| Hardcoded paths | Not reusable across projects | Use $ARGUMENTS |
| Missing description | Doesn't appear in `/help` | Add frontmatter with description |
| No skill reference | Duplicates methodology | Reference skill for detailed guidance |

## Anti-Patterns

### ❌ Fat Command (Should Be Skill)

```markdown

# BAD: 200 lines of methodology in a command

---
description: Code review
---

## Code Review Methodology

### Step 1: Understand Context

[50 lines of detailed guidance...]

### Step 2: Security Analysis

[50 lines of detailed guidance...]
```text

**Fix:** Move methodology to skill, reference from command.

### ❌ No Argument Handling

```markdown

# BAD: Breaks without argument

Review $ARGUMENTS for issues.
```text

**Fix:** Handle missing arguments gracefully:

```markdown

# GOOD

Review $ARGUMENTS for issues.

If no files specified, review staged changes:
!`git diff --cached --name-only`
```text

### ❌ Hardcoded Values

```markdown

# BAD: Hardcoded paths

Review /src/components/ for issues.
```text

**Fix:** Use arguments:

```markdown

# GOOD

Review $ARGUMENTS for issues.
Default: src/
```text

### ❌ Missing Description

```markdown

# BAD: No frontmatter

Do something with code.
```text

**Fix:** Add description for `/help` discoverability:

```markdown
---
description: Review code for quality issues
argument-hint: [file-or-directory]
---
```text

## Command Creation Checklist

**RED Phase - Write Failing Test:**

- [ ] Verify command doesn't already exist
- [ ] Document expected invocation patterns and argument handling
- [ ] Try invoking the command — confirm it fails or behaves wrong (baseline)
- [ ] Document the gap between current and expected behavior

**GREEN Phase - Write Minimal Command:**

- [ ] Create file in correct location (.claude/commands/)
- [ ] Add description in frontmatter
- [ ] Add argument-hint if command takes arguments
- [ ] Handle $ARGUMENTS gracefully (with and without)
- [ ] Reference skills for detailed methodology
- [ ] Add tool restrictions if needed
- [ ] Add model override if needed
- [ ] Add bash context (!`command`) if helpful
- [ ] Add file references (@path) if helpful
- [ ] Test invocation works
- [ ] Test arguments work

**REFACTOR Phase - Close Loopholes:**

- [ ] Verify arguments don't break with unexpected input
- [ ] Verify referenced skills are actually followed
- [ ] Verify tool restrictions prevent unintended actions
- [ ] Test edge cases (missing args, wrong args, extra args)
- [ ] Re-test until command behaves correctly in all scenarios

**Quality Checks:**

- [ ] Command is thin (methodology in skills)
- [ ] Description is clear and discoverable
- [ ] Arguments are documented (argument-hint)
- [ ] Missing arguments handled gracefully
- [ ] Skill references are correct

**Deployment:**

- [ ] Place in .claude/commands/ for project scope
- [ ] Commit to version control
- [ ] Verify appears in `/help`

## Organization Best Practices

### Recommended Structure

```text
.claude/commands/
├── workflows/           # Multi-step processes
│   ├── feature.md
│   ├── release.md
│   └── hotfix.md
├── tools/               # Single-purpose utilities
│   ├── deps-check.md
│   ├── lint-fix.md
│   └── type-check.md
├── git/                 # Git operations
│   ├── commit.md
│   ├── pr.md
│   └── rebase.md
├── test/                # Testing commands
│   ├── unit.md
│   ├── integration.md
│   └── coverage.md
└── help.md              # List all commands
```text

### Help Command

Create a master help command:

```markdown

# .claude/commands/help.md

---
description: List all available project commands
---

## Available Commands

### Workflows

- `/project:workflows:feature [description]` - Full feature development
- `/project:workflows:release [version]` - Release workflow
- `/project:workflows:hotfix [issue]` - Hotfix workflow

### Tools

- `/project:tools:deps-check` - Check outdated dependencies
- `/project:tools:lint-fix` - Auto-fix lint issues

### Git

- `/project:git:commit` - Create conventional commit
- `/project:git:pr [title]` - Create pull request

### Testing

- `/project:test:unit [pattern]` - Run unit tests
- `/project:test:coverage` - Generate coverage report

For detailed help on any command, read its file in `.claude/commands/`.
```text

## Full Command Template

```markdown
---
allowed-tools: [Tool1, Tool2, Bash(command:*)]
description: [What this command does - shown in /help]
model: [haiku|sonnet|opus]
argument-hint: [arg1] [arg2]
---

## Context

[Optional: Live context from bash or file references]

- Current branch: !`git branch --show-current`
- Config: @config/settings.json

## Task

[Main instruction using $ARGUMENTS or $1, $2]

Do something with: $ARGUMENTS

[Optional: Handle missing arguments]
If no arguments provided, use default: [default behavior]

## Methodology

**REQUIRED:** Follow the `[skill-name]` skill for:

- [Aspect 1 the skill covers]
- [Aspect 2 the skill covers]

## Output

[Optional: Expected output format]
```text

## Worked Example

For a complete walkthrough of argument handling TDD — including 4 test scenarios, 3 iterations from minimal to production command, and key lessons — see examples/ARGUMENT_HANDLING_TESTING.md

## The Bottom Line

**Commands are the interface, skills are the methodology.**

Keep commands thin - they trigger workflows and reference skills for detailed guidance. This separation gives you quick invocation (`/commit`) with rich methodology (from `git-workflow` skill).

Same TDD cycle applies: Write failing test (baseline) → Write minimal command → Close loopholes.
Same benefits: Better quality, correct invocation, bulletproof argument handling.

If you follow TDD for code, follow it for commands. It's the same discipline applied to workflow automation.