agents — create / improve agents

Caution

Agents without sharp trigger descriptions misfire constantly. Claude auto-selects agents by matching your request against their description field — a vague description means the wrong agent fires, or none at all. Writing good frontmatter by hand is tedious and error-prone.

Tip

One skill scaffolds or refines any agent. /brewcode:agents create spawns agent-creator + runs text-optimize on the result. /brewcode:agents up improves triggers and system prompt quality on an existing agent. CLAUDE.md agents table update is optional and prompted.

Quick reference

Field	Value
Command	`/brewcode:agents`
Arguments	`[create <description>\|up <name\|path>] \| <name\|path>`
Model	opus
Context	session
Tools	Read, Write, Edit, Glob, Grep, Bash, Task, AskUserQuestion, Skill

When to use

New agent from scratch — create mode scaffolds frontmatter, system prompt, and trigger phrases in one pass
Existing agent misfires — up mode tunes description trigger keywords and activation examples
System prompt is stale — up with “Full review + project context” option pulls in current codebase patterns
CLAUDE.md agents table out of sync — skill can update the table row automatically after create or improve

Scenario	Command
New agent for backend validation	`/brewcode:agents create backend validator`
Improve the reviewer agent	`/brewcode:agents up reviewer`
Improve by file path	`/brewcode:agents .claude/agents/reviewer.md`
Show usage	`/brewcode:agents`

Examples

# Create a new agent — guided placement + model + CLAUDE.md questions
/brewcode:agents create backend validator

# Improve existing agent — shorthand (no "up" prefix needed)
/brewcode:agents reviewer

# Explicit improve with full path
/brewcode:agents up .claude/agents/tester.md

Expected output after create:

# agents [create]

## Detection
| Field    | Value             |
|----------|-------------------|
| Mode     | create            |
| Target   | backend validator |

## Result
| Field     | Value                          |
|-----------|--------------------------------|
| Agent     | .claude/agents/validator.md    |
| Model     | sonnet                         |
| Scope     | project                        |
| CLAUDE.md | updated                        |

## Next Steps
- Run /reload-plugins to pick up the new agent
- Test with: "validate the API response schema"

Flow

Parse arguments
Extracts mode and target from $ARGUMENTS. Empty args → prints usage and stops. Prefix create → create mode. Prefix up or a bare name/path → improve mode.
Ask clarifying questions (one batch)
create: three questions in a single AskUserQuestion call — placement scope (project / global / plugin), preferred model (sonnet / opus / haiku / inherit), and whether to update CLAUDE.md. up: two questions — improvement focus (triggers / system prompt / both / full review) and CLAUDE.md update.
Resolve target (up mode only)
Searches .claude/agents/, ~/.claude/agents/, and brewcode/agents/ for the name or path. Stops with an error and lists available agents if the target is not found.
Spawn agent-creator subagent
Delegates to brewcode:agent-creator via Task tool with full context — description or current file content, placement, model, and improvement focus. Returns the written file path.
Optimize with text-optimize
Runs brewtools:text-optimize on the agent file to trim token bloat without losing meaning. Skipped silently if brewtools is not installed.
Update CLAUDE.md (if approved)
Finds the agents table by header pattern (| Agent | or | Name |) and adds or updates the row. Appends a new ## Agents section if no table exists. Always uses Edit, never Write, on an existing file.
Print result summary
Outputs a detection + result table: mode, target, agent path, model, scope, and CLAUDE.md status. Suggests next steps — typically /reload-plugins and a test invocation phrase.

Phase internals — argument parsing table

Pattern	Mode	Target
empty	help	—
`create <desc>`	create	description text
`up <name\|path>`	up	agent name or path
`<name\|path>` (no keyword)	up (shorthand)	name or path

Placement path mapping:

Selection	Path
Project	`.claude/agents/`
Global	`~/.claude/agents/`
Plugin	`brewcode/agents/`

🧩

Updating plugins

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