Online Tool Store
· 4 min read
How to Write a Persona Card for a Chatbot
Manesh Jayawardhana
CIO & Co-founder
Most chatbot persona documents read like a character sheet: a name, a friendly disposition, a paragraph about being helpful and approachable. Then the assistant goes live and confidently answers a legal question it had no business touching.
The backstory wasn’t the problem. The document just never said what the assistant shouldn’t do, or what should happen instead.
What a persona card is actually for
A persona card is the part of a system prompt that defines behaviour. Five things do real work in it:
Scope. The single job this assistant does. “Billing and account questions” is a scope. “Customer support” is a category.
Tone. How it writes. Two or three concrete adjectives, and ideally one example sentence, beat a paragraph of description.
Refusals. The topics it must not engage with, named explicitly. “Be safe” changes nothing; “don’t give legal, medical or tax advice, say X instead” changes behaviour.
Escalation. What happens at the boundary. Who takes over, under what conditions, and what the assistant says while handing off.
Never-claims. Things it must not assert — that it’s a human, that it can guarantee an outcome, that it has access to systems it doesn’t.
The pattern to notice: four of the five are about limits. Personality is the least load-bearing part of a persona card, and it’s the part most documents spend the most words on.
Why people get stuck here
- Scope too broad. An assistant that handles everything has no boundary to enforce, so refusals become arbitrary.
- Vague refusals. “Avoid sensitive topics” is not a specification anyone — human or model — can apply consistently.
- No escalation path. The assistant is told what not to do and given nowhere to send the user.
- Untracked prompts. The card lives in a console text box, gets edited live, and nobody knows what changed when behaviour shifted.
What a good persona card contains
One job, stated plainly
Name the domain and, more usefully, name the adjacent domains that are out of scope. The boundary is more informative than the centre.
Refusals with replacements
For each refusal, say what the assistant should offer instead. A refusal with no alternative reads as unhelpful; a refusal that redirects reads as competent.
An escalation trigger and a handoff line
Under what conditions does a human take over, and what does the assistant say as it hands off? Both need writing, or the assistant will improvise something inconsistent.
Version control
The card is configuration. It belongs in a repository alongside your code, with a history, so a behaviour change can be traced to a commit.
| Section | Weak | Strong |
|---|---|---|
| Scope | “Customer support” | “Billing and account questions only” |
| Refusals | “Avoid sensitive topics” | “No legal, medical, tax — say X instead” |
| Escalation | Not specified | “Refunds over £100 → human, say Y” |
| Tone | “Friendly and helpful” | “Plain, warm, short sentences” |
Common mistakes to avoid
- Writing three paragraphs of backstory and one line about scope.
- Listing refusals without saying what to do instead, producing a bot that stonewalls.
- Editing the prompt directly in a production console with no record of the change.
- Promising capabilities the assistant doesn’t have, such as looking up an order it can’t see.
- Hiding the scope from users — people who know what the assistant handles escalate sooner and complain less.
How to do it with Chatbot Persona Card Builder
The Chatbot Persona Card Builder produces a card structured around the parts that change behaviour.
- Name the assistant and the single job it does.
- Set the tone, and write one example sentence in that voice.
- Define refusals explicitly, each with what to say instead.
- Set the escalation trigger and the handoff wording.
- Copy the card into your system prompt and commit it alongside your code.
Other prompt and documentation generators are in the tools directory. If you’re building against a specific model, its provider’s own prompting documentation is worth reading alongside this.
Frequently asked questions
How specific should refusals be?
Specific enough to act on. Name the topics and the replacement response. A general instruction to be careful produces inconsistent behaviour, because “careful” is interpreted differently in every conversation.
Should users see the persona?
A summary of scope, yes. Users who know what the assistant does and doesn’t handle raise fewer impossible requests and reach a human faster when they need one.
Does backstory help at all?
A little, for tone consistency. But it’s the smallest lever in the document. Scope, refusals and escalation change what the assistant actually does; backstory mostly changes adjectives.
Final thought
Write the boundaries first and the personality last. A well-bounded assistant with no character is useful; a charming one with no limits is a liability.