create-agent

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 concise > folded scalar descriptions (50-70 tokens, no <example> blocks), 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:

1. Domain & purpose — What problem does this agent solve?
2. Expert persona — What specialist identity should it embody?
3. Trigger conditions — When should Claude delegate to this agent? What user messages activate it?
4. Proactive vs reactive — Should it fire automatically after events (e.g., after code is written), or only on explicit request?
5. Tool access — What tools are actually needed? Least-privilege: an analysis agent doesn't need Write.
6. 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

The description field is loaded into context every session. Token budget matters — write the minimum needed for accurate routing.

Use a > folded scalar with:

• "Use this agent when [trigger conditions]."
• Proactive hint if applicable ("Recommended PROACTIVELY after...")
• Scope boundary ("Not for X — use Y-agent.")
• Target: 50-70 tokens. No <example> blocks — they waste context without improving routing.

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..."
• Concise > scalar, 50-70 tokens, no <example> blocks
• Covers scope boundaries (what it's NOT for)
• Proactive hint 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