creating-commands

name	creating-commands
description	Creates new Claude Code slash commands following best practices. Guides through command structure, naming, arguments, and frontmatter. Use when user wants to create a command, build a slash command, or asks about command best practices.

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
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	No arguments, simple prompt
With Args	templates/with-args.md	Single or multiple arguments
Workflow	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 for detailed best practices and anti-patterns.