Brewcode:Agents

agents Skill

Agent Management: Create and improve Claude Code agents interactively.

<instructions>

Phase 1: Parse Arguments

Extract mode and target from $ARGUMENTS:

Examples:

• /brewcode:agents --> help
• /brewcode:agents create backend validator --> create, target=backend validator
• /brewcode:agents up reviewer --> up, target=reviewer
• /brewcode:agents .claude/agents/reviewer.md --> up, target=path (shorthand)

---

Mode: help (empty args)

Print usage and stop:

# brewcode:agents

Agent management - create and improve Claude Code agents.

## Usage
- `/brewcode:agents create <description>` -- create new agent
- `/brewcode:agents up <name|path>` -- improve existing agent
- `/brewcode:agents <name|path>` -- improve (shorthand)

## Examples
- `/brewcode:agents create backend validator`
- `/brewcode:agents up reviewer`
- `/brewcode:agents .claude/agents/reviewer.md`

---

Mode: create

Description Budget (DEFAULT)

Frontmatter description: <= 100 chars (optimal ~80), single line. Role + 2-3 distinct triggers (comma-list). No filler, no <example> blocks in frontmatter. Some registries truncate long descriptions and dilute trigger matching. EN only unless user explicitly asks.

Step 1: AskUserQuestion (batch -- all questions in ONE call)

Ask all 3 questions in a single AskUserQuestion:

Q1 -- Placement:

header: "Agent scope"
question: "Where to place the agent?"
options:
  - label: "Project (.claude/agents/)"
    description: "Team-shared, scoped to this project"
  - label: "Global (~/.claude/agents/)"
    description: "Available in all projects"
  - label: "Plugin (brewcode/agents/)"
    description: "Distributed with plugin"

Q2 -- Model:

header: "Model"
question: "Preferred model?"
options:
  - label: "sonnet -- balanced (Recommended)"
    description: "Best balance of quality and speed for most agents"
  - label: "opus/fable -- hardest tasks"
    description: "opus for deep reasoning; fable (claude-fable-5, Mythos-class) for the hardest tasks"
  - label: "haiku -- fast/simple"
    description: "For quick lookup or simple transformations"
  - label: "inherit -- from session"
    description: "No model field — agent inherits model from calling session"

Model mapping: sonnet → sonnet, opus/fable option → pick opus → opus or fable → fable (claude-fable-5, Mythos-class), haiku → haiku, inherit → omit model: field entirely.

Q3 -- CLAUDE.md update:

header: "CLAUDE.md"
question: "Update CLAUDE.md agents table after creation?"
options:
  - label: "Yes -- add row to agents table"
    description: "Adds agent to the agents table in CLAUDE.md"
  - label: "No -- skip"
    description: "Skip CLAUDE.md update"

Save answers as: SCOPE, SCOPE_PATH, MODEL, UPDATE_CLAUDE_MD.

Path mapping:

• "Project (.claude/agents/)" --> .claude/agents/
• "Global (~/.claude/agents/)" --> ~/.claude/agents/
• "Plugin (brewcode/agents/)" --> brewcode/agents/

Step 2: Spawn agent-creator

Task tool:
  subagent_type: "brewcode:agent-creator"
  prompt: |
    Create an agent for: {DESCRIPTION}

    Placement: {SCOPE} ({SCOPE_PATH})
    Model: {MODEL}

    Follow the agent-creator creation process:
    1. Parallel codebase analysis (Explore agents)
    2. Ask clarifying questions (role, tools, triggers)
    3. Write frontmatter + system prompt
    4. Validate against checklist

    Output: full agent file path after creation.
  model: opus

Capture result as AGENT_PATH.

Step 3: Apply text-optimize

Skill(skill="brewtools:text-optimize", args="{AGENT_PATH}")

Note: requires brewtools plugin. If unavailable -- skip or apply text-optimize-fallback manually.

Step 4: Update CLAUDE.md (if user approved)

• Read project CLAUDE.md
• Find agents table (look for | Agent | or | Name | header row with | Scope | or | Purpose | columns)
• If table exists: add row | agent-name | scope | model | triggers |
• If no table: append section:

  ## Agents

  | Agent | Scope | Model | Triggers |
  |-------|-------|-------|----------|
  | {agent-name} | {scope} | {model} | {triggers} |

• Use Edit tool (never Write for existing files)

---

Mode: up (improve existing)

Step 1: Resolve path/name

EXECUTE using Bash tool:

TARGET="UP_TARGET_HERE"
# Trim whitespace
TARGET="$(echo "$TARGET" | xargs)"

if [[ -z "$TARGET" ]]; then
  echo "NO_TARGET"
  exit 1
fi

# Check if direct file
if [[ -f "$TARGET" ]]; then
  echo "FOUND: $TARGET"
elif [[ -f "$TARGET.md" ]]; then
  echo "FOUND: $TARGET.md"
elif [[ -d "$TARGET" ]] && [[ -f "$TARGET/$(basename "$TARGET").md" ]]; then
  echo "FOUND: $TARGET/$(basename "$TARGET").md"
else
  # Search by name in known locations
  FOUND=""
  for loc in ".claude/agents" "$HOME/.claude/agents" "brewcode/agents"; do
    if [[ -f "$loc/$TARGET.md" ]]; then
      FOUND="$loc/$TARGET.md"
      break
    elif [[ -f "$loc/$TARGET" ]]; then
      FOUND="$loc/$TARGET"
      break
    fi
  done
  if [[ -n "$FOUND" ]]; then
    echo "FOUND: $FOUND"
  else
    echo "NOT_FOUND: $TARGET"
  fi
fi

Replace UP_TARGET_HERE with the actual target extracted from $ARGUMENTS (strip up prefix if present).

STOP if NOT_FOUND -- report error and list available agents.

Read the resolved agent file to extract name, purpose, current content.

Step 2: AskUserQuestion (2 questions in ONE call)

Q1 -- Focus:

header: "Improvement focus"
question: "What to improve?"
options:
  - label: "Triggers/activation"
    description: "Improve description and trigger examples for better auto-detection"
  - label: "System prompt quality"
    description: "Enhance instructions, checklist, output format"
  - label: "Both (Recommended)"
    description: "Triggers + system prompt quality"
  - label: "Full review + project context"
    description: "Complete review including project-specific knowledge update"

Q2 -- CLAUDE.md update:

header: "CLAUDE.md"
question: "Update CLAUDE.md agents table after?"
options:
  - label: "Yes"
    description: "Update agents table row in CLAUDE.md"
  - label: "No"
    description: "Skip CLAUDE.md update"

Save answers as: IMPROVEMENT_FOCUS, UPDATE_CLAUDE_MD.

Step 3: Spawn agent-creator

Task tool:
  subagent_type: "brewcode:agent-creator"
  prompt: |
    Improve existing agent. Focus: {IMPROVEMENT_FOCUS}

    Agent path: {AGENT_PATH}
    Current content:
    {AGENT_CONTENT}

    Tasks:
    1. Analyze current strengths/weaknesses
    2. Improve description trigger examples
    3. Enhance system prompt clarity
    4. Apply agent-creator best practices
    5. Save updated file

    Output: full agent file path after update.
  model: opus

Step 4: Apply text-optimize

Skill(skill="brewtools:text-optimize", args="{AGENT_PATH}")

Note: requires brewtools plugin. If unavailable -- skip or apply text-optimize-fallback manually.

Step 5: Update CLAUDE.md (if approved)

Same logic as create Step 4. If row already exists for this agent, update it instead of adding a new one.

</instructions>

---

Output Format

# agents [{MODE}]

## Detection

| Field | Value |
|-------|-------|
| Arguments | `$ARGUMENTS` |
| Mode | `[create|up|help]` |
| Target | `[description or path]` |

## Result

| Field | Value |
|-------|-------|
| Agent | `[path]` |
| Model | `[model]` |
| Scope | `[project|global|plugin]` |
| CLAUDE.md | `[updated|skipped]` |

## Next Steps

- [recommendations]

Agents

Interactive agent creation and improvement orchestrator. Create new Claude Code agents or improve existing ones through a guided, multi-step workflow powered by the agent-creator subagent.

Quick Start

/brewcode:agents create backend validator
/brewcode:agents up reviewer

Modes

Examples

Good Usage

# Create a new agent with a plain-English description
/brewcode:agents create database migration checker

# Improve an existing agent by name (searches known locations)
/brewcode:agents up reviewer

# Improve by explicit path (shorthand -- no "up" keyword needed)
/brewcode:agents .claude/agents/reviewer.md

# Improve a global agent
/brewcode:agents up ~/.claude/agents/my-helper.md

Common Mistakes

# Missing description after "create" -- nothing to create
/brewcode:agents create

# Trying to improve an agent that does not exist -- will fail with NOT_FOUND
/brewcode:agents up nonexistent-agent

# Passing multiple keywords -- only the first keyword is recognized
/brewcode:agents create up reviewer

Workflow

Create Mode

1. Questions (single prompt) -- scope (project / global / plugin), model (sonnet / opus / haiku / inherit), CLAUDE.md update preference. 2. agent-creator -- subagent analyzes codebase in parallel, asks clarifying questions about role and tools, writes frontmatter + system prompt, validates against checklist. 3. brewtools:text-optimize -- automatic token optimization pass on the generated agent file (requires brewtools plugin). 4. CLAUDE.md update -- if approved, adds or creates an agents table row.

Improve (up) Mode

1. Resolve -- locates the agent file by name or path across .claude/agents/, ~/.claude/agents/, and brewcode/agents/. 2. Questions (single prompt) -- improvement focus (triggers, system prompt, both, or full review) and CLAUDE.md update preference. 3. agent-creator -- subagent analyzes current strengths and weaknesses, enhances the file per the chosen focus. 4. brewtools:text-optimize -- automatic token optimization pass (requires brewtools plugin). 5. CLAUDE.md update -- if approved, updates the existing row or adds a new one.

Output

The skill produces a structured report:

# agents [create|up]

## Detection
| Field | Value |
| Arguments | ... |
| Mode | create / up / help |
| Target | description or resolved path |

## Result
| Field | Value |
| Agent | /path/to/agent.md |
| Model | sonnet / opus / haiku / inherit |
| Scope | project / global / plugin |
| CLAUDE.md | updated / skipped |

## Next Steps
- [recommendations]

Agent files are written to the directory matching the chosen scope:

Tips

• Use shorthand (/brewcode:agents reviewer) for the fastest path to improving an existing agent -- no up keyword needed.
• The "inherit" model option omits the model: field entirely, so the agent uses whatever model the calling session runs on.
• After creation, review the generated triggers in the agent's description frontmatter -- good triggers are the main driver of automatic agent selection.
• Run /brewcode:agents up periodically on high-use agents to incorporate new project context and best practices.

Documentation

Full docs: agents