Agent Creator

Caution

Agents with vague descriptions trigger on the wrong requests — or never trigger at all. A bad description means Claude picks the wrong agent, spams irrelevant ones, or silently falls back to the main conversation. Most hand-written agents also leak CLAUDE.md rules into the body (already injected) or forget the Triggers: keyword list that drives auto-selection.

Tip

Describe what you want — the agent handles the rest. It runs parallel analysis of your codebase, drafts the frontmatter and system prompt, validates against Anthropic best practices, then optimizes with brewtools:text-optimize. Improvement and debugging of existing agents follow the same flow.

Quick reference

FieldValue
Triggers”create agent”, “new agent”, “agent doesn’t trigger”, “improve agent”, “fix agent description”
Modelopus
ToolsRead, Write, Edit, Glob, Grep, Task, Skill, WebFetch, WebSearch, AskUserQuestion

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

  1. Clarify intent

    Asks 2-3 targeted questions: desired role, allowed tools, model tier (opus / sonnet / haiku). For improvement requests, reads the existing agent file first.

  2. Parallel analysis

    Launches multiple Explore subagents concurrently — codebase conventions, existing agents in scope, CLAUDE.md rules, stack details. Results are merged before writing.

  3. Synthesize

    Extracts project-specific patterns, naming conventions, and anti-patterns. Determines description format: single-line, with Triggers: list, or multi-line with <example> blocks (for ambiguous agents only).

  4. Write

    Produces a complete .md file: frontmatter with all required and relevant optional fields, then a system prompt structured as Role → Context → Patterns → Commands → Checklist.

  5. Validate

    Checks name format ([a-z0-9-]+), description keyword density, tool minimality (least privilege), no duplicated CLAUDE.md rules in body, unique name in scope.

  6. Optimize

    Runs brewtools:text-optimize on the output — converts prose to tables, removes filler, trims to dense LLM-readable format (~30% token savings typical).

Frontmatter reference — all fields
---
name: agent-name              # REQ: [a-z0-9-]+
description: "..."            # REQ: action verb + Triggers: keyword list
model: sonnet                 # OPT: sonnet|opus|haiku|inherit
effort: high                  # OPT: low|medium|high|auto (plugin agents, v2.1.78+)
maxTurns: 20                  # OPT: integer (plugin agents, v2.1.78+)
tools: Read, Glob, Grep       # OPT: omit = inherit all
disallowedTools: Write, Edit  # OPT: explicit deny list (v2.1.78+)
permissionMode: default       # OPT: default|acceptEdits|dontAsk|bypassPermissions|plan
skills: skill1, skill2        # OPT: full content injected at startup
color: cyan                   # OPT: cyan|green|yellow|red|magenta
memory: true                  # OPT: agent-specific MEMORY.md; auto-adds Read/Write/Edit
initialPrompt: "..."          # OPT: first prompt sent on start (v2.1.69+)
isolation: worktree           # OPT: isolated git worktree (v2.1.50+)
worktree:
  baseRef: main               # OPT: branch the worktree forks from (CC 2.1.115+, default: current HEAD)
mcpServers: [server1]         # OPT: restrict which MCP servers agent accesses
---

Caution

Do not set permissionMode: bypassPermissions by default. This is equivalent to running with --dangerously-skip-permissions — it silently skips all safety prompts. Only use it for fully-sandboxed CI environments where there is no interactive user. For local development, prefer permissionMode: default or permissionMode: acceptEdits.

Description patterns by ambiguity level:

OverlapFormatExample
None — unique domainSingle-line action + Triggers"Implements features, fixes bugs. Triggers: implement, fix bug, add feature"
Some — 1-2 other agentsSingle-line + detailed Triggers"Creates bash scripts. Triggers: create script, bash script, shell script"
High — creator/meta agentsMulti-line + 2-3 <example> blocksSee agent-creator.md source

Subagent spawn constraint: subagents run in SubAgentLoop which excludes AgentTool. Nesting is not possible by design — chain from the main conversation instead.

Known active bugs: #29423 (subagents skip CLAUDE.md), #27736 (skills: in plugin agents), #31392 (global agents not discovered in v2.1.70+).

🧩

Skill Creator

Same design process for skills instead of agents.

🔗

GitHub source

Full frontmatter reference, description patterns, and system prompt templates.

🚀

Brewcode overview

All brewcode agents, skills, and hooks in one place.

Updating plugins

Use /brewtools:plugin-update to check and update the brewcode plugin suite in one command. See the FAQ for details.