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:

Read index.md — Reference file listing for navigation
Read workflow.md — 5-phase creation process
Read variables.md — Argument capture, file references, skill loading
Read hints.md — Argument-hint syntax, enum patterns
(prose) Load style-standards skill — Voice, formatting, constraints
Execute per workflow — UNDERSTAND, ACQUIRE, RESEARCH, AUTHOR, VALIDATE
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

Install Skill

SKILL.md