Design Persona

Guide the user through designing and creating a simulation persona using the

coval

CLI. Follow the phases below in order, asking questions at each step.

$ARGUMENTS

contains a use case (e.g. "insurance_claims", "customer_support") or agent name, use it to skip or pre-fill relevant questions.

Phase 0: Preflight + Inventory

Step 1: Check authentication

bash

coval whoami

If not authenticated, guide the user:

bash

coval login

This prompts for an API key. Get one at https://app.coval.dev/settings (Organization > Manage > API Keys).

If the user doesn't have a Coval account, direct them to https://coval.dev to sign up.

Step 2: Inventory existing resources

Run these in parallel:

bash

coval personas list --format json
coval agents list --format json

Decision matrix:

Has personas → present them as a numbered list: "You already have these personas. Want to reuse one, duplicate and modify, or create new?"
No personas → proceed to Phase 1
If
```
$ARGUMENTS
```
matches an existing agent name, pre-select that agent for Phase 1

Phase 1: Agent Context

Ask: "Which agent will this persona test?"

If agents exist, present them as a numbered list to pick from
If no agents exist, say: "No agents found. You can still create a persona — just tell me what type of agent it will test (voice, outbound-voice, chat, sms, websocket)."

If the user selects an agent, fetch its details:

bash

coval agents get <agent_id> --format json

Extract from the response:

Agent type (
```
model_type
```
) — determines whether voice settings are relevant and conversation initiator direction
Agent name — for context in prompts
Agent prompt (if available) — helps craft a better persona

Key type mappings:

```
MODEL_TYPE_VOICE
```
/
```
MODEL_TYPE_OUTBOUND_VOICE
```
→ voice settings matter, conversation initiator depends on direction

MODEL_TYPE_CHAT

MODEL_TYPE_WEBSOCKET

MODEL_TYPE_API

MODEL_TYPE_ENDPOINT

→ voice settings are defaults only (won't affect simulation)

Phase 2: Use Case Detection

Ask: "What does your agent do?"

Present the options:

customer_support — Customer Support
scheduling_booking — Scheduling & Booking
sales — Sales
insurance_claims — Insurance Claims
healthcare_intake — Healthcare Intake
restaurant_orders — Restaurant Orders
debt_collection — Debt Collection
it_helpdesk — IT Helpdesk
other — Other (describe it)

Load

references/persona-templates.md

and select the template matching the chosen use case.

Present the template as a starting point:

Here's a starting persona for <use case>:

  Name:       <template name>
  Voice:      <voice>
  Language:   en-US
  Background: <background>
  Wait:       <wait seconds>s
  Prompt:     "<template description>"

Ask: "Use this as a starting point? (yes / customize name / start from scratch)"

Phase 3: Voice + Language

Load

references/voice-options.md

for available options.

Ask these questions:

"What language should the persona speak?"
- en-US — English (US)
- es-ES — Spanish (Spain)
- fr-FR — French (France)
- de-DE — German
- pt-BR — Portuguese (Brazil)
- ja-JP — Japanese
"Voice preference?"
- Female: aria (clear, professional)
- Male: callum (clear, professional)

For non-voice agents (chat, websocket, API), explain: "Since your agent is text-based, voice and language are stored as defaults but won't affect the simulation."

Phase 4: Environment + Behavior

Background Sound

Present options with recommendations based on the use case:

Value	Description	Recommended For
quiet	No background noise	Medical, legal, financial calls
office	Office ambient noise	Corporate, business, IT support
cafe	Restaurant/cafe noise	Casual, restaurant scenarios
airport	Airport/travel noise	Travel-related agents

Say: "Based on your <use case> use case, I'd recommend <recommended>. Use that or pick another?"

Wait Seconds

How long the persona waits before speaking after connection:

Value	Style	Best For
0.3	Fast responder	Restaurant orders, fast-paced interactions
0.5	Standard	Most inbound call scenarios
1.0	Slow / deliberate	Outbound calls, debt collection, elderly callers

Say: "The template uses <template wait>s. Keep that or adjust?"

Interruption Rate

How often the persona interrupts the agent mid-sentence:

Rate	Behavior	Best For
NONE	Never interrupts	Compliance testing, scripted flows
LOW	Rare interruptions	Standard testing, polite callers
MEDIUM	Occasional interruptions	Realistic conversation simulation
HIGH	Frequent interruptions	Stress testing, impatient callers

Explain: "NONE is best for validating scripted compliance flows. LOW is realistic for most callers. MEDIUM simulates natural conversation. HIGH stress-tests your agent's ability to handle interruptions."

Ask: "What interruption rate? (NONE / LOW / MEDIUM / HIGH)"

Note: Interruption rate is not yet available as a CLI flag. To set it after creation, use the Coval API:
PATCH /v1/personas/{persona_id}
with
{"interruption_rate": "LOW"}
.

Phase 5: Prompt Crafting

Start from the template's description as a base prompt.

Explain the key distinction: "The persona prompt defines WHO the caller is and HOW they behave — their personality, speaking style, and emotional state. It does NOT define what they ask about — that's handled by test cases."

Ask: "What specific behavior should this persona exhibit? For example:"

"Speaks quickly and gets frustrated if put on hold"
"Elderly caller who needs things repeated"
"Non-native speaker who sometimes uses wrong words"
"Aggressive caller who threatens to cancel"

Help the user refine the

simulated_user_prompt

by combining:

The template description as a foundation
The user's language choice applied to
```
{language}
```
placeholders
Any custom behavior the user describes

Present the final prompt for confirmation before proceeding.

Phase 6: Create + Confirm

Present a full summary before creating:

Ready to create this persona:

  Name:              <name>
  Voice:             <voice>
  Language:          <language>
  Background:        <background>
  Wait Seconds:      <wait>
  Interruption Rate: <rate>
  Prompt:            "<final prompt>"

Ask: "Create this persona? (yes / edit)"

Create the persona:

bash

coval personas create \
  --name "<name>" \
  --voice "<voice>" \
  --language "<language>" \
  --prompt "<final prompt>" \
  --background "<background>" \
  --wait-seconds <wait> \
  --format json

Capture

persona_id

from the JSON response.

Confirm success:

Persona created!

  ID:   <persona_id>
  Name: <name>

  View: https://app.coval.dev/personas/<persona_id>

Phase 7: Next Steps

Suggest what the user can do next:

What's next?

  Build test cases for this persona:     /build-test-suite
  Configure evaluation metrics:          /configure-metrics
  Launch a quick evaluation:             /quick-eval

  Or manage this persona later:
  coval personas get <persona_id>
  coval personas update <persona_id> --prompt "new prompt"

design-persona

NPX Install

Tags

SKILL.md Content

Design Persona

Phase 0: Preflight + Inventory

Step 1: Check authentication

Step 2: Inventory existing resources

Phase 1: Agent Context

Phase 2: Use Case Detection

Phase 3: Voice + Language

Phase 4: Environment + Behavior

Background Sound

Wait Seconds

Interruption Rate

Phase 5: Prompt Crafting

Phase 6: Create + Confirm

Phase 7: Next Steps