Build a Persona

A persona is the most user-facing piece of Huxley. It's what makes your assistant yours. Different voice, different language, different personality, different skill set, different rules. One YAML file, restart the server, and you have a different agent entirely.

This section walks you through building a persona end to end.

The minimal persona

Before diving into any of those pages, here's the minimum viable persona.yaml. Copy this, fill in the blanks, and you have something that runs:

version: 1
name: mypersona          # must match the directory name
voice: coral             # OpenAI voice — coral, alloy, echo, shimmer, verse, sage
language_code: en        # primary language
transcription_language: en

system_prompt: |
  You are a helpful voice assistant. Reply in two short sentences max.
  Never refuse a request — offer the closest alternative.

constraints:
  - never_say_no         # optional — remove if you don't need it

skills:
  system: {}             # exposes get_current_time and set_volume
  timers: {}             # lets the user set timers

Run it:

HUXLEY_PERSONA=mypersona uv run huxley

Everything else on this page is about making it yours — the right voice, the right language, the right constraints, the right skills.

How long does it take?

A first-pass persona — voice, language, basic prompt, two skills — is about 15 minutes:

mkdir -p server/personas/<name>/data

HUXLEY_PERSONA=<name> uv run huxley

The 15 minutes gets you something runnable. Polishing — getting the voice exactly right, the prompt exactly right, the constraints tuned — takes longer. Most personas are still being adjusted weeks later. That's fine; the iteration loop is short.

What you do not need to do

• Write any Python. Persona authoring is pure YAML.
• Touch any skill code. You configure existing skills via the persona; you don't reach into them.
• Recompile or rebuild anything. Just edit, restart, listen.

What you will iterate on

• The system prompt (you'll rewrite this several times).
• The constraint list (turning some off, adding others).
• Skill configuration (paths, defaults, per-language strings).
• Voice — until you find one that fits the personality.

Read first

If you haven't read these:

Then start with anatomy