Writing Commands

Overview

Commands are user-invokable shortcuts that trigger specific workflows. Good commands have clear triggers, delegate to skills, and provide feedback.

When to Create

Create a command when:

• User performs same multi-step workflow repeatedly
• Complex process benefits from simple invocation
• Workflow requires specific skill sequence
• Consistent output format is needed

Don't create for:

• One-off tasks
• Simple actions (use skills directly)
• Workflows that vary significantly each time

Structure Template

---
name: /command-name
description: [What this command does - shown in help]
allowed_tools: [List of tools command can use]
---

# /command-name

## Purpose
[What problem this command solves]

## Skills to Invoke
[Ordered list of skills to load]

## User Prompts
[Questions to ask user if needed]

## Execution Steps
1. [Step 1]
2. [Step 2]
...

## Success Criteria
[How to know command completed successfully]

## Output Format
[Structure of command response]

Quality Checklist

• Name starts with / and is memorable
• Description fits in one line
• Skills to invoke explicitly ordered
• User prompts defined for required input
• Execution steps are clear and sequential
• Success criteria are measurable
• Output format is consistent
• allowed_tools limits scope appropriately

Testing Requirements

1. Invocation test - Command triggers correctly
2. Skill loading test - Required skills load in order
3. User prompt test - Questions asked when needed
4. Execution test - Steps complete as expected
5. Output test - Response matches format
6. Error handling test - Graceful failure on issues

Examples

Good Command:

---
name: /new-feature
description: Start a new feature with session, tests, and implementation
allowed_tools: [Read, Write, Edit, Bash, Skill, Task]
---

## Purpose
Initialize complete feature development workflow with TDD.

## Skills to Invoke
1. session (create session file)
2. test-driven-development (setup test structure)
3. git-expert (create feature branch)

## User Prompts
- "What is the feature name?"
- "Brief description of the feature?"

## Execution Steps
1. Create feature branch: feature/{name}
2. Initialize session file
3. Create test file with first failing test
4. Report setup complete

## Success Criteria
- Branch created
- Session file exists
- Test file with failing test exists

## Output Format
Feature '{name}' initialized:
- Branch: feature/{name}
- Session: .claude/tasks/session-{name}.md
- Test: tests/{name}.test.ts (RED)

Bad Command:

---
name: /do-stuff
---

Does various things.

(No purpose, no steps, no criteria)

Common Mistakes

Mistake	Fix
Vague name	Use descriptive /verb-noun format
No skill delegation	List skills to invoke in order
Missing user prompts	Define what input is needed
No success criteria	Add measurable completion check
Uncontrolled scope	Use allowed_tools to limit actions
No output format	Define consistent response structure