livekit-prompt-builder

What this skill does

# LiveKit Voice Agent Prompt Builder

Create production-ready prompts for LiveKit voice agents that work seamlessly with text-to-speech systems.

## Quick Start

For most use cases, follow this simple workflow:

1. **Choose a template** from `assets/templates/` that matches your use case
2. **Customize** the template with your specific information
3. **Validate** using `scripts/validate_prompt.py`
4. **Test** with your LiveKit agent
5. **Refine** based on real conversations

## Workflow

### Step 1: Determine Your Agent Type

Select the template that best matches your needs:

**General Purpose:**

- **Basic Assistant** (`basic-assistant.txt`) - Simple conversational agent
  - Use for: General chat, demos, minimal functionality
  - Complexity: Low
  - Tools: Optional

- **Tool-Enabled Agent** (`tool-enabled-agent.txt`) - Agent with function calling
  - Use for: Weather, search, data lookup, single-domain assistants
  - Complexity: Medium
  - Tools: 1-5 tools

- **Customer Service** (`customer-service.txt`) - Support agent with escalation
  - Use for: Help desks, support lines, troubleshooting
  - Complexity: Medium
  - Tools: Lookup, search, escalation

- **Specialist Agent** (`specialist-agent.txt`) - Task-specific agent (reservations, orders, etc.)
  - Use for: Booking systems, order taking, appointments
  - Complexity: Medium-High
  - Tools: Action tools (create, update)

- **Multi-Agent Coordinator** (`multi-agent-coordinator.txt`) - Routes to other agents
  - Use for: Main entry point in multi-agent systems
  - Complexity: Medium
  - Tools: Transfer/handoff tools

**Industry-Specific:**

- **Front Desk Receptionist** (`front-desk-receptionist.txt`) - Professional call routing
  - Use for: Office reception, call centers, front desk operations
  - Complexity: Low-Medium
  - Tools: Transfer, routing, message taking

- **Debt Collection** (`debt-collection-agent.txt`) - Compliant recovery agent
  - Use for: Debt recovery, collections, payment arrangements
  - Complexity: High
  - Tools: Payment processing, sentiment analysis
  - Note: Includes FDCPA/TCPA/CFPB compliance requirements

### Step 2: Customize Your Template

Open your selected template and fill in the placeholders:

**Example - Customizing `basic-assistant.txt`:**

Template:
```
You are [NAME], a friendly voice assistant. You are [TRAIT_1] and [TRAIT_2], with [TRAIT_3].
```

Customized:
```
You are Casey, a friendly voice assistant. You are helpful and patient, with a sense of humor.
```

**Key customization areas:**
- Identity (name, role, personality)
- Domain context (business info, hours, policies)
- Tool descriptions (when and how to use each tool)
- Workflow steps (information collection sequence)
- Boundaries (what agent can't do)

### Step 3: Apply Voice Optimization

Ensure your prompt includes these critical voice optimization rules:

**Required elements:**

```
Keep your responses brief - 1-3 sentences. Respond in plain text only - no emojis, asterisks, markdown, or special formatting. Ask one question at a time.
```

**For agents that mention numbers, prices, or contact info:**

```
Spell out numbers ("fifteen" not "15"). Spell phone numbers digit by digit ("5-5-5, 1-2-3-4"). For URLs, omit "https://" and say "dot" for periods.
```

**For agents with tools:**

```
If a tool call fails, explain the issue simply and suggest a fallback. Summarize tool results in conversational language - don't recite technical IDs or raw data.
```

### Step 4: Validate Your Prompt

Run the validation script to check for common issues:

```bash
python scripts/validate_prompt.py your_prompt.txt
```

The validator checks for:
- Missing identity statement
- Lack of voice optimization rules
- TTS antipatterns (emojis, markdown, special characters)
- Excessive length (>500 words)
- Missing tool error handling
- Number formatting guidance

**Fix any errors** before deploying your prompt.

### Step 5: Test with LiveKit

Deploy your prompt in a LiveKit agent and test with real conversations:

**Test scenarios:**
1. **Happy path** - User provides information smoothly
2. **Interruptions** - User changes topic or interrupts
3. **Tool failures** - Simulate tool errors
4. **Edge cases** - Ambiguous requests, out-of-scope questions
5. **Voice quality** - Listen to TTS output for formatting issues

### Step 6: Refine

Based on testing, refine your prompt:

**Common refinements:**
- Add specific guidance for observed failure modes
- Adjust tone or personality descriptors
- Add examples for complex tool usage
- Tighten response length constraints if agent is too verbose
- Add boundaries for out-of-scope requests

## Key Concepts

### Voice-First Design

Voice agents differ from text chatbots:

**Critical differences:**
- No visual formatting (users can't see bold, lists, etc.)
- Limited user patience (long responses cause frustration)
- TTS limitations (special characters cause problems)
- No "scroll back" (users can't review previous responses)

**Implications for prompts:**
- Always specify plain text only
- Enforce brevity (1-3 sentences typical)
- Spell out numbers and abbreviations
- Ask one question at a time
- Avoid complex structures (lists, tables)

### The Three Essential Sections

Every voice agent prompt should have:

1. **Identity** - "You are [name/role]. You are [personality]."
2. **Voice Rules** - Plain text, brief responses, number formatting
3. **Core Functionality** - What the agent does, tools it uses, workflows it follows

Additional sections (domain context, guardrails, handoffs) add as needed.

### Template vs. Custom Prompts

**Use templates when:**
- Starting a new agent
- Following common patterns (support, booking, etc.)
- Want quick setup with best practices

**Write custom when:**
- Unique use case not covered by templates
- Very specialized domain
- Complex multi-step workflows

Even with custom prompts, reference the templates for voice optimization patterns.

## Progressive Disclosure: When to Load References

Load reference documentation based on your specific needs:

**For all users:**
- Start with templates and this SKILL.md

**Load prompt-components.md when:**
- Building complex prompts from scratch
- Need detailed guidance on specific sections
- Want to understand the "why" behind best practices
- Customizing beyond simple template fill-in

**Load voice-optimization.md when:**
- Encountering TTS formatting issues
- Agent responses sound awkward or unnatural
- Need deep understanding of voice-specific constraints
- Working with multiple TTS providers
- Debugging number, URL, or email pronunciation

**Load tool-integration.md when:**
- Integrating function calling/tools
- Building multi-agent systems with handoffs
- Need patterns for error handling or parameter collection
- Tools aren't being used correctly
- Working with RAG or external data sources

**Load examples.md when:**
- Want to see complete, real-world prompts
- Need inspiration for similar use cases
- Comparing complexity levels
- Learning from production patterns

**Load industry-best-practices.md when:**
- Building agents for regulated industries (healthcare, banking, debt collection)
- Need compliance guidance (HIPAA, FDCPA, TCPA, etc.)
- Working on industry-specific use cases (front desk, customer service, sales)
- Require specialized tone and approach patterns
- Need security or privacy considerations

**Load iterative-improvement.md when:**
- Improving existing prompts based on feedback
- Analyzing test results and conversation data
- Conducting A/B tests on prompt variations
- Establishing metrics and measurement frameworks
- Need systematic approach to prompt refinement
- Want to preserve prompt structure while making improvements

**Strategy:** Start minimal (templates + SKILL.md). Load references only when you hit specific challenges or need deeper guidance.

## Multi-Agent Systems

For systems with multiple agents, design each agent separately:

**Pattern:**

1. **Coordinator/Greeter** - Uses `multi-agent