command-builder
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.
When & Why to Use This Skill
The Command Builder skill streamlines the creation and configuration of Claude Code slash commands. It enables developers to build reusable, structured prompt templates using YAML frontmatter, advanced argument handling, and granular tool permissions, ensuring consistency and efficiency across agentic workflows.
Use Cases
- Case 1: Creating custom slash commands with positional parameters ($1, $2) and default values to automate repetitive code analysis tasks.
- Case 2: Configuring scoped tool permissions (e.g., Read, Bash, Edit) for specific commands to ensure secure and predictable agent execution.
- Case 3: Organizing project-level command namespaces (e.g., /git:commit, /test:unit) to standardize development workflows across a team.
- Case 4: Migrating manual prompts into declarative YAML-based commands to optimize model selection and improve CLI autocomplete guidance.
| 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-standardsskill — 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
Readfor every@pathreference. - [ALWAYS] Declare
Bashfor every!commandreference. - [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
$ARGUMENTSand$1-$Nin same command. - [ALWAYS] Declare required tools for
@pathand!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-$Nmixing. - Tools: All
@pathhaveRead, all!commandhaveBash. - Quality: LOC < 125, verb-first naming.
[REFERENCE] Operational checklist: →validation.md