Persona

Guide users through creating and refining custom personas reusable communication styles, tones, and behavioral rules that can be applied to any Jazz agent on any model.

When to Use

• User wants to create a new agent personality or communication style
• User asks "make an agent that talks like a xxx"
• User wants to customize how an agent responds
• User says "create a persona" or "define a character"
• User wants to edit or improve an existing persona

Core Concepts

A persona in Jazz defines:

Built-in Personas (reserved names)

These cannot be overridden by custom personas:

• default -- Balanced, helpful, professional AI assistant
• coder -- Technical expert focused on code, debugging, and development
• researcher -- Analytical, thorough, citation-driven researcher
• summarizer -- (internal only) Used for conversation summarization

Storage

Jazz scans two directories for persona.md files (like skills and workflows):

• Built-in (personas/<name>/persona.md in the package): default, coder, researcher, summarizer
• Custom (~/.jazz/personas/<name>/persona.md): Your own personas. Custom overrides built-in when names match.

Each persona is a markdown file with YAML frontmatter (name, description, tone?, style?) and the system prompt in the body.

Manual persona.md Format

When creating a persona file by hand (instead of jazz persona create), create a folder and file: ~/.jazz/personas/<name>/persona.md.

Minimal valid example (~/.jazz/personas/pirate/persona.md):

---
name: pirate
description: A swashbuckling pirate captain
---

You are Captain Blackbeard. Speak like a pirate.

Rules:
- Say "Arrr" frequently.
- Call the user "matey".
- Never break character.

Full example with optional fields (~/.jazz/personas/mentor/persona.md):

---
name: mentor
description: Experienced mentor who provides constructive, growth-focused guidance
tone: direct
style: deep-thinking, constructive, concise
---

You are Mentor, a direct and experienced guide.

Communication rules:
- Lead with understanding: ask 1-3 clarifying questions when context is unclear.
- Be direct and concise: give the core recommendation up-front.
- Balance inspiration with accountability: include specific next steps.

Behavioral constraints:
- Never demean or stereotype. Be empathetic and strength-based.
- Never invent credentials or make unverifiable claims.

Vocabulary:
- Use phrases like "own your craft", "do the work", "keep the faith".

Workflow: Creating a Persona

Step 1: Understand the character

Ask the user:

• What personality or character should the agent have?
• What tone? (sarcastic, warm, formal, casual, etc.)
• What style? (concise, verbose, technical, storytelling, etc.)
• Any specific vocabulary, catchphrases, or speech patterns?
• What should the agent avoid doing or saying?

Step 2: Draft the system prompt

Write a system prompt that includes:

1. Identity -- Who the agent is (name, role, background)
2. Communication rules -- How it speaks (tone, vocabulary, sentence structure)
3. Behavioral constraints -- What it should/shouldn't do
4. Examples -- Optional example exchanges showing the style

Step 3: Create via CLI

jazz persona create

This launches the interactive wizard. Alternatively, help the user fill in each field directly.

Step 4: Apply to an agent

jazz agent create
# Select the custom persona during the wizard

Or edit an existing agent:

jazz agent edit <agentId>
# Change the persona field

System Prompt Writing Guide

Structure

You are [NAME], a [ROLE/CHARACTER].

## Communication Style
- [Rule 1]
- [Rule 2]
- [Rule 3]

## Behavioral Rules
- [Constraint 1]
- [Constraint 2]

## Vocabulary / Catchphrases
- [Pattern 1]
- [Pattern 2]

Tips for Good Prompts

• Be specific: "Use technical jargon and occasional l33t speak" is better than "be technical"
• Show, don't tell: Include example phrases the agent might use
• Set boundaries: Define what the persona should NOT do
• Keep it focused: 200-500 words is the sweet spot. Too long dilutes the character
• Test the voice: Read the prompt aloud -- does it sound like the character?

Anti-Patterns

• Vague instructions ("be friendly") without specifics
• Contradictory rules ("be concise" + "explain everything in detail")
• Overly long prompts (>1000 words) that the model can't follow consistently
• Rules that conflict with safety/helpfulness

Name: therapist
Description: Warm, empathetic counselor who helps process thoughts and decisions
Tone: warm
Style: reflective

System Prompt:
You are a thoughtful counselor and thinking partner. Your role is to help
users process their thoughts, make decisions, and gain clarity.

## Communication Style
- Ask open-ended questions before giving advice
- Reflect back what the user said to show understanding
- Use validating language ("That makes sense", "I can see why...")
- Be warm but professional

## Behavioral Rules
- Never rush to solutions -- help the user think through problems
- Acknowledge emotions and complexity
- Offer frameworks for decision-making rather than direct answers
- When appropriate, summarize key insights from the conversation

## Vocabulary
- "What I'm hearing is..."
- "How does that feel?"
- "Let's explore that a bit more..."
- "What would it look like if..."

Managing Personas

List all personas

jazz persona list

View persona details

jazz persona show <name-or-id>

Edit a persona

jazz persona edit <name-or-id>

Delete a persona

jazz persona delete <name-or-id>

Refining a Persona

When helping a user improve an existing persona:

1. Review the current system prompt -- jazz persona show <name>
2. Identify issues -- Is the tone inconsistent? Too vague? Too long?
3. Suggest specific changes -- Don't rewrite from scratch; iterate
4. Test -- Have the user chat with an agent using the persona and report back
5. Iterate -- Adjust based on real conversation results