---

name: command-builder type: standard depth: base description: Creates and configures Claude Code slash commands with YAML frontmatter, argument handling, and tool permissions. Use when building new commands, adding $ARGUMENTS or $1-$N parameters, configuring allowed-tools, organizing command namespaces, or fixing command failures.

[H1][COMMAND-BUILDER]

Dictum: Reusable prompt templates reduce repetition and enforce consistency.

Load commands from .claude/commands/ (project) or ~/.claude/commands/ (user). Filename becomes command name.

Tasks:

1. Read index.md — Reference file listing for navigation
2. Read workflow.md — 5-phase creation process
3. Read variables.md — Argument capture, file references, skill loading
4. Read hints.md — Argument-hint syntax, enum patterns
5. (prose) Load style-standards skill — Voice, formatting, constraints
6. Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE
7. Validate — Quality gate; see §VALIDATION

[REFERENCE]: index.md — Complete reference file listing

---

[1][FRONTMATTER]

Dictum: Declarative constraints gate command execution.

---
description: Brief description shown in /help menu
argument-hint: [required-arg] [optional-arg?]
allowed-tools: Read, Write, Edit, Glob, Grep, Task, Bash, TodoWrite
model: opus
---

[INDEX]	[FIELD]	[TYPE]	[PURPOSE]	[SYNTAX]
[1]	description	string	/help menu text	Verb-first. <80 chars. Outcome-focused.
[2]	argument-hint	string	Autocomplete guidance	[required] [optional?] [--flag].
[3]	allowed-tools	list	Scoped tool permissions	Comma-separated tool names.
[4]	model	string	Override default model	Full model ID or alias.

[IMPORTANT]:

• [ALWAYS] Use --- delimiters (three dashes, no spaces).
• [ALWAYS] Quote strings containing :, #, [, ], {, }.
• [NEVER] Use tabs; YAML requires spaces.

[CRITICAL]:

• [ALWAYS] Declare Read for every @path reference.
• [ALWAYS] Declare Bash for every !command reference.
• [NEVER] Omit required tools—command fails without output.

---

[2][MODELS]

Dictum: Model selection balances capability against cost and latency.

[CRITICAL] Session inherits default model. Override for specific capability requirements.

[INDEX]	[MODEL_ID]	[ALIAS]	[STRENGTH]	[LATENCY]	[COST]
[1]	claude-opus-4-5-20251101	opus	Complex reasoning	High	High
[2]	claude-sonnet-4-5-20250929	sonnet	Balanced performance	Medium	Medium
[3]	claude-3-5-haiku-20241022	haiku	Fast, simple tasks	Low	Low

[INDEX]	[CHARACTERISTIC]	[OPUS]	[SONNET]	[HAIKU]
[1]	Multi-file scope	X
[2]	Architectural impact	X
[3]	Standard development		X
[4]	Speed priority			X
[5]	Deep analysis	X	X

---

[3][VARIABLES]

Dictum: Dynamic substitution enables reusable commands.

[INDEX]	[SYNTAX]	[CAPTURES]	[REQUIRED_TOOL]	[USE_WHEN]
[1]	$ARGUMENTS	All args as string	None	Free-form input
[2]	$1, $2...	Positional parameters	None	Structured multi-arg
[3]	${1:-val}	Default if missing	None	Optional parameters
[4]	@path	Include file contents	Read	File analysis
[5]	!command	Shell execution	Bash	Dynamic context

[CRITICAL]:

• [NEVER] Mix $ARGUMENTS and $1-$N in same command.
• [ALWAYS] Declare required tools for @path and !command.

→references/variables.md: Complete reference—examples, skill loading, anti-patterns.

---

[4][PATTERNS]

Dictum: Canonical patterns accelerate development.

[4.1][FILE_ANALYSIS]

---
description: Analyze file for issues
argument-hint: [file-path]
allowed-tools: Read
---
## Target
@$1
## Task
Identify security, performance, and code quality issues.

---

[4.2][MULTI_FILE_OPERATION]

---
description: Process files matching pattern
argument-hint: [glob-pattern]
allowed-tools: Read, Edit, Glob, TodoWrite
---
## Task
Match files via $1. Analyze content. Apply fixes. Track progress via TodoWrite.

---

[4.3][AGENT_WORKFLOW]

---
description: Multi-agent analysis
argument-hint: [target-folder]
allowed-tools: Task, Read, Glob, TodoWrite
---
## Task
1. Match files in $1 via Glob
2. Spawn analysis agents via Task
3. Synthesize findings, track via TodoWrite

---

[4.4][SKILL_CONTEXT]

---
description: Validate target against skill standards
argument-hint: [target] [focus?]
allowed-tools: Read, Task, Glob, Edit, TodoWrite
---
## Skill Context
@.claude/skills/[skill-name]/SKILL.md
@.claude/skills/[skill-name]/references/[domain]/*.md
## Task
Load context above. Spawn Task agents. Verify findings against loaded context. Apply corrections.

→templates/command-template.md — canonical template.

---

[5][ORGANIZATION]

Dictum: Namespaces prevent command collision.

[INDEX]	[SCOPE]	[LOCATION]	[USE_CASE]
[1]	Personal	~/.claude/commands/	Individual workflows
[2]	Project	.claude/commands/	Shared team workflows

[INDEX]	[CONVENTION]	[PATTERN]	[EXAMPLE]
[1]	Verb-first	action-target	create-component
[2]	Lowercase	No capitals	review-pr
[3]	Hyphen-separated	No underscores	run-tests
[4]	Descriptive	Clear purpose	analyze-coverage

.claude/commands/
├── git/
│   ├── commit.md  -> /git:commit
│   └── pr.md      -> /git:pr
└── test/
    └── unit.md    -> /test:unit

---

[6][VALIDATION]

Dictum: Validation gates prevent incomplete artifacts.

[VERIFY] Completion:

• Workflow: All 5 phases executed (UNDERSTAND → VALIDATE).
• Frontmatter: Valid YAML, description present, tools declared.
• Variables: No $ARGUMENTS + $1-$N mixing.
• Tools: All @path have Read, all !command have Bash.
• Quality: LOC < 125, verb-first naming.

[REFERENCE] Operational checklist: →validation.md