Agent Creator

Generate well-structured Claude Code agents — markdown files with YAML frontmatter that delegate complex multi-step work to autonomous subprocesses with isolated context windows.

Agents vs Skills — know the difference before generating:

Agents run in isolated context, have second-person system prompts ("You are..."), use <example> XML blocks in descriptions, and are spawned via the Task tool
Skills inject inline into the current conversation, use imperative body instructions for Claude to follow, and route via description matching on trigger phrases

Phase 0: Understand Requirements

Parse $ARGUMENTS for hints. Gather:

Domain & purpose — What problem does this agent solve?
Expert persona — What specialist identity should it embody?
Trigger conditions — When should Claude delegate to this agent? What user messages activate it?
Proactive vs reactive — Should it fire automatically after events (e.g., after code is written), or only on explicit request?
Tool access — What tools are actually needed? Least-privilege: an analysis agent doesn't need Write.
Context isolation — Does it generate heavy output? Should it run in a worktree (isolation: worktree)?

If $ARGUMENTS is empty or insufficient, use AskUserQuestion to gather domain, trigger conditions, and proactive intent before proceeding. Proceed to Phase 1 once these are established.

Phase 1: Generate

Apply throughout: second-person for system prompt body, intensional over extensional reasoning, minimum viable frontmatter.

Step 1 — Choose identifier

Naming rules (enforced by validate_agent.py):

3–50 characters, lowercase letters/numbers/hyphens only
Must start and end with alphanumeric
Avoid generic terms: helper, assistant, agent

Good: code-reviewer, test-generator, api-docs-writer Bad: ag (too short), -start (leading hyphen), my_agent (underscore)

Step 2 — Write frontmatter

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md for the full field catalog, color semantics, model options, tool selection framework, and execution modifiers.

Required: name, description Always set: model: inherit (unless specific model capability needed), color (visual ID in UI)

Intensional rule for tools: Restrict to the minimum needed because agents run autonomously — over-permission has no human in the loop to catch it. ["Read", "Grep", "Glob"] for analysis. Add Write for generation. Add Bash only when shell execution is essential, never by default.

Step 3 — Write description with `<example>` blocks

Agent descriptions use a unique two-part format: a trigger statement + XML example blocks. The routing model uses this structure to decide when to spawn the agent.

Format:

Use this agent when [trigger conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How Claude responds before delegating to agent]"
<commentary>
[Why this agent should trigger here]
</commentary>
</example>

Intensional rules for the description field:

2–4 <example> blocks — single-example descriptions miss synonym trigger coverage
Cover different phrasings of the same intent — routing matches on token patterns across examples
Include proactive examples when the agent should fire after events, not just on explicit request
<commentary> must explain routing reasoning, not just restate the user message
Specify when NOT to use if ambiguity with other agents exists — prevents mis-routing

For proactive agents, the description needs a two-turn assistant pattern showing an event followed by delegation. See references/agent-frontmatter.md for the exact format.

Step 4 — Write system prompt

The markdown body (after ---) becomes the agent's system prompt. Write entirely in second person, addressing the agent directly. This is the critical authoring difference from skills: agents need a persona and process, not instructions for Claude to follow.

Standard structure:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]

**Process:**
1. [Step — imperative]
2. [Next step]

**Quality Standards:**
- [Standard]

**Output Format:**
[Structure and content of what to return]

**Edge Cases:**
- [Situation]: [How to handle]

Intensional rules for the system prompt:

Persona first — the expert identity shapes all downstream decisions; establish it in the first sentence
Process steps prevent "winging it" on complex tasks; each step is an explicit decision boundary
Output format is non-negotiable — callers need predictable structure to consume results
Define edge cases in the system prompt; discovered-at-runtime errors cost retries

Keep under 3,000 words. Detailed domain reference belongs in references/ preloaded via the skills: frontmatter field, not embedded directly in the system prompt.

See ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md for a complete working example demonstrating the proactive trigger pattern.

Step 5 — Script opportunity scan

Read ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md and apply the five signal patterns to every step in the agent's system prompt:

Signal	Question	If yes →
Repeated Generation	Does any step produce the same structure across invocations?	Parameterized script in `scripts/`
Unclear Tool Choice	Does any step combine tools in a fragile sequence?	Script the procedure
Rigid Contract	Can you write `--help` text for this step right now?	CLI candidate
Dual-Use Potential	Would a user run this step from the terminal independently?	Design as proper CLI
Consistency Critical	Must this step produce identical output for identical inputs?	Script — never LLM generation

Step 6 — Check delegation

Scan existing agents and skills before finalizing:

Glob: .claude/agents/*.md, ~/.claude/agents/*.md (project + global agents)
Glob: .claude/skills/*/SKILL.md, ~/.claude/skills/*/SKILL.md (project + global skills)

Does an existing agent cover this domain? Extend it, or tighten scope of the new one
Are there skills or reference files to preload via skills: frontmatter for domain knowledge?
Are there commands or MCPs this agent should delegate sub-tasks to?

Always use fully qualified names:

Task: subagent_type=plugin-dev:agent-creator (not just "agent-creator")
Skill: claude-skills:create-skill (not just "create-skill")

Step 7 — Validate

When creating a new agent file:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/validate_agent.py <agent-file> --output json

Exit 0 = proceed to Phase 2. Exit 1 = parse the errors array; each entry has field, message, severity. Resolve all critical and major items before writing to disk.

Phase 2: Deliver

Output Paths

Scope	Location
User agent (global)	`~/.claude/agents/<name>.md`
Project agent	`.claude/agents/<name>.md`
Plugin agent	`<plugin-root>/agents/<name>.md`

Agents in agents/ are auto-discovered — no registration needed. Plugin agents are namespaced automatically as plugin-name:agent-name.

Initialize agent file (optional scaffold)

When creating from scratch:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/create-agent/scripts/init_agent.py <name> --path <agents-dir>

Exit 0 = file created with placeholders, proceed to fill content. Exit 1 = naming collision; ask user to rename or confirm overwrite.

Explain Your Choices

Present the generated agent with brief rationale:

What you set and why — "Set model: sonnet because this agent performs complex multi-file reasoning"
What you excluded and why — "Left isolation unset; no git state management needed"
Tools selected and why — explicitly justify each tool; undefended tool access is a design smell

Write and Confirm

Before writing:

Writing to: [path]
This will [create new / overwrite existing] file.
Proceed?

After Creation

Summarize:

Name and file path
When it triggers (key trigger conditions)
Tools granted and why
Suggested test scenario

Proceed to Phase 3.

Phase 3: Evaluate

Dimension	Criteria
Clarity (0-10)	System prompt unambiguous, objective and persona clear
Trigger Precision (0-10)	Description + examples cover intended trigger space, not broader
Efficiency (0-10)	System prompt token economy — maximum guidance per token
Completeness (0-10)	Covers domain requirements; output format defined; edge cases addressed
Safety (0-10)	Tools restricted to minimum needed; no runaway permission grants

Target: 9.0/10.0. If below, refine once addressing the weakest dimension, then deliver.

Phase 3 is complete when score ≥ 9.0 or one refinement pass has run. Deliver: agent file path, key trigger conditions, tools granted and why.

Validation Checklist

Structure:

File is <name>.md in an agents/ directory
Valid YAML frontmatter with name and description
Markdown body is present and substantial

Description Quality:

Starts with "Use this agent when..."
Contains 2–4 <example> blocks
Each example has Context, user, assistant, and <commentary>
Covers different trigger phrasings (synonym coverage)
Proactive example included if agent should fire after events

System Prompt Quality:

Written in second person ("You are...", "You will...")
Has clear persona/role statement as first sentence
Process steps are numbered and imperative
Output format is defined
Edge cases addressed
Under 3,000 words; domain detail offloaded to references/

Frontmatter:

model: inherit unless specific model needed
color set and semantically meaningful
tools restricted to minimum needed
No TODO placeholders remaining

Error Handling

Issue	Action
Unclear domain	Ask: what does success look like for this agent?
Scope too broad	Split into 2–3 focused agents with non-overlapping trigger conditions
Conflicts with existing agent	Note overlap; narrow triggering scope or extend the existing one
Vague trigger conditions	Ask for 3 concrete user messages that should activate this agent

create-agent