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

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

user

local

Execution: 8. Session mode — Will this run as a subagent (delegated by Claude) or as the main session agent (

claude --agent <name>

initialPrompt

isolation: worktree

high

max

low

If

$ARGUMENTS

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

ag

-start

my_agent

Step 2 — Write frontmatter

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/agent-frontmatter.md

Required:

name

description

model: inherit

color

Intensional rule for

tools

["Read", "Grep", "Glob"]

Write

Bash

Agent(type1, type2)

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

>

• "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

---

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

If

memory

Keep under 3,000 words. Detailed domain reference belongs in

references/

skills:

See

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/examples/proactive-code-reviewer.md

Step 5 — Script opportunity scan

Read

${CLAUDE_PLUGIN_ROOT}/skills/create-agent/references/script-patterns.md

scripts/

--help

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:

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

field

message

severity

critical

major

Phase 2: Deliver

Output Paths

~/.claude/agents/<name>.md

.claude/agents/<name>.md

<plugin-root>/agents/<name>.md

Agents in

agents/

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

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

• memory

  set if cross-session learning identified, with maintenance instructions in body

• effort

  set if non-default thinking depth needed

• initialPrompt

  set if session-mode agent that self-starts

• background: true

  set if concurrent execution identified

• isolation: worktree

  set if agent modifies files that need review before merging
• No TODO placeholders remaining

Error Handling