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.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026

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.
namecommand-builder
typestandard
depthbase
descriptionCreates 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