Agent Creator

Quick reference

Scope guard

Agent Creator sizes the task before starting. One bounded unit = one deliverable, roughly 5 files, roughly 10 steps.

“Create six agents for my team” gets a split proposal — one agent per subtask. The same rule that agent-creator applies to itself is the one it writes into every agent it generates.

Guardrails in every generated agent

Two blocks land in the body of every agent Agent Creator writes. They are part of the output contract, not advice. One of them is also called Return Contract — a separate thing from Agent Creator’s own return contract described later on this page: this one is what a generated agent hands back, that one is what Agent Creator itself hands back.

For generic agents, Scope Fit is omitted for research, docs and review-only work; Return Contract remains required. Team profiles use the explicit teams-setup exception: shared return and scope rules live in team.md, with only six domain sections in each profile. Agent Creator applies its own Return Contract: paths and validation verdicts, without full bodies.

Delegation

Agent Creator completes bounded work itself and requests main-caller delegation for large independent Explore analysis or a final brewtools:text-optimizer pass. It does not nest or delegate its own verification. Claude Code supports nested delegation within its configured depth; Brewcode policy keeps spawns in the main conversation so the caller can integrate each result.

Ordinary subagents cannot use AskUserQuestion, even if it is listed in tools:. Conversation forks retain the parent tool pool; a skill’s context: fork creates an ordinary subagent and does not gain that exception. This delegated creator returns unresolved questions to its caller.

Optimization handoff

Agent Creator returns exact created or updated paths and validation evidence to the main caller. The main caller resolves and reads the installed Brewtools text-optimize skill and its guard and references, then executes its Medium workflow. These resources belong to Brewtools, not the Brewcode plugin root. The creator cannot spawn optimizers or verifiers, or invoke the explicit-only skill through the Skill tool.

For a user-started pass in the main conversation:

/brewtools:text-optimize Optimize .claude/agents/reviewer.md in Medium mode, preserving all meaning.

Replace the example path with the file Agent Creator returned. For its final handoff, the main caller applies these additional acceptance requirements from Agent Creator:

1. Before optimization edits, run Phase 0 snapshot and require exit 0 plus RUN_DIR. Clean targets are the default; existing explicit authorization to edit named dirty targets permits --allow-dirty, while unrelated changes remain preserved.
2. Inventory protected facts and assign one optimizer per file. Give it the full GOAL/ROLE/SCOPE/CONTEXT/CONSUMER/DONE brief, exact target and original paths, RUN_DIR, an authorized report path, and cross-file decisions (empty by default). Require an immediate owned-draft checkpoint after every atomic edit. Missing snapshot or RUN_DIR means stop before editing; the optimizer cannot create its own snapshot.
3. Run verify --no-restore, then ask a fresh independent read-only verifier to compare original and current files from disk without the writer’s report. Require 100% meaning preservation, including names, numbers, paths, examples, negations, and scope.
4. Repair owned losses, refresh checkpoints, repeat the gates and agent validation, or refuse acceptance while preserving concurrent bytes. Report optimization as requested or pending until the main caller returns gate evidence.

If Brewtools is unavailable, report optimization as skipped. The validated agent remains usable.

When to use

• New agent — you need a specialized subagent (reviewer, code-generator, security-scanner, etc.)
• Agent not triggering — the agent exists but Claude doesn’t auto-select it reliably
• Trigger collisions — two agents compete for the same request; need <commentary> disambiguation
• System prompt quality — existing agent body is vague prose instead of dense tables + checklists
• Post-update drift — agent worked before but a plugin update changed naming or available tools

Examples

"Create an agent for code review — reads only, outputs severity table"
"My reviewer agent doesn't trigger when I say 'check this PR'"
"Improve the description of my tester agent, it keeps clashing with developer"

# Natural language triggers — all route to agent-creator
"new agent for security scanning"
"agent isn't picking up my requests"
"fix agent description"

Flow

---
name: agent-name              # REQ: lowercase-hyphens; no leading `-`, no `:` (reserved for plugin namespacing)
description: "..."            # REQ: action verb + Triggers: keyword list
model: sonnet                 # OPT: fable|opus|sonnet|haiku|inherit  (fable=claude-fable-5, Mythos-class, CC 2.1.170+)
effort: high                  # OPT: low|medium|high|xhigh|max (no auto, no bare integer)
maxTurns: 20                  # OPT: integer, max turns before abort
tools: Read, Glob, Grep       # OPT: omit = inherit all
disallowedTools: Write, Edit  # OPT: explicit deny list
skills: skill1, skill2        # OPT: full content injected into context at startup
color: cyan                   # OPT: 8 valid values -- magenta is NOT one
memory: project               # OPT: user|project|local -- auto-adds Read/Write/Edit
background: true              # OPT: keeps it backgrounded even when Claude wants the result; hard-errors on a teammate-spawned agent since CC 2.1.269 -- drop it from a definition that may run as a teammate
omitClaudeMd: true            # OPT: skips ordinary instructions; managed policy exception below; ignored as main
isolation: worktree           # OPT: FM accepts `worktree` only -- LOW PRIORITY, see below (`remote` is invocation-level, never FM)
permissionMode: default       # OPT: LOCAL-ONLY -- ignored + warn in plugin agents
mcpServers: [server1]         # OPT: LOCAL-ONLY -- ignored + warn in plugin agents
initialPrompt: "..."          # OPT: LOCAL-ONLY -- first prompt sent on start
hooks: {}                     # OPT: local agent hook map; ignored for plugin agents
experimental: {cacheTtl: "5m"} # OPT: file definitions only; ignored in --agents JSON
---

Reference files (read on demand)

Agent Creator keeps its full frontmatter catalog, scope/tool rules, execution model, templates, and known-issue log out of this page’s body — same on-demand pattern the source file itself uses. Read the one that matches what you’re doing; skip the rest.

Return Contract

Verdict first, <=30 lines, path:line. No agent bodies, no pasted frontmatter, no analysis transcripts, no preamble. Per generated agent: file path, one-line role, model/maxTurns/tools on one line, validation verdict (pass, or the failing checklist item), text-optimizer run or skipped, and any assumption made about the brief. Longer material — analysis notes, generated bodies, full validation runs — goes to .claude/reports/<YYYYMMDD-HHMMSS>_agent-creator/; only the path comes back.

This is the same discipline Agent Creator bakes into every generated agent — see the Return Contract row in the Guardrails table above, a separate contract from this one. /brewtools:agent-return-setup enforces this at ~1000 / ~2500 est-tokens when installed; the contract itself ships unconditionally.