| name | command-creator |
| description | Create Claude Code commands with phase-based structure and agent delegation. Use when building /plugin:command slash commands for Claude Code plugins. |
| when_to_use | TRIGGER when: 'create a command', 'add a slash command', 'new /command for', building Claude Code plugin commands. DO NOT TRIGGER: creating skills, agents, or rules. |
| effort | high |
Create Claude Code commands — user-invocable workflows that orchestrate agents, interview users, and delegate complex work through structured phases.
Core Process
1. Classify Command Scope
Determine structure before drafting:
- How many phases? Simple commands (1-2 phases) vs orchestration commands (5+ phases).
- Does the command need subagents, or can it run entirely in the main context with Read/Glob/Grep/Bash? Default to main context; only add Agent delegation when the work must run in a fresh context or with a different model.
- Interactive (AskUserQuestion gates) or autonomous (runs end-to-end without prompts)?
- What approval gates are needed before destructive or irreversible actions?
2. Research Existing Commands
Use Glob + Read directly to find similar commands in the target project:
- Glob
**/commands/*.md, read 2-3 representative files
- Note phase structure, frontmatter fields, and whether they use subagents or direct tools
3. Dedup Audit
Read ${CLAUDE_SKILL_DIR}/../prompt-writer/references/cc-dedup-guide.md before drafting.
Key dedup rules for commands:
- Commands receive CLAUDE.md automatically — do not re-state its global directives.
- Do not repeat Intent Gate, Delegation Check, or barrier semantics — these load every message.
- Do not re-explain agent model routing rules already in global CLAUDE.md.
- Commands specify WHAT to do (which agents, which phases) not HOW CC should behave.
4. Draft Command
Follow phase-based structure from references/command-patterns.md. Each phase uses:
## Phase N: Name
**Goal**: One sentence — what this phase achieves.
**Actions**:
1. First action
2. Second action
3. Third action (with sub-steps if needed)
Rules:
- Phases must be sequential — later phases depend on earlier ones.
- Insert AskUserQuestion approval gates before destructive actions.
- Delegate heavy work to agents — commands orchestrate, agents execute.
- Reference
$ARGUMENTS for user-supplied input.
- Use
${CLAUDE_PLUGIN_ROOT} for paths to bundled templates.
5. Frontmatter
---
description: "Short, action-oriented. What does this command do? ≤250 chars."
argument-hint: "[expected-input]"
effort: low | medium | high
---
Notes:
- Do not declare
allowed-tools, disallowedTools, or model. CC ignores them at runtime for user-level plugin components; tool access flows from session permissions.
- Always include
AskUserQuestion and Agent if the command interviews users or delegates to agents.
effort signals expected token budget: low (single task, <5 phases), medium (multi-agent, 5-7 phases), high (full orchestration, 7+ phases).- Do not add
model to command frontmatter — commands inherit the session model. Only agents have model routing.
6. Review
Present draft. Verify before finalizing:
- Phases sequential? No phase assumes work from a later phase.
- Approval gates present before destructive or irreversible actions?
- Agent delegation clear? Each Agent call has TASK + EXPECTED OUTCOME + MUST DO + MUST NOT DO + CONTEXT.
- Error handling covers: missing input, agent failure, no changes found, user cancellation.
$ARGUMENTS referenced at the right phase (usually Phase 1)?- No ineffective frontmatter declared (
model, allowed-tools, disallowedTools)?
Agent Delegation Patterns
Parallel Foreground (wait for all)
All agents in a single message block — CC waits automatically:
Agent(subagent_type: "<your-search-agent>", prompt: "...")
Agent(subagent_type: "<your-analysis-agent>", prompt: "...")
Use when results are needed before proceeding. Do NOT advance to the next phase until all agents complete.
Background (genuinely independent work)
Agent(subagent_type: "<your-worker>", run_in_background: true, prompt: "...")
Agent(subagent_type: "<your-worker>", run_in_background: true, prompt: "...")
Use only when you have independent work to continue while agents run. Collect all completion notifications before the next phase.
Model Routing per Agent
Pass model: to override per agent — do not upgrade all agents to Opus:
| Task type | Model |
|---|
| Search, file reading, fast lookup | haiku |
| Standard execution, analysis | sonnet |
| Planning, architecture, deep review | opus |
Agent Prompt Template
Every agent delegation follows this structure:
TASK: [What the agent must accomplish — one clear sentence]
EXPECTED OUTCOME: [What the agent returns — file:line refs, verdict, structured output]
MUST DO:
- [Specific constraint 1]
- [Specific constraint 2]
MUST NOT DO:
- [What to exclude or avoid]
CONTEXT: [Relevant state — plan path, conventions, prior findings]
String Substitutions
Variables available in command bodies (replaced at load time by CC):
| Variable | Where | Description |
|---|
$ARGUMENTS | Commands | All arguments passed on invocation |
${CLAUDE_PLUGIN_ROOT} | Commands | Absolute path to the plugin's root directory |
${CLAUDE_SKILL_DIR} | Skills only | Absolute path to the skill's directory — NOT available in commands |
Use ${CLAUDE_PLUGIN_ROOT} to reference bundled templates:
Read template from `${CLAUDE_PLUGIN_ROOT}/references/my-template.md`
References
| Topic | File | When to read |
|---|
| Command templates | command-patterns.md | Before drafting — full phase template, AskUserQuestion patterns, pipeline profiles, agent spawning examples |
| Dedup guide | ${CLAUDE_SKILL_DIR}/../prompt-writer/references/cc-dedup-guide.md | Before drafting — what not to repeat from global CLAUDE.md and auto-loaded context |
| Frontmatter schemas | ${CLAUDE_SKILL_DIR}/../prompt-writer/references/frontmatter-schemas.md | During frontmatter validation — field schemas, invocation control, tool control semantics |
