name: agent-builder description: This skill should be used when the user asks to "build an agent", "create an agent", "design a new agent", "make me an agent that", "agent from this prompt", "build an agent from these docs", "design a multi-agent workflow", "optimize agent models", or needs to create Claude Code agents from requirements and supporting documents with model optimization and cost-aware multi-agent workflow support. version: 0.1.0

Agent Builder

Design and generate production-ready Claude Code agents from user requirements, supporting documents, and domain knowledge. Supports single agents and multi-agent workflows with model optimization and cost-aware recommendations.

When to Use

• User wants to create a new Claude Code agent from a description or prompt
• User has supporting documents (PDFs, markdown, URLs) that should inform the agent's domain expertise
• User needs a multi-agent workflow where several agents cooperate
• User wants to optimize model selection across agents for cost/quality tradeoffs
• User wants to convert an existing process or rubric into an autonomous agent

Workflow

Phase 1: Intake

Gather requirements for the agent(s) to be built. Ask the user these questions:

1. What should the agent do? Accept a natural-language description of the agent's purpose, responsibilities, and expected behavior.
2. Supporting documents? Ask if the user has any supporting materials: PDFs, markdown files, URLs, rubrics, checklists, or domain documentation. Read all provided documents using Read (for files) or WebFetch (for URLs).
3. Single or multi-agent? Determine whether this is a single agent or a multi-agent workflow.
   • For multi-agent: How should agents coordinate? Common patterns:
     • Pipeline: Agent A output feeds Agent B input (sequential)
     • Fan-out: One triage agent dispatches to N specialist agents
     • Triage + specialist: A lightweight agent classifies, then routes to domain experts
4. Trigger behavior: Should the agent be proactive (auto-triggers based on context), reactive (only when explicitly asked), or both?
5. Tools needed? What tools does the agent require? Apply the principle of least privilege:
   • Read-only analysis: ["Read", "Grep", "Glob"]
   • Code generation: ["Read", "Write", "Grep", "Glob"]
   • Testing/execution: ["Read", "Write", "Bash", "Grep"]
   • Web research: ["Read", "WebSearch", "WebFetch"]
   • Full access: omit the tools field
6. Deployment location: Where should the agent .md file(s) be placed? Default: agents/ directory in the current project or plugin.

If the user provides a brief one-liner, ask clarifying questions. If they provide detailed requirements, proceed directly.

Phase 2: Budget Discovery

Understand the user's cost constraints to inform model selection across all agents.

Ask:

1. API plan tier: Free, Pro, Team, or Enterprise?
2. Monthly budget ceiling: Approximate monthly spend limit for Claude API usage.
3. Priority: Is cost or quality the higher priority? (Or balanced?)

If the user declines to share budget details, default to "balanced Pro tier" assumptions and note this in the output.

Record the user's answers for use in Phase 5 (Model Optimization).

Phase 3: Research

Gather domain knowledge to make the agent(s) expert in their domain.

1. Read supporting documents: Read all PDFs, markdown files, and URLs the user provided. Extract:
   • Domain terminology and jargon
   • Decision frameworks and rubrics
   • Process steps and checklists
   • Quality criteria and standards
   • Edge cases and exceptions
2. Web research: If the domain would benefit from current best practices, search the web for relevant patterns:
   • Search for "[domain] best practices 2026"
   • Search for "[domain] common mistakes"
   • Search for "Claude Code agent [domain]" for existing examples
3. Read agent schema: Read references/agent-schema.md to ensure the generated agent(s) conform to the required format.
4. Synthesize findings: Compile a domain knowledge brief that will be incorporated into the agent's system prompt. This brief should capture:
   • Key concepts the agent must understand
   • Decision rules and heuristics
   • Common pitfalls to avoid
   • Domain-specific output formats

Present a brief summary of research findings to the user before proceeding.

Phase 4: Design

Design each agent's configuration. For each agent in the workflow:

1. Identifier: Draft a name (3-50 chars, lowercase + hyphens, starts/ends alphanumeric). Make it descriptive of the agent's role.
2. Description: Write the description field with:
   • Clear triggering conditions ("Use this agent when...")
   • 2-4 <example> blocks showing context, user request, assistant response, and commentary
   • Both proactive and reactive triggering scenarios (if applicable)
3. System prompt structure: Design the body of the agent file following the standard template:
   • Role statement: "You are [specific role] specializing in [specific domain]."
   • Core Responsibilities: 3-8 specific, actionable responsibilities
   • Process: 5-12 concrete steps the agent follows
   • Quality Standards: 3-5 measurable standards
   • Output Format: Exact format for the agent's results
   • Edge Cases: 3-5 edge cases with specific handling instructions
4. Color: Select based on agent purpose:
   • Blue/cyan: analysis, review, investigation
   • Green: generation, creation
   • Yellow: validation, warnings
   • Red: security, critical analysis
   • Magenta: refactoring, transformation
5. Tools: Select the minimum set needed (least privilege principle).

For multi-agent workflows, additionally define:

• Coordination pattern: How agents interact (pipeline, fan-out, triage+specialist)
• Handoff protocol: What data each agent passes to the next
• Ordering: Which agent runs first, second, etc.

Present the complete design to the user for review before generating files. Format as a table:

| Agent | Role | Color | Tools | Coordination |
|-------|------|-------|-------|--------------|
| name  | desc | color | [...] | role in workflow |

Wait for user approval or modifications before proceeding.

Phase 5: Model Optimization

Read references/model-selection-guide.md and apply the scoring framework.

For each agent:

1. Score 5 dimensions (each 1-5):

   • Reasoning Depth: How complex is the reasoning required?
   • Domain Complexity: How specialized is the knowledge needed?
   • Output Quality Sensitivity: How bad are errors?
   • Speed Priority: How fast must responses be?
   • Cost Sensitivity: How constrained is the budget?

2. Compute weighted score:

   Score = (Reasoning*2) + (Complexity*2) + (Quality*2) + (Speed*-1) + (Cost*-1)
   

3. Map to model:

   • = 18: opus

   • 10-17: sonnet
   • 5-9: haiku
   • < 5: inherit

4. Apply override rules:

   • Security-critical tasks: upgrade one tier
   • Frequently-triggered agents (>10x/session): downgrade one tier

For multi-agent workflows, additionally:

1. Compute total workflow cost: Sum of (model_cost_ratio * estimated_invocations) across all agents. Use ratios: haiku=1x, sonnet=5x, opus=15x.

2. Compare against budget: If total workflow cost exceeds the user's stated constraints, recommend downgrades:

   • Downgrade agents with the lowest Output Quality Sensitivity scores first
   • Present the savings: "Downgrading Agent X from opus to sonnet saves ~60% on that step"

Present per-agent recommendations in a table:

| Agent | R | C | Q | S | $ | Score | Model | Override? |
|-------|---|---|---|---|---|-------|-------|-----------|

For multi-agent workflows, add a workflow cost summary:

| Agent | Model | Est. Invocations | Cost Units |
|-------|-------|-------------------|------------|
| total |       |                   | X units    |
| budget|       |                   | Y units    |

Allow the user to override any model recommendation per agent.

Phase 6: Generate

Write the complete agent .md file(s).

For each agent:

1. Write YAML frontmatter: Include all required fields (name, description, model, color) and optional fields (tools) as determined in Phases 4-5.
2. Write system prompt body: Incorporate:
   • Domain knowledge extracted from supporting documents (Phase 3)
   • Role statement, responsibilities, process, standards, output format, edge cases (Phase 4)
   • Any domain-specific terminology, rubrics, or checklists from supporting docs
3. Validate length: System prompt should be 500-5,000 characters for standard agents, up to 10,000 for comprehensive agents. Never exceed 10,000.

Use the Write tool to create each agent file.

Phase 7: Validate

Check every generated agent file against the schema.

For each agent file, verify:

Frontmatter checks:

• [ ] name: 3-50 chars, lowercase + hyphens only, starts/ends alphanumeric
• [ ] description: 10-5,000 chars, includes triggering conditions, includes <example> blocks
• [ ] model: one of inherit, sonnet, opus, haiku
• [ ] color: one of blue, cyan, green, yellow, magenta, red
• [ ] tools (if present): valid array of tool names

System prompt checks:

• [ ] Written in second person ("You are...")
• [ ] Includes Core Responsibilities (3-8 items)
• [ ] Includes Process steps (5-12 steps)
• [ ] Includes Quality Standards (3-5 items)
• [ ] Includes Output Format
• [ ] Includes Edge Cases (3-5 items)
• [ ] Length: 500-10,000 characters

Multi-agent checks (if applicable):

• [ ] Coordination references are consistent across agents
• [ ] Handoff data formats match between producer and consumer agents
• [ ] No circular dependencies in the workflow

Report results per agent:

## Validation Results

| Agent | Frontmatter | System Prompt | Multi-Agent | Result |
|-------|-------------|---------------|-------------|--------|
| name  | PASS/FAIL   | PASS/FAIL     | PASS/FAIL   | PASS   |

If any check fails, fix the issue immediately and re-validate.

Phase 8: Deploy

Place files and provide deployment guidance.

1. Place files: Write agent .md file(s) to the target agents/ directory determined in Phase 1.
2. Summary: For each agent, report:
   • File path
   • Agent name and model
   • How it triggers (proactive/reactive/both)
   • Key capabilities
3. Testing instructions: Provide 2-3 test prompts the user can try to verify the agent triggers correctly.
4. Multi-agent workflow diagram (if applicable): Show agent interactions using a text diagram:

[User Request]
      |
  [triage-agent] (haiku)
      |
  +---+---+
  |       |
[agent-a] [agent-b]
(sonnet)  (opus)
  |       |
  +---+---+
      |
  [Final Output]

Include model assignments and estimated cost per invocation in the diagram.

Important Guidelines

• Always read references/agent-schema.md before generating any agent file.
• Always read references/model-selection-guide.md before making model recommendations.
• Never skip the user review step in Phase 4 — the user must approve the design before generation.
• Never skip validation in Phase 7 — every agent must pass all checks.
• Incorporate domain knowledge from supporting documents directly into system prompts — don't just summarize, make the agent an expert.
• For multi-agent workflows, ensure each agent's system prompt references how it interacts with other agents in the workflow.
• Apply the principle of least privilege for tool access — only grant tools the agent actually needs.
• When uncertain about model selection, default to sonnet as the balanced choice.

Reference Files

• references/agent-schema.md — Complete agent file specification: frontmatter fields, validation rules, system prompt structure
• references/model-selection-guide.md — Model optimization rubric: 5-dimension scoring, weighted matrix, cost estimation, multi-agent budget planning