[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
- Match files in $1 via Glob
- Spawn analysis agents via Task
- 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