vox-best-practice_skill

Overview

This skill captures vox.ai development best practices for designing, authoring, diagnosing, and refactoring voice-agent system prompts and for integrating with the vox MCP server. It delivers templates, checklists, failure-mode diagnosis, minimal-impact refactoring rules, and guidance for MCP tool and built-in action management. The goal is fast, reliable single-prompt Korean voice agents and safe, testable MCP integrations with common assistant engines.

How this skill works

I inspect existing system prompts, identify failure modes, and produce precise change requests plus a minimal-impact revised prompt that preserves required sections, variables, and tool contracts. I also outline MCP integration steps (streamable HTTP, OAuth/API token usage, client-specific settings), tool registration patterns, and safe deployment controls so updates occur only when you approve. Built-in and custom tool behaviors (end_call, transfer_call, transfer_agent, send_sms, API tool hooks) are summarized for predictable runtime behavior.

When to use it

• Creating a new Korean single-prompt voice agent for production or testing
• Refactoring an existing system prompt after observed failures or UX regressions
• Diagnosing intermittent runtime failures tied to variables, fillers, or tool calls
• Preparing MCP integration with an assistant engine (ChatGPT, Claude, Cursor, Codex, etc.)
• Onboarding a new engineer to vox prompt and tool-management conventions

Best practices

• Open at least one referenced policy/template before making edits; don’t guess platform facts
• Prioritize factual accuracy and tool-backed evidence over speculative behavior
• Apply minimal-change refactoring: preserve required sections, variables, and tool contracts
• Include failure_modes and explicit change_requests in any diagnosis output
• Gate live MCP updates: perform changes only when the user explicitly requests apply/update

Example use cases

• Run a diagnosis on a Korean voice agent that often cuts off callers and get explicit change_requests
• Refactor a noisy system prompt to reduce filler tokens while keeping the same variable API
• Prepare MCP tool manifests for built-in actions and a custom API lookup tool before staging
• Generate a test vs production checklist for prompt variations and model-specific settings
• Create a tightly scoped revision that fixes one failure mode without altering other behaviors