creating-commands

Creating Commands

Guides creation of Claude Code slash commands using documented best practices.

Quick Start

For a new command:

1. Ask user for command purpose and arguments needed
2. Generate using appropriate template
3. Validate against checklist

For reviewing existing command:

1. Read command file
2. Check against anti-patterns in [reference.md](reference.md)
3. Report issues with fixes

Workflow: Create New Command

Progress:
- [ ] Gather requirements (purpose, arguments, scope)
- [ ] Choose template (basic, with-args, workflow)
- [ ] Generate command file
- [ ] Validate against checklist

Step 1: Gather Requirements

Ask user with AskUserQuestion:

• What should this command do? (purpose)
• Does it need arguments? (none, single, multiple)
• Project or personal? (scope)

Step 2: Choose Template

| Type | Template | When to Use | |------|----------|-------------| | Basic | [templates/basic.md](templates/basic.md) | No arguments, simple prompt | | With Args | [templates/with-args.md](templates/with-args.md) | Single or multiple arguments | | Workflow | [templates/workflow.md](templates/workflow.md) | Integrates with skills/agents |

Step 3: Generate Command

Create in appropriate location:

• .claude/commands/ - Project commands (git-tracked)
• ~/.claude/commands/ - Personal commands (your machine only)

Step 4: Validate

Run through checklist before finishing:

Validation Checklist:
- [ ] Name: lowercase with hyphens only
- [ ] Name: descriptive, verb-noun format preferred
- [ ] Description: explains what command does
- [ ] Arguments: documented with argument-hint if used
- [ ] Prompt: clear, actionable instructions
- [ ] Tools: allowed-tools declared if needed

Naming Rules

Format: verb-noun or action (lowercase, hyphens)

• fix-issue
• review-pr
• run-tests
• optimize

Constraints:

• Lowercase letters, numbers, hyphens only
• No spaces or underscores
• Keep concise (1-3 words)

Command File Format

---
description: Brief explanation shown in help
allowed-tools:
  - Bash(bash:*)
  - WebSearch
argument-hint: "param_name"
---

Your command prompt here.
Use $ARGUMENTS for all args or $1, $2 for positional.

Argument Syntax

| Syntax | Usage | Example | |--------|-------|---------| | $ARGUMENTS | All arguments as one string | /cmd foo bar → foo bar | | $1, $2 | Positional arguments | /cmd foo bar → $1=foo, $2=bar | | @file | Include file contents | Review @src/main.ts |

Frontmatter Options

| Field | Purpose | Required | |-------|---------|----------| | description | Shown in help, enables auto-invoke | Recommended | | allowed-tools | Tools the command can use | If using tools | | argument-hint | Documents expected args | If has args | | model | Specific model to use | Optional |

Example: Basic Command

---
description: Run all tests and report failures
allowed-tools:
  - Bash(npm:*)
---

Run the test suite and summarize results:

1. Execute `npm test`
2. If failures, show failing tests with context
3. Suggest fixes for common issues

See [reference.md](reference.md) for detailed best practices and anti-patterns.