Agent

# Agent-Builder Command

<instructions>
  <context>
    Interactive meta-command that transforms a brief agent concept into a production-ready
    Claude Code agent specification with YAML frontmatter and comprehensive instructions.
    Leverages systematic clarification, template-based generation, and multi-agent review
    to ensure agents are effective, well-bounded, and aligned with best practices.
  </context>

  <requirements>
    - Accept single-string $ARGUMENTS describing the agent concept
    - Support flags: --fast (minimal questions), --dest (output location), --type (workflow/autonomous)
    - Comprehensive clarification strategy:
      * Minimum 15-20 questions for standard agents
      * 25-30 questions for complex multi-tool agents
      * Fast mode: minimum 8-10 essential questions
      * Track coverage across 18+ agent design categories
    - Dynamic question generation based on agent complexity and domain
    - Multi-level questioning with intelligent follow-ups
    - Show clarification progress: "[Questions: 12/20 | Coverage: 72%]"
    - Suggest output folder by scanning .claude/commands/* for agent directories
    - write file as Markdown with YAML frontmatter
    - Add reviewer sub-agents (Tool-Selection, Boundary-Definition, Instruction-Clarity)
    - Self-critique checklist: YAML validity, tool appropriateness, clear boundaries
    - Always ask clarifying questions sequentially, evaluating need for follow-ups
    - Every agent must have clear trigger conditions in description
    - Emit concise success summary with agent capabilities overview
    - Save the agent under `.claude/agents`
    - Make the final file use the templates/pseudo-xml style! Except for the YAML frontmatter
  </requirements>

  <execution>
    1. <init>
         - Scan .claude/commands for existing agents and patterns
         - Determine agent type from initial description
    2. <clarify>
         - Initialize question categories for agent design:
           * Core Purpose: What specific problem domain does this agent address?
           * Trigger Conditions: When should Claude use this agent?
           * Capabilities: What tasks can the agent perform?
           * Boundaries: What must the agent NOT do?
           * Tools Required: Which tools does the agent need?
           * Interaction Style: How should the agent communicate?
           * Domain Expertise: What knowledge areas are crucial?
           * Decision Making: How autonomous should the agent be?
           * Error Recovery: How should the agent handle failures?
           * Quality Metrics: How is success measured?
           * User Guidance: What information does the agent need from users?
           * Workflow Patterns: Sequential steps vs dynamic decisions?
           * Output Format: What should the agent produce?
           * Edge Cases: Unusual scenarios to handle?
           * Integration: How does it work with other agents?
           * Performance: Expected complexity and runtime?
           * Safety: Risk assessment and mitigation?
           * Examples: Concrete usage scenarios?
         - Ask questions sequentially, tracking coverage
         - Generate follow-up questions based on responses:
           * If multi-tool: ask about tool coordination
           * If autonomous: ask about decision boundaries
           * If specialized: ask about domain-specific needs
         - Show progress after every 3 questions
         - Continue until minimum coverage achieved
    3. <draft>
         - Generate YAML frontmatter (name, description with examples, tools, color)
         - Create comprehensive agent instructions
         - Include concrete behavioral examples
    4. <self-critique>
         - Run comprehensive internal checklist:
           * Minimum questions asked (15 normal, 8 fast)?
           * All critical categories covered?
           * Agent purpose crystal clear?
           * Trigger conditions well-defined?
           * Boundaries explicitly stated?
           * Tool selection appropriate?
           * Instructions actionable and specific?
         - Revise draft based on gaps found
    5. <review>
         - Spawn sub-agents:
             * Tool-Selection Reviewer (are tools necessary and sufficient?)
             * Boundary-Definition Reviewer (are limits clear?)
             * Instruction-Clarity Reviewer (can another LLM follow these?)
         - Merge feedback, update specification
    6. <validate>
         - Verify YAML syntax and required fields
         - Check description includes trigger examples
         - Ensure instructions follow best practices
    7. <write>
         - Write `.claude/agents/<agent-name>.md` (or --dest)
         - Format: YAML frontmatter + markdown instructions
    8. <report>
         - Echo file path, agent capabilities summary
         - List tools selected and key boundaries
  </execution>

  <validation>
    - [ ] Minimum 15 clarification questions asked (8 in fast mode)
    - [ ] Coverage across all 18+ agent design categories
    - [ ] Critical categories have 3-4 clarifications each
    - [ ] Follow-up questions generated for complex features
    - [ ] Agent purpose and triggers clearly defined
    - [ ] Tool selection justified and minimal
    - [ ] Boundaries and limitations explicit
    - [ ] Instructions include DO and DON'T sections
    - [ ] Description includes 3+ example scenarios
    - [ ] YAML frontmatter valid and complete
    - [ ] Reviewer agents approved
    - [ ] No placeholder text or TODOs remain
  </validation>

  <examples>
    ```bash
    # Full interactive flow for code refactoring agent
    /agent:builder "Create an agent that helps improve code quality and structure"

    # Fast mode for security analysis agent
    /agent:builder --fast --type=workflow "Security vulnerability scanner"

    # Custom destination for documentation agent
    /agent:builder --dest=.claude/commands/docs "Technical documentation generator"
    ```

  </examples>