Build an agent

For questions about architecture, agent capabilities, routing behavior, or a requested feature that this skill does not answer, follow the docs MCP workflow before answering or implementing. For every new Voiceflow troubleshooting issue, consult it even when this skill suggests a fix. Include package/skill/stage context in why as described there. Reuse guidance for the same issue; consult it whenever unsure.

Read the operation contract. Resolve the user's intended project and environment from context; clarify only missing choices. A build request authorizes its necessary draft work, not publishing.

Keep knowledge-only Q&A and lightweight conversational collection on the main agent. Use a playbook for a distinct multi-step job needing its own tools or procedures; a workflow for deterministic branching or ordered actions. A series of questions alone does not require a workflow. Preserve valid details already supplied, including in the request that triggers routing, and ask only for what is missing. Avoid creating a playbook solely to wrap the KB.

Separate three instruction layers: global identity/style/guardrails, main-agent routing, and playbook job instructions. Playbooks inherit the global prompt; they do not see each other's private instructions.

Before building for a new business, read the actual global prompt and main-agent instructions, not just route metadata. CLI agent get needs both --include-prompt --include-instructions; MCP get needs includePrompt: true and includeInstructions: true. See identity and greeting fields. Replace sample identity and starter instructions in those fields, preserving unrelated settings. A business name in a playbook does not override the global identity. For an existing agent, retain its identity unless the task changes it.

Write the job's completion language around what its tools actually do. Collecting details or setting conversation variables is not submitting a request. A pure lookup or calculation does not book, reserve, send, or arrange human follow-up. Without an action that performs that effect, summarize what was collected and explain the next available step without promising it will happen automatically.

Build in dependency order: agent context, playbook, required resources, tool attachments, then instructions referencing those attached tools. Every attachment and routing description must say both WHAT it does and WHEN to use it.

Define who gives the final answer. A playbook that answers should stay active and wait for the next visitor message, returning to main only when a new message needs another capability. Do not unconditionally return immediately after an answer: main can repeat it or route the same request back. If main owns the answer, the playbook should hand off its result without also answering.

Read the complete existing routing registry before updating it: a supplied playbooks/workflows list replaces the list. Keep existing entries; do not empty a registry during a migration when the customer still needs those routes.

Use returned IDs. Confirm write results, unresolved references, tool descriptions, and routing before reporting the draft ready. Do not run tools that contact external services merely to inspect configuration.

When runtime testing is authorized, compile the draft and check a fresh greeting and the job's completion response. Ask whether the requested action actually happened; verify the answer against the executed tool's effect. See evaluations. Report configuration-only checks as such when runtime testing is outside scope.

Read prompting for instructions and wiring before attaching functions/API tools. Source: Playbooks.

---
name: voiceflow-build
description: Build or extend Voiceflow agents and playbooks, choose the right architecture, and connect routing and tools. Use after the user describes what they want to build.
license: MIT
---