/create-agent

name: create-agent
description: >
  This skill should be used when the user asks to "create an agent", "make an agent",
  "write an agent", "build a subagent", "add an agent to a plugin", "design an autonomous agent",
  "generate an agent file", "write a system prompt for an agent", "what frontmatter does an agent need",
  "create a specialized agent". Not for skills or commands — use create-skill.
argument-hint: "[name] - or leave empty to interview"

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 Agent 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:

**Identity:** 1. **Domain & purpose** — What problem does this agent solve? 2. **Expert persona** — What specialist identity should it embody?

**Triggering:** 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?

**Capabilities:** 5. **Tool access** — What tools are actually needed? Least-privilege: an analysis agent doesn't need Write. 6. **Memory** — Should this agent learn across sessions? (e.g., accumulate codebase patterns, recurring issues, architectural decisions.) If yes, choose scope: `project` (recommended default, shareable via VCS), `user` (global across projects), or `local` (project-specific, not in VCS). 7. **MCP servers** — Does it need external tools (browser, database, API) not in the parent session?

**Execution:** 8. **Session mode** — Will this run as a subagent (delegated by Claude) or as the main session agent (`claude --agent <name>`)? Session agents need broader tool access, more self-contained prompts, and may use `initialPrompt` to self-start. 9. **Background execution** — Should it run concurrently while the user continues? Background agents auto-deny unpre-approved permissions and cannot ask clarifying questions. 10. **Context isolation** — Does it generate heavy output or modify files? Should it run in a worktree (`isolation: worktree`)? 11. **Effort level** — Does it need deep reasoning (`high`/`max`) or is it a fast classification task (`low`)?

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. For session-mode agents that orchestrate subagents, use `Agent(type1, type2)` to scope spawning.

**Set if applicable from Phase 0:**

• `memory` — if cross-session learning was identified; add memory maintenance instructions to body
• `effort` — if the task warrants non-default thinking depth
• `initialPrompt` — if this is a session agent that should self-start
• `background: true` — if concurrent execution was identified
• `mcpServers` — if external tools were identified

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 — calle