--- name: build-agent description: > End-to-end voice agent builder for ModelGuide. Use this skill whenever someone wants to build, create, or set up a voice agent or voice bot from scratch — regardless of industry (dental, HVAC, retail, restaurant, gym, real estate, law firm, insurance, etc.). Trigger on "/build-agent" or phrases like "build a voice agent", "create a voice bot", "set up an agent", "automate our phone line / dispatch calls / inbound calls", "I need a voice agent for my [business]", "help me build an agent", or "I want to set up a new ModelGuide agent". Also trigger when someone says they are "starting from zero" or "starting fresh" on a new agent build. Guides through 8 stages: prereq check, interview, local input collection, YAML generation + provisioning, eval import, simulation feedback loop, autonomous tightening, and local LiveKit validation. Supports end-to-end provisioning for Medusa, Zendesk, and conversation-only agents. For other APIs, dispatches `@mg-connector` in parallel while the rest of the build continues — the build only pauses at `mg setup` if the connector isn't ready yet. Produces a validated voice agent in 2-3 hours. Resumes from the last completed stage if `.modelguide/STATE.md` exists. --- # Build-Agent Skill End-to-end voice agent wizard. From business idea to validated local voice agent. ## Resumption Before the interview, check for existing progress: ```bash test -f .modelguide/STATE.md && cat .modelguide/STATE.md ``` If `currentStage` exists, skip completed stages and resume. Special case: if `connectorStatus: pending` (or legacy `currentStage: connector`) in STATE.md, check `.modelguide/CONNECTOR_HANDOFF.md` before continuing: - `status: requested` → connector is still building; continue from the last completed stage (skip `mg setup` — go to Stage [2b] if Stage [1] is done, else Stage [1]) and note the pause point - `status: blocked` → show the blocker message, stop, and ask for help resolving it - `status: completed` → sync `catalogSlug`, `connectorSlug`, `toolSlugs` from handoff into D-07, update `connectorStatus: done`. Then resume from whichever stage is next: - If `agentId` is empty (Stage [1] hasn't run): resume at Stage [1] — collect admin email, connector secrets, generate `.env.example` - If `agentId` is populated (Stage [1] done): generate `connectors.yaml` and tool blocks, then run `mg setup` (Stage [2c]) If STATE.md doesn't exist, start from [pre]. --- ## Extend: Add a SOP to an Existing Agent If you already have a built agent (`currentStage: done` or any stage ≥ 3) and want to add a new use case without rebuilding, use this path instead of the full wizard. Trigger phrases: "add a use case", "add a SOP", "teach the agent to handle X", "new scenario for the agent". ### Steps 1. **Read context** — load `CONTEXT.md` and existing `.modelguide/sops.yaml` to understand the current agent, connector, and SOP slugs already registered. 2. **Interview for the new SOP** (2-3 questions): - "Describe the new scenario in one sentence — what does the customer say and what should the agent do?" - "Does this require a new tool call, or can it use the existing connector?" - If new tool: check `CONNECTOR_HANDOFF.md` or ask which tool slug to use. 3. **Generate the new SOP** — append to `.modelguide/sops.yaml` (do not overwrite existing SOPs): - Follow the same structure as existing SOPs (status: active, agents: [agentSlug], steps with tool: block if applicable) - Name the SOP after the customer's goal, not the agent action 4. **Generate new eval cases** — append to `.modelguide/evals.yaml`: - At minimum: happy path, missing-info, guardrail trigger for the new SOP 5. **Import and recompile**: ```bash cd modelguide-api && bun run src/cli/mg.ts import-sops --org {{orgSlug}} ../.modelguide/sops.yaml cd modelguide-api && bun run src/cli/mg.ts import-evals --org {{orgSlug}} ../.modelguide/evals.yaml cd modelguide-api && bun run src/cli/mg.ts compile-agents --org {{orgSlug}} ``` 6. **Run evals for just the new SOP**: ```bash cd modelguide-api && bun run src/cli/mg.ts run-evals --org {{orgSlug}} --agent {{agentSlug}} --suite {{newSopSlug}} ``` Apply targeted fixes if pass rate < 80%, same categorization as Stage [5]. Once evals pass, push to the live agent (ElevenLabs only): ```bash cd modelguide-api && bun run src/cli/mg.ts sync-agent --org {{orgSlug}} --agent {{agentSlug}} ``` 7. **Generate simulation script** for the new SOP (happy path + guardrail trigger) and show it so you can test it live. --- ## State Files **`.modelguide/STATE.md`** — stage tracker: ``` currentStage: pre | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | done mode: auto-pilot | supervised platform: livekit | elevenlabs orgSlug: agentSlug: agentId: connectorType: catalog | none | custom catalogSlug: | (none) | (pending) connectorSlug: | (none) | (pending) connectorStatus: done | pending | (none) evalIteration: 0 lastEvalScore: (none) ``` **`.modelguide/CONTEXT.md`** — interview answers and locked decisions (D-01…D-NN). **`.modelguide/CONNECTOR_HANDOFF.md`** — only for custom APIs: ```yaml status: requested | completed | blocked serviceName: serviceSlug: requestedConnectorSlug: _ authModel: baseUrl: operations: - catalogSlug: | (pending) connectorSlug: | (pending) toolSlugs: - configFields: - name: description: required: true secretFields: - field: name: type: api_key changedFiles: - verification: blocker: ``` Slug roles: - `serviceSlug` — interview-time slug for the external service - `requestedConnectorSlug` — proposed org connector instance slug - `catalogSlug` — final connector type slug in the global catalog - `connectorSlug` — final org connector instance slug used in `agents.yaml`, `sops.yaml`, and runtime MCP tool names Update `currentStage` in STATE.md at the start and end of each stage. --- ## Stage [pre]: Prerequisite Check Check Docker, Bun, and Python 3.11+: ```bash docker info > /dev/null 2>&1 && echo "Docker: OK" || echo "Docker: MISSING" bun --version > /dev/null 2>&1 && echo "Bun: OK" || echo "Bun: MISSING" python3 --version 2>&1 | grep -E "3\.(1[1-9]|[2-9][0-9])" && echo "Python: OK" || echo "Python: MISSING or < 3.11" ``` **ModelGuide repo check** — verify the repo is set up: ```bash test -f modelguide-api/.env && echo "API env: OK" || echo "API env: MISSING — run: cp modelguide-api/.env.example modelguide-api/.env and fill in required vars" test -d modelguide-api/node_modules && echo "API deps: OK" || echo "API deps: MISSING — run: cd modelguide-api && bun install" ``` If `modelguide-api/.env` is missing, ask the person to copy the example and fill in `DATABASE_URL`, `JWT_SECRET`, and other required vars before continuing. Format the results as a status block: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Prerequisites ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✓ Docker ✗ Bun missing → curl -fsSL https://bun.sh/install | bash ✓ Python ✓ API env configured ✓ API deps installed ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Use ✓ for passing items (show the version or "configured"), ✗ for missing items with the install command inline. Show all issues at once — never stop after the first. Do not abort. - Docker: https://www.docker.com/products/docker-desktop/ - Bun: `curl -fsSL https://bun.sh/install | bash` - Python 3.11+: `brew install python@3.11` (macOS) or https://python.org/downloads If all pass, end with: `All good — starting Stage [0].` If any fail, end with: `Fix the items marked ✗ above and run me again.` Write STATE.md with `currentStage: 0`. --- ## Stage [0]: Define / Interview Gather all decisions needed for agent configuration. Write answers to CONTEXT.md as locked decisions D-01…D-NN. Open each question with a progress banner so the person always knows where they are: ``` ━━━ Q1 of 7 ━━━━━━━━━━━━━━━━━━━━━━━ ``` After each answer is locked, confirm it on one line: `✓ D-01 Mode: auto-pilot` ### Q1 — Mode "Would you like **auto-pilot** (I run everything) or **supervised** (I pause after each stage)?" Default: auto-pilot. Record as D-01. ### Q2 — Business context "Briefly describe your business and who the agent will serve (1-3 sentences)." Derive `orgSlug` from the business name (lowercase, hyphens, max 20 chars). Record as D-02. ### → Domain research (after Q2, before Q3) Once you know the business type, research the domain to make the rest of the interview faster and the agent smarter: 1. Search: "[business type] customer service voice agent common scenarios" 2. Search: "[business type] compliance requirements" (for regulated industries: healthcare, finance, legal, insurance) 3. Search: "[business type] API integrations" if the business type suggests a specific system (scheduling, POS, EHR, CRM) Use findings to: - Propose 3 realistic starter conversations for Q3 (builder confirms or customizes) - Pre-populate domain-specific guardrail suggestions for Q6 - Identify if a catalog connector already covers this domain (e.g., appointment booking → custom; retail → Medusa; support → Zendesk) - Flag regulated-industry requirements early (e.g., HIPAA for healthcare, PCI for payments) Keep the research step invisible — don't list search results at the builder. Just use the knowledge to give sharper suggestions. ### Q3 — Example conversations "Here are 3 typical scenarios for [business type]. Confirm, customize, or replace:" ``` 1. [suggested customer phrase] → [suggested agent action] 2. ... 3. ... ``` Push for specific dialogue if vague. These become SOP steps and eval test cases directly. Record as part of D-02. ### Q4 — Tools / API "What systems does the agent need to call?" Options: - **A) Medusa** — built-in e-commerce (products, cart, orders) - **B) Zendesk** — built-in helpdesk (tickets, knowledge base) - **C) None** — conversation only - **D) Mocked demo** — the agent needs named tools but no real backend (sales demo, POC, dry-run) - **E) Something else** (e.g. Shopify or a custom REST API) Supported end-to-end provisioning without connector-building work: **Medusa**, **Zendesk**, **conversation-only**, **mocked demo**. **D — Mocked demo (ADR-013):** - Use when the business has no real API to integrate with (yet) OR the build is explicitly a demo/sales asset. Tool responses are static fixtures authored directly in `connectors.yaml` with `isMocked: true`. - No `mg-connector` dispatch; no background subagent. The `connectors.yaml` + `mg setup` path handles everything. - Capture in D-07: `connectorType: mocked`, `catalogSlug: {{orgSlug}}_{{serviceSlug}}` (same as connector slug), `connectorSlug: {{orgSlug}}_{{serviceSlug}}`, plus the tool list and a fixture sketch for each. - At Stage [3] YAML generation, emit `isMocked: true` + inline `tools: [{ name, input_schema, mock_response }]`. Edits to `mock_response` flow through on re-seed without delete-then-reimport. **E — Something else (real custom connector):** - Capture the service name, auth model, base URL, and concrete operations in D-07 - Derive `serviceSlug` and requested org connector slug `{{orgSlug}}_{{serviceSlug}}` - Write `.modelguide/CONNECTOR_HANDOFF.md` with `status: requested`, the captured service details, and the requested operations - Tell the user: ``` Your API isn't one of the built-in connectors, so I'm kicking off a background build for it. I've saved all the details — your API URL, authentication, and the endpoints — to a handoff file. A background process is building the connector automatically. You don't need to do anything. We keep going from here — the only pause would be during provisioning if the connector isn't ready yet. ``` - Spawn a **background subagent** using the Agent tool: - `run_in_background: true` - Task prompt: "Invoke the `mg-connector` skill (use the Skill tool with `skill: 'mg-connector'`). The handoff spec is already written to `.modelguide/CONNECTOR_HANDOFF.md` — use it as your starting context. Build the connector and ensure the file reaches `status: completed` when done." - Do NOT wait for it to finish - Write STATE.md with `currentStage: 1`, `connectorStatus: pending` - Continue immediately to Stage [1] — do NOT stop and wait Record D-07 with both connector identifiers: - Medusa → `connectorType: catalog`, `catalogSlug: medusa`, `connectorSlug: {{orgSlug}}_store` - Zendesk → `connectorType: catalog`, `catalogSlug: zendesk`, `connectorSlug: {{orgSlug}}_support` - None → `connectorType: none`, `catalogSlug: (none)`, `connectorSlug: (none)` - Mocked demo → `connectorType: mocked`, `catalogSlug: {{orgSlug}}_{{serviceSlug}}`, `connectorSlug: {{orgSlug}}_{{serviceSlug}}` - Custom → `connectorType: custom`, `catalogSlug: (pending)`, `connectorSlug: {{orgSlug}}_{{serviceSlug}}` Also record the tool slugs needed by the agent. ### Q5 — Persona "What's the agent's name, and how should it sound?" Options: Friendly & conversational / Professional & concise / Domain expert / Custom. Claude infers a default from the business (retail → friendly, B2B → professional, healthcare → calm & clear). Derive: - `agentFirstName` — the human name (e.g. "Aria", "Max") - `agentSlug` — always `{{orgSlug}}-voice-agent` (e.g. `glowskin-voice-agent`, `coolair-voice-agent`) - `AgentClassName` — PascalCase of the first name + "Agent" (e.g. `AriaAgent`, `MaxAgent`) - `agentDescription` — a 1-2 sentence persona statement written **as the agent's role identity**, used verbatim as the "Role & Objective" opening of the compiled system prompt. This is NOT an internal dev note. Write it as if addressing the LLM directly (e.g. "You are a voice assistant for GlowSkin handling skincare product questions and order support. Answer only in English."). Include the language instruction if non-English. Record name/slug/class as D-03/D-04, style as D-05. ### Q6 — Guardrails Guardrails come in two flavors — present both clearly: **Focus guardrails** keep the agent on-topic and concise. Without them, agents drift into long explanations, offer unsolicited advice, or handle requests outside their scope. They matter as much as safety rules for voice — nobody wants a two-minute monologue when they asked about their order. **Safety guardrails** prevent liability, compliance violations, and escalation failures. "Here are guardrails I'd suggest based on your business. I've split them into focus rules and safety rules — add, remove, or customize:" **Focus (pre-populate from domain research + business context):** - Only answer questions related to [inferred scope from Q2/Q3] — redirect anything else politely - Keep responses to 1-3 sentences unless the customer explicitly asks for more detail - Do not volunteer information the customer didn't ask for - If unsure, say so briefly and offer to connect with a human — don't speculate - Custom focus rule **Safety (pre-populate from domain research):** - Never quote or estimate delivery/arrival times - Never execute financial transactions without human confirmation - Never share another customer's data - Always escalate complaints or angry customers - Never give professional advice (medical, legal, financial) — redirect to a human - Custom safety rule Require at least 2 from each category (minimum 4 total). Claude proposes sensible defaults from business context and domain research. Record as D-08. ### Q7 — Platform & stack confirmation First, ask which platform to deploy on: ``` Which platform should the agent run on? A) ElevenLabs Conversational AI — fully managed, no code, deploy in minutes B) LiveKit Agents — self-hosted Python agent, full control Default: A (ElevenLabs), unless the builder has a reason to self-host. ``` **If ElevenLabs (A):** ``` Platform: ElevenLabs Conversational AI LLM: GPT-4o-mini — fast, cost-effective (change if needed) Press Enter to confirm, or tell me what to change. ``` Ask for the LLM model if they want a different one. Valid options: any model from the ElevenLabs supported list (gpt-4o, gpt-4o-mini, gpt-4.1, claude-sonnet-4-5, claude-haiku-4-5, gemini-2.5-flash, etc.). Record model as `llmModel` in D-06. **If LiveKit (B):** ``` LLM: GPT-4.1-mini (OpenAI) — fast, cost-effective for tool-calling STT: Deepgram Nova-3 — best accuracy for voice TTS: ElevenLabs Flash v2.5 — natural voice quality Framework: LiveKit Agents — local dev support, no cloud needed Press Enter to confirm, or tell me what to change. ``` Record platform and full stack as D-06. Write STATE.md (`currentStage: 1`) and CONTEXT.md with all decisions. For custom connectors, also write `connectorStatus: pending`. After writing the files, show a locked decisions summary instead of dumping CONTEXT.md raw: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Stage [0] — decisions locked ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Mode auto-pilot Business · Agent ·