Skip to main content
skill CX Codex

vapi-prompt-builder — Claude Code skill: setup

vapi-prompt-builder is a Claude Code skill that creates, refines, and audits Vapi system prompts for voice agents and Squads, including call flows, routing, and handoffs.

MIT 297 installs ★ 69 updated 2026-10-23

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add VapiAI/skills --skill vapi-prompt-builder -a claude-code
Open on GitHub

What vapi-prompt-builder does

vapi-prompt-builder turns a voice-agent brief into a Vapi system prompt, or reviews one that already exists. It separates creation, rewriting, and auditing tasks, then covers the call goal, caller intents, deployment shape, available tools, data collection, escalation, and handoff boundaries.

The skill can shape prompts for a single assistant or a Vapi Squad. Its workflow covers speaking style, response rules, guardrails, dynamic context, intent routing, tool behavior, recovery from errors, information intake, transfers, and call endings. Squad work also includes member roles, context passed during handoff, per-assistant tool limits, and routing test scenarios.

Internet access and VAPI_API_KEY are required. Without them, the skill cannot work with Vapi. It is available for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode.

What it helps with

  • draft a Vapi system prompt for a voice assistant
  • map call routing across a Vapi Squad
  • audit handoff and escalation rules
  • add tool-use and caller-intake instructions

Example prompts for the agent

  • Create a Vapi system prompt for an inbound call assistant and clarify the call objective first.
  • Audit this prompt for routing gaps, operator escalation, and failure recovery.
  • Design a Vapi Squad with an intake assistant that hands callers to a specialist.

How to install vapi-prompt-builder

1Skills CLI (Vercel)

npx skills add VapiAI/skills --skill vapi-prompt-builder -a claude-code

2Manually: put the files in place

~/.claude/skills/vapi-prompt-builder/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/vapi-prompt-builder/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about vapi-prompt-builder

How do I install vapi-prompt-builder in Claude Code?

Run npx skills add VapiAI/skills --skill vapi-prompt-builder -a claude-code, then check ~/.claude/skills/vapi-prompt-builder/SKILL.md.

What does vapi-prompt-builder do?

It creates, rewrites, and audits Vapi system prompts for voice agents. The workflow covers call behavior, tools, guardrails, data intake, escalation, and assistant handoffs.

What does the skill require?

It requires internet access and VAPI_API_KEY to work with Vapi.

Source text

SKILL.md · MIT
---
name: vapi-prompt-builder
description: Create, improve, or audit Vapi voice agent and Squad system prompts for production phone and web based voice agents. Use when the user wants help designing a Vapi assistant prompt, multi-assistant Squad prompt set, refining an existing prompt, creating prompt sections, building an intake or handoff workflow, improving tool-use instructions, adding guardrails, or optimizing voice-agent behavior for brevity, turn-taking, error handling, caller data collection, escalation, handoffs, and spoken formatting.
license: MIT
compatibility: Requires internet access and a Vapi API key (VAPI_API_KEY).
metadata:
  author: vapi
  version: "1.0"
---

# Vapi Prompt Builder

## Core Workflow

Use this skill to produce production-ready Vapi voice agent system prompts. Optimize for spoken interaction, low latency, explicit turn-taking, tool reliability, safe escalation, and predictable call outcomes.

Start by classifying the request:

- Create: Build a new Vapi system prompt from a business goal or agent concept.
- Improve: Rewrite an existing prompt while preserving intended behavior.
- Audit: Review an existing prompt and return findings, gaps, and recommended changes.

Then resolve deployment shape:

- Single assistant: one Vapi assistant owns the call flow.
- Squad: multiple specialized assistants hand off between each other.

If the request is ambiguous and the workflow may involve multiple specialized roles, routing, or handoffs, stop and ask: "Should this be designed as one Vapi assistant, or as a Vapi Squad with multiple assistants and handoffs?" Do not draft until this is resolved.

Read `references/squad-prompting.md` when the user mentions squads, Handoff Tools, handoffs between assistants or squads, silent handoffs, dynamic routing, router/triage assistants, specialist assistants, or a workflow that is too broad for one reliable prompt.

Before writing or preserving workflow details, run a capability-grounding pass. Verify that every claimed input, artifact, tool action, side effect, and example is possible through the actual call channel, runtime context, visible Vapi tools, or explicitly described backend behavior. Read `references/capability-grounding.md` when the prompt mentions files, uploads, attachments, documents, screenshots, browser/web actions, async jobs, integrations, or any action the phone caller cannot perform directly during the call.

Read `references/voice-prompt-patterns.md` when creating or substantially rewriting a prompt, or when the request involves voice style, examples, tool behavior, information collection, or call endings.

Run an identifier-hygiene pass before finalizing. Read `references/identifier-hygiene.md` when the prompt uses tool names, resource IDs, snake_case identifiers, placeholder names, or generic values such as `the_tool_name`.

Run a Vapi trust-boundary pass when the prompt, tools, or configuration mention authentication, caller identity, account IDs, permissions, secrets, secure values, verified values, static parameters, `function.parameters`, dynamic variables, `variableExtractionPlan`, tool aliases, handoff arguments, or sensitive tool responses. Read `references/vapi-security-trust.md` before recommending where those values belong.

Run a Vapi readiness pass before presenting an artifact as ready to build or configure. Read `references/vapi-readiness.md` when the output includes tools, structured outputs, dynamic variables, Squads, handoffs, pronunciation guidance, testing/evals, or configuration notes. Separate confirmed Vapi configuration from assumptions and missing deployment inputs.

## Intake

Ask the fewest questions needed to make a useful first draft. Prefer a complete draft with clear assumptions over a long upfront questionnaire.

Always collect or infer:

- Business or use case
- Deployment shape: single assistant or Squad
- Agent role and call objective
- Caller type and likely intents
- Success criteria
- Required workflows
- Handoff/routing boundaries when using a Squad
- Tools or actions the agent can use
- Tool schemas, structured outputs, and handoff destinations that are already known
- Model provider when Handoff Tool configuration patterns depend on it
- Which values are server-trusted, caller-spoken, tool-returned, LLM-derived, or security-sensitive
- How each required input becomes available to the agent or backend
- Human handoff or escalation rules
- Information the agent may collect
- Information the agent must not collect
- Tone, persona, and brand constraints

Read `references/intake-question-bank.md` when the request is vague, high-risk, or missing several essentials.

If the user provides an existing prompt, inspect it before asking questions. Ask only about missing facts, contradictions, tool behavior, compliance constraints, or ambiguous handoff rules.

## Prompt Sections

For a single assistant, generate or improve these sections unless the user asks for a narrower output:

1. Identity and purpose
2. Personality and speaking style
3. Response guidelines
4. Guardrails and safety behavior
5. Context and dynamic variables
6. Workflow and intent routing
7. Tool-use rules
8. Error handling and recovery
9. Smart information collection
10. Escalation, transfer, and call ending
11. Few-shot examples

For a Squad, generate or improve:

1. Squad purpose and member map
2. Entry assistant behavior
3. One focused system prompt per assistant
4. Handoff decision rules
5. Context handoff requirements
6. Tool boundaries per assistant
7. Shared guardrails
8. Per-assistant examples, including handoff examples
9. External test scenarios for routing and context preservation

For new prompts and substantial rewrites, include a compact `Examples` section inside the final Vapi system prompt unless the user explicitly asks to omit examples or there is a strong latency/token reason to keep the prompt minimal. Do not substitute external test scenarios for in-prompt examples.

Keep the final system prompt lean. Do not include tutorial prose, rationale, or markdown intended for humans unless the user requests it. Use section headers only if they improve maintainability.

Format the final prompt for fast model parsing, not as human-facing documentation:

- Prefer compact bullets, numbered workflow steps, and short imperative rules over dense paragraphs.
- Keep each rule to one idea; split multi-clause paragraphs into separate rules.
- Use paragraphs only for brief identity/personality context, and keep them to one to three short sentences.
- Do not confuse prompt formatting with spoken output: markdown is acceptable inside the system prompt, but instruct the agent not to speak markdown, bullets, or numbered lists to callers.
- Before finalizing, compress any section that reads like explanatory prose into operational instructions.

## Example Design

Design in-prompt examples as behavioral training data for the voice agent:

- Include at least three examples when the prompt covers a complete workflow: happy path, edge case, and error recovery.
- Cover each primary workflow when the agent has multiple high-value intents.
- Show realistic caller turns, concise assistant responses, tool calls, and tool outcomes.
- Include branching behavior for zero results, multiple results, invalid input, unclear speech, and tool failure when relevant.
- Ground every example in actual channel, runtime, tool, or backend capabilities.
- Use exact tool identifiers only in explicit `Tool Call:` lines or machine-facing configuration notes.
- Keep examples short enough to justify their latency cost.
- Use shape examples instead of repeating forbidden phrases, sensitive values, or unsupported artifacts.

Keep external test scenarios separate from the final prompt. Test scenarios are for the human/operator to validate the prompt; examples are instructions embedded in the prompt for the model to imitate.

## Voice Optimization

Before returning the final prompt, run a voice-agent pass:

- Keep caller-facing turns short, usually one or two sentences.
- Ask one question at a time.
- Avoid numbered lists, bullets, markdown, and visual formatting in agent responses.
- Convert dates, phone numbers, currency, times, and URLs to spoken-friendly forms.
- Replace tool IDs, resource slugs, snake_case identifiers, and placeholder names in prose with natural capability descriptions.
- Add explicit rules for interruptions, silence, unclear input, and tool failures.
- Distinguish light banter from hard off-topic requests.
- Calibrate human-feel controls to the use case: all production agents need natural pacing, repair, and warmth; only add disfluency, banter, or personal rapport when they fit the persona and risk profile.
- Remove channel-impossible behaviors unless a tool or backend contract makes them real.
- Prefer deterministic Vapi configuration over prompt instructions when reliability or security matters.

## Tool and Configuration Notes


- Tool descriptions should say when to call, when not to call, and required parameter formats.
- Prompt prose should describe tools by capability. Exact tool names belong only in tool-call examples, schemas, configuration notes, or Query Tool instructions where Vapi needs the system prompt to name the search tool.
- Do not invent deployable tool schemas, structured output schemas, enum values, server URLs, or handoff destinations. Ask for them or mark them as configuration needed.
- Transfer and end-call tools need explicit descriptions.
- Slow tools should use request-start messages to fill dead air.
- Pronunciation issues should use pronunciation dictionaries when available.
- Values that must be secure, verified, or impossible for the LLM to fake should use Vapi's server-side/static-parameter patterns, not prompt text or LLM-filled schemas.
- Tool responses should be short, structured, and limited to fields the model needs.

## Output Modes

For a new prompt, return:

- Brief assumptions, if any
- Final Vapi system prompt, or Squad prompt set when using a Squad
- Suggested Vapi configuration notes, if relevant
- Configuration needed or blocking questions, if deployment-critical details are missing
- External test scenarios, separate from the prompt

For an improved prompt, return:

- Final revised prompt, or revised Squad prompt set when using a Squad
- Important changes made
- Remaining questions or risks
- Configuration needed or blocking questions, if deployment-critical details are missing
- External test scenarios, separate from the prompt

For an audit, return:

- Findings ordered by severity
- Missing or weak prompt sections
- Vapi configuration concerns
- Concrete rewrite recommendations

Read `references/review-checklist.md` before finalizing an audit or substantial rewrite.

© vapi · MIT · VapiAI/skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set10

The whole set →
create-assistant create-assistant is a Claude Code skill for designing and validating Vapi voice assistants. It comes into play when building a phone or web agent and shaping its behavior. CX Codex +1 1,100installs create-phone-number create-phone-number — a skill for working with Vapi phone numbers through the public API: plan, provision, import, route, update and verify. Useful for connecting a voice assistant to calls. CX Codex +1 973installs setup-webhook setup-webhook — a skill for Claude Code that configures server URLs and webhooks to receive real-time events from Vapi. Use it when integrating Vapi into an application or building endpoints for call processing. CX Codex +1 968installs create-tool create-tool helps design, create, and attach tools to Vapi voice assistants through the public API. Supports native telephony controls, external integrations, declarative HTTP requests, and MCP servers. CX Codex +1 958installs create-squad create-squad decides whether a use case needs a multi-assistant Squad or a single assistant, then builds and verifies the Squad through the public Vapi API. CX Codex +1 910installs vapi-bootstrap-framework The vapi-bootstrap-framework skill scaffolds a Vapi voice-agent project from a ROUGH_DRAFT.md draft, generating a Bun + TypeScript structure, scenario registry, language stacks, and bootstrap script. CX Codex +1 314installs simulations Designs, builds, and executes conversation simulations for Vapi assistants and squads. It maps natural language requirements into realistic multi-turn voice or chat test suites. CX Codex +1 161installs create-structured-output create-structured-output is a Claude Code skill that defines a post-call extraction schema, attaches it to an assistant, and tests it on call recordings. CX Codex +1 154installs

Project sponsors

Companies that keep this analytics open