Agent Team Builder

Agent Team Builder

Design and generate production-ready multi-agent team configurations for business workflows through an interactive discovery session. This skill generates configuration files; it does not execute or deploy agents.

Contents

• references/team-templates.md — Sales, Support, Research, and Content team starting points.
• references/config-schema.md — Full team-config.yaml schema plus advanced features (A2A messaging, scaling, shared context).
• references/output-files.md — Files to generate and the final response format.

Workflow

Always complete discovery before designing. Never generate a team config without understanding the business process first.

1. Run discovery. Ask the user, one area at a time:

• Process name (what to automate).
• Current state (who is involved, handoff points).
• Pain points (where delays, errors, or bottlenecks occur).
• Volume (runs per day/week/month).
• Success metrics (time, error rate, satisfaction).
• Constraints (compliance, approval gates, human-in-the-loop).
• Integrations (CRM, email, Slack, databases, APIs).

2. Design the team architecture. Determine the minimum number of agents (typically 3-7). Select role types as needed:

• Coordinator — orchestrates workflow, routes tasks, handles exceptions.
• Specialist — deep expertise in one domain.
• Validator — quality assurance, compliance checking, output review.
• Interface — handles external communication.
• Data — manages retrieval, transformation, and storage.

Pick a communication pattern: hub-and-spoke (sequential), pipeline (linear), mesh (collaborative), or broadcast (notification). Start from a template in references/team-templates.md when one fits.

3. Specify each agent. Define: Agent ID, Role Title, full production-ready System Prompt, Tool Access (least privilege), Input Schema, Output Schema, Handoff Rules, Escalation Rules, Success Criteria, and Failure Modes.

4. Generate the configuration files. Produce team-config.yaml, per-agent agents/{id}/prompt.md, workflow.md, and test-scenarios.yaml per references/output-files.md, conforming to references/config-schema.md.

5. Present the design using the response format in references/output-files.md.

Execution Rules

1. Always start with discovery. 2. Apply principle of least privilege — give each agent only the tools and access it needs. 3. Design for failure — every agent gets failure modes and recovery strategies. 4. Keep a human in the loop — include escalation paths for high-stakes decisions. 5. Define measurable outcomes — every agent gets trackable success criteria. 6. Start small — recommend 3-4 agents and expand based on performance data. 7. Document everything — keep the generated config self-documenting and maintainable. 8. Generate test scenarios so the team can be validated before deployment. 9. Recommend a pilot phase before full deployment. 10. Never include API keys, passwords, or secrets in generated config; use environment variable references.

The generated team-config.yaml is designed to be consumed by an agent orchestration framework. Treat all generated system prompts as starting points to refine against real-world performance.

Configuration Schema

The complete team-config.yaml follows this schema.

# Team Configuration Schema
version: "1.0"
team:
  name: string              # Unique team identifier
  description: string       # Human-readable description
  created: datetime         # ISO 8601 creation timestamp
  updated: datetime         # ISO 8601 last update timestamp
  owner: string             # Team owner email or ID
  communication_pattern: enum[hub-and-spoke, pipeline, mesh, broadcast]
  max_concurrent_tasks: integer  # Maximum parallel task execution
  timeout_seconds: integer       # Default task timeout
  retry_policy:
    max_retries: integer
    backoff_multiplier: float
    max_backoff_seconds: integer

coordinator:
  agent_id: string          # ID of the coordinator agent
  health_check_interval: integer  # Seconds between health checks
  rebalance_threshold: float      # Load imbalance threshold for rebalancing

agents:
  - id: string              # Unique agent identifier
    role: string            # Human-readable role name
    description: string     # What this agent does
    tools: array[string]    # Allowed tools
    model: string           # LLM model to use (default: inherit)
    temperature: float      # Generation temperature (0.0-1.0)
    max_tokens: integer     # Maximum output tokens
    system_prompt: string   # Full system prompt (or path to prompt file)
    input_schema:           # Expected input format
      type: object
      properties: {}
    output_schema:          # Expected output format
      type: object
      properties: {}
    triggers:               # What activates this agent
      - event: string       # Event name
      - schedule: string    # Cron expression
      - condition: string   # Boolean expression
    handoff_rules:          # When to pass work to another agent
      - condition: string
        target: string      # Target agent ID
        data: array[string] # What data to pass
    escalation:             # When to involve humans
      - condition: string
        target: enum[human, manager, on-call]
        channel: enum[slack, email, pagerduty]
        message: string
        sla_minutes: integer
    rate_limits:
      requests_per_minute: integer
      tokens_per_minute: integer
    monitoring:
      log_level: enum[debug, info, warn, error]
      metrics: array[string]
      alerts:
        - condition: string
          channel: string
          severity: enum[info, warning, critical]
    success_criteria:
      - metric: string
        target: string
        measurement_window: string
    failure_modes:
      - scenario: string
        recovery: string
        alert: boolean

workflows:
  - name: string
    description: string
    trigger: string
    steps:
      - agent: string       # Agent ID
        action: string      # What the agent does in this step
        input_from: string  # Where input comes from (trigger, previous step, etc.)
        output_to: string   # Where output goes
        timeout: integer
        on_failure: enum[retry, skip, escalate, abort]

shared_resources:
  knowledge_base: string    # Path to shared knowledge base
  templates: string         # Path to shared templates
  credentials: string       # Path to credentials (encrypted)
  data_stores:
    - name: string
      type: enum[file, database, api]
      connection: string
      access: array[string] # Which agents can access

Advanced Features

Agent-to-Agent Communication Protocol

When agents need to communicate, they use a standardized message format.

message:
  from: agent_id
  to: agent_id
  type: enum[request, response, notification, escalation]
  priority: enum[low, medium, high, critical]
  correlation_id: uuid    # Links related messages
  timestamp: iso8601
  payload:
    action: string
    data: object
    context: object       # Shared context from previous steps
  metadata:
    attempt: integer
    timeout_at: iso8601
    callback: string      # Where to send the response

Dynamic Team Scaling

Teams can scale based on workload.

scaling:
  min_instances: 1
  max_instances: 5
  scale_up_threshold: 0.8    # Scale up when queue depth exceeds 80% capacity
  scale_down_threshold: 0.2  # Scale down when queue depth drops below 20%
  cooldown_seconds: 300      # Wait before scaling again

Shared Context Management

Agents share context through a managed state store.

shared_context:
  store_type: file           # file, redis, database
  path: ./team-state/
  ttl_seconds: 86400         # Context expires after 24 hours
  access_control:
    - agent: coordinator
      permissions: [read, write, delete]
    - agent: specialist
      permissions: [read, write]
    - agent: validator
      permissions: [read]

Output Files and Response Format

Files to Generate

After completing discovery and design, generate these files in the user's specified output directory (default: ./agent-team/).

1. team-config.yaml

The master configuration file containing:

• Team metadata (name, description, version, created date)
• Communication pattern and protocols
• All agent definitions with full specifications
• Workflow triggers and schedules
• Escalation matrix
• Monitoring and alerting rules

See config-schema.md for the full schema.

2. Individual Agent Prompts

For each agent, generate a separate file at agents/{agent-id}/prompt.md containing:

• Role definition and personality
• Domain expertise and knowledge
• Input/output specifications
• Decision frameworks
• Example interactions
• Edge case handling

3. Workflow Diagrams

Generate a workflow.md file with:

• Mermaid diagram showing agent communication flow
• State machine for the overall process
• Decision tree for routing logic
• Escalation path diagram

4. Testing Scenarios

Generate a test-scenarios.yaml file with:

• Happy path scenarios for each workflow
• Edge cases and failure scenarios
• Load testing parameters
• Expected outputs for validation

Response Format

After discovery is complete, present the team design using this structure.

## Team Design: [Team Name]

### Architecture Overview
[Mermaid diagram of agent communication]

### Agent Roster
| Agent | Role | Tools | Handoff To |
|-------|------|-------|------------|
| ... | ... | ... | ... |

### Workflow Summary
[Step-by-step description of how work flows through the team]

### Escalation Matrix
[When and how humans are involved]

### Estimated Impact
- Current process time: [X hours/minutes]
- Automated process time: [Y hours/minutes]
- Error reduction: [estimated %]
- Capacity increase: [estimated %]

### Files Generated
- team-config.yaml
- agents/{id}/prompt.md (for each agent)
- workflow.md
- test-scenarios.yaml

Team Templates

Use these common team patterns as starting points, then customize based on discovery. Prefer fewer, more capable agents over many narrow ones.

Sales Team Template

team:
  name: sales-automation-team
  description: End-to-end sales pipeline automation
  communication_pattern: hub-and-spoke
  coordinator: lead-router

agents:
  - id: lead-router
    role: Sales Coordinator
    description: Routes incoming leads, monitors pipeline health, escalates stalled deals
    tools: [Read, Write, Bash, Glob]
    triggers:
      - event: new_lead_received
      - event: deal_stalled_72h
      - schedule: daily_pipeline_review
    handoff_rules:
      - condition: "lead.score >= 80"
        target: deal-strategist
      - condition: "lead.score >= 50 AND lead.score < 80"
        target: lead-nurturer
      - condition: "lead.score < 50"
        target: lead-qualifier
    escalation:
      - condition: "deal.value > 100000"
        target: human
        channel: slack
        message: "High-value deal requires human review"

  - id: lead-qualifier
    role: Lead Qualification Specialist
    description: Researches and scores inbound leads using firmographic and behavioral data
    tools: [Read, Write, Bash]
    system_prompt: |
      You are a lead qualification specialist. Your job is to research incoming leads
      and produce a qualification score with supporting evidence.

      QUALIFICATION FRAMEWORK (BANT):
      - Budget: Can they afford the solution? (0-25 points)
      - Authority: Is this person a decision maker? (0-25 points)
      - Need: Do they have a clear pain point we solve? (0-25 points)
      - Timeline: Are they looking to buy within 6 months? (0-25 points)

      RESEARCH PROTOCOL:
      1. Check company website for size, industry, and recent news
      2. Review LinkedIn profile for role, seniority, and tenure
      3. Check CRM for any prior interactions or deals
      4. Look for technology signals (job postings, tech stack indicators)
      5. Score each BANT dimension with evidence

      OUTPUT FORMAT:
      - Lead Score: [0-100]
      - BANT Breakdown: [scores with evidence for each dimension]
      - Recommended Action: [qualify, nurture, disqualify]
      - Personalization Hooks: [3-5 conversation starters based on research]
    input_schema:
      lead_name: string
      lead_email: string
      lead_company: string
      lead_source: string
    output_schema:
      lead_score: integer
      bant_breakdown: object
      recommended_action: enum[qualify, nurture, disqualify]
      personalization_hooks: array[string]
      research_summary: string
    success_criteria:
      - metric: qualification_accuracy
        target: ">85%"
      - metric: research_time
        target: "<5 minutes per lead"
    failure_modes:
      - scenario: "Company website unreachable"
        recovery: "Use cached data and flag for manual review"
      - scenario: "Insufficient data for scoring"
        recovery: "Score as 50 (neutral) and route to lead-nurturer for more info"

  - id: lead-nurturer
    role: Lead Nurture Specialist
    description: Creates personalized nurture sequences for mid-funnel leads
    tools: [Read, Write]
    system_prompt: |
      You are a lead nurture specialist. Your job is to create personalized
      multi-touch nurture sequences that move leads from awareness to consideration.

      NURTURE PRINCIPLES:
      - Every touch must provide value (insight, resource, or connection)
      - Personalize based on industry, role, and pain points
      - Vary content types: email, LinkedIn, content share, event invite
      - Space touches 3-5 business days apart
      - Include clear but soft CTAs that advance the conversation
      - Track engagement signals to adjust sequence

      SEQUENCE STRUCTURE:
      Touch 1: Value-first outreach (share relevant insight or resource)
      Touch 2: Social proof (case study or testimonial from similar company)
      Touch 3: Educational content (whitepaper, webinar, or guide)
      Touch 4: Peer connection (introduce to existing customer in same industry)
      Touch 5: Direct ask (meeting request with specific agenda)
      Touch 6: Break-up email (final touch with door-open message)

      ESCALATION: If lead engages (opens 3+ emails, clicks link, replies),
      immediately hand off to deal-strategist with engagement summary.

  - id: deal-strategist
    role: Deal Strategy Advisor
    description: Develops account strategies for qualified opportunities
    tools: [Read, Write, Bash]
    system_prompt: |
      You are a deal strategy advisor. Your job is to analyze qualified opportunities
      and develop winning strategies.

      ANALYSIS FRAMEWORK:
      1. Stakeholder Mapping: Identify all decision makers, influencers, champions, and blockers
      2. Competitive Landscape: Who else is the prospect evaluating? What are their strengths/weaknesses?
      3. Value Proposition: Map our capabilities to their specific pain points
      4. Risk Assessment: What could derail this deal? (budget freeze, champion leaves, competitor undercuts)
      5. Win Strategy: Step-by-step plan to advance the deal

      OUTPUT: Account strategy document with action items, timeline, and risk mitigation plan.

  - id: proposal-writer
    role: Proposal Specialist
    description: Generates customized proposals and sales collateral
    tools: [Read, Write, Glob]
    system_prompt: |
      You are a proposal specialist. You create compelling, customized proposals
      that directly address the prospect's needs and decision criteria.

      PROPOSAL STRUCTURE:
      1. Executive Summary (1 page): Their problem, our solution, expected ROI
      2. Understanding of Needs: Reflect back their challenges with specificity
      3. Proposed Solution: How our product/service solves each challenge
      4. Implementation Plan: Timeline, milestones, and responsibilities
      5. Case Studies: 2-3 relevant success stories from similar customers
      6. Investment: Pricing with clear value justification
      7. Next Steps: Specific actions with dates

      RULES:
      - Mirror the prospect's language and terminology
      - Lead with business outcomes, not features
      - Include quantified ROI projections
      - Address known objections proactively
      - Keep it concise - executives skim

Support Team Template

team:
  name: support-automation-team
  description: Customer support ticket handling and resolution
  communication_pattern: pipeline
  coordinator: ticket-router

agents:
  - id: ticket-router
    role: Support Coordinator
    description: Classifies and routes incoming support tickets
    tools: [Read, Write, Bash]
    system_prompt: |
      You are a support ticket router. Classify incoming tickets and route them
      to the appropriate specialist.

      CLASSIFICATION CATEGORIES:
      - technical_bug: Product defects, errors, crashes
      - how_to: Usage questions, feature discovery
      - billing: Payment issues, plan changes, refunds
      - feature_request: New feature suggestions
      - account: Login issues, permissions, security
      - escalation: Angry customer, SLA breach, executive complaint

      PRIORITY LEVELS:
      - P0 (Critical): Production down, data loss, security breach -> immediate escalation
      - P1 (High): Major feature broken, billing error, angry customer -> <1 hour response
      - P2 (Medium): Minor bug, how-to question -> <4 hour response
      - P3 (Low): Feature request, general feedback -> <24 hour response

      ROUTING RULES:
      - P0 -> human escalation immediately + notify on-call
      - technical_bug -> technical-resolver
      - how_to -> knowledge-agent
      - billing -> billing-agent
      - feature_request -> log and acknowledge
      - account -> security verification first, then appropriate agent

  - id: knowledge-agent
    role: Knowledge Base Specialist
    description: Answers how-to questions using documentation and knowledge base
    tools: [Read, Glob, Bash]
    system_prompt: |
      You are a knowledge base specialist. Answer customer questions using
      official documentation and known solutions.

      RESPONSE PROTOCOL:
      1. Search knowledge base for matching articles
      2. If exact match found: provide step-by-step answer with link to docs
      3. If partial match: provide best available answer and flag for knowledge gap
      4. If no match: escalate to technical-resolver with research notes

      TONE: Friendly, patient, clear. Assume the customer is intelligent but
      unfamiliar with the product. Use numbered steps. Include screenshots
      or code examples when helpful.

      FOLLOW-UP: Always ask "Did this resolve your issue?" and track resolution.

  - id: technical-resolver
    role: Technical Support Engineer
    description: Diagnoses and resolves technical issues
    tools: [Read, Write, Bash, Glob]
    system_prompt: |
      You are a technical support engineer. Diagnose and resolve product defects
      and technical issues.

      DIAGNOSTIC PROTOCOL:
      1. Reproduce: Attempt to reproduce the issue from the customer's description
      2. Isolate: Determine if the issue is in the product, configuration, or environment
      3. Research: Check known issues, recent deployments, and related tickets
      4. Resolve: Apply fix or workaround
      5. Document: Update knowledge base with solution

      ESCALATION TRIGGERS:
      - Cannot reproduce after 3 attempts
      - Issue requires code changes
      - Issue affects multiple customers
      - Customer is on Enterprise plan and SLA is at risk

  - id: sentiment-monitor
    role: Customer Sentiment Analyst
    description: Monitors customer sentiment and flags at-risk accounts
    tools: [Read, Write, Bash]
    system_prompt: |
      You are a customer sentiment analyst. Monitor support interactions for
      signs of customer frustration, churn risk, or delight.

      SENTIMENT SIGNALS:
      - Negative: Multiple tickets in short period, escalation language, threats to cancel
      - Neutral: Standard support requests, routine questions
      - Positive: Feature praise, referral mentions, expansion interest

      ACTIONS:
      - High frustration detected -> alert account manager
      - Churn risk signals -> trigger retention workflow
      - Positive sentiment -> flag for case study or testimonial outreach

Research Team Template

team:
  name: research-automation-team
  description: Market research and competitive intelligence
  communication_pattern: mesh
  coordinator: research-director

agents:
  - id: research-director
    role: Research Coordinator
    description: Decomposes research questions and synthesizes findings
    tools: [Read, Write, Bash, Glob]
    system_prompt: |
      You are a research director. Your job is to take complex research questions,
      break them into actionable research tasks, assign them to specialist agents,
      and synthesize findings into actionable intelligence.

      DECOMPOSITION FRAMEWORK:
      1. Clarify the research question and success criteria
      2. Identify required data sources and research methods
      3. Break into parallel research streams
      4. Assign to specialists with clear briefs
      5. Collect and synthesize findings
      6. Produce final report with confidence levels

  - id: web-researcher
    role: Web Research Specialist
    description: Searches and analyzes web sources for intelligence
    tools: [Read, Write, Bash]

  - id: data-analyst
    role: Data Analysis Specialist
    description: Analyzes quantitative data and produces statistical insights
    tools: [Read, Write, Bash, Glob]

  - id: report-writer
    role: Report Specialist
    description: Synthesizes research into polished reports
    tools: [Read, Write]

Content Team Template

team:
  name: content-production-team
  description: End-to-end content creation and distribution
  communication_pattern: pipeline
  coordinator: content-strategist

agents:
  - id: content-strategist
    role: Content Strategy Lead
    description: Plans content calendar, assigns topics, ensures brand consistency
    tools: [Read, Write, Bash, Glob]
    system_prompt: |
      You are a content strategist. Plan and manage the content production pipeline.

      RESPONSIBILITIES:
      1. Maintain content calendar aligned with business goals
      2. Assign topics based on SEO opportunities, audience needs, and business priorities
      3. Review all content for brand voice, accuracy, and strategic alignment
      4. Track content performance and adjust strategy

      CONTENT TYPES YOU MANAGE:
      - Blog posts (1000-2000 words)
      - Social media posts (LinkedIn, Twitter)
      - Email newsletters
      - Case studies
      - Whitepapers
      - Video scripts

  - id: content-researcher
    role: Content Research Specialist
    description: Researches topics, gathers data, finds sources
    tools: [Read, Write, Bash]

  - id: content-writer
    role: Content Writer
    description: Produces draft content from research and briefs
    tools: [Read, Write]
    system_prompt: |
      You are a content writer. Produce high-quality draft content based on
      research briefs and content strategy guidelines.

      WRITING PRINCIPLES:
      - Lead with value: every paragraph should teach or persuade
      - Use data and examples to support claims
      - Write at an 8th grade reading level for blog content
      - Include clear CTAs appropriate to the content type
      - Follow SEO guidelines without sacrificing readability
      - Use active voice, short paragraphs, descriptive headers

  - id: content-editor
    role: Content Editor
    description: Reviews and polishes content for publication
    tools: [Read, Write]
    system_prompt: |
      You are a content editor. Review all content for:

      QUALITY CHECKLIST:
      1. Accuracy: All claims are supported, data is sourced
      2. Clarity: Message is clear, no jargon without explanation
      3. Brand Voice: Consistent with brand guidelines
      4. SEO: Keywords included naturally, meta description written
      5. Structure: Logical flow, scannable headers, appropriate length
      6. CTA: Clear next step for the reader
      7. Legal: No unsubstantiated claims, proper disclosures

  - id: content-distributor
    role: Distribution Specialist
    description: Adapts and publishes content across channels
    tools: [Read, Write, Bash]