personas-from-artifacts
Skill3 starsChanged 18 days agoMITView on GitHub
Derive a SET of simulation personas for an agent from product artifacts — backend payloads, UI screenshots, journey/product docs, and sample real user messages — instead of designing one persona by hand. Identifies who actually interacts with the agent and how they behave, then creates the personas via the CLI. Best for text/chat agents and for new agents with no interaction history. Use when the user says "make personas from these screenshots/payloads", "who are my users", "create a set of personas", "derive personas from my product", "build a persona library", or "I have backend data, turn it into personas".
In this repository33 other files it gives its agents.
- setup-agentSkill
- build-dashboardSkill
- coval-calibrate-metricSkill
- coval-compare-runsSkill
- coval-discover-failuresSkill
- coval-eval-auditSkill
- coval-evals-as-codeSkill
- coval-eval-startSkill
- review-llm-annotations-and-improve-promptSkill
- configure-metricsSkill
- migrate-bluejaySkill
- onboardSkill
- coval-resourcesSkill
- design-personaSkill
- analyze-accent-reportSkill
- analyze-adversarial-reportSkill
- analyze-audio-quality-reportSkill
- launch-runSkill
- quick-evalSkill
- run-accent-testingSkill
- run-adversarial-testingSkill
- run-audio-quality-testingSkill
- watch-runSkill
- download-audioSkill
- get-resultsSkill
- consult-sofiaSkill
- build-test-suiteSkill
- distill-test-setSkill
- huggingface-importSkill
- configure-trace-metricsSkill
- debug-tracesSkill
- optimize-trace-observabilitySkill
- setup-tracingSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Create a *set* of simulation personas for an agent by reading what the agent actually does and who uses it — from backend payloads, UI …
- Very specific: line 34
If not authenticated: coval login (key at https://app.coval.dev/settings → Organization → Manage → API Keys).
- Distinctive: line 45
If personas already exist, ask whether to add to them, and avoid near-duplicates.
- Distinctive: line 48
Ask: "Which agent are these personas for?" Pick from the list or describe a new one.
- Distinctive: line 65
Ask the user to share whatever they have (any subset is fine):
- Very specific: line 73
Read these to answer three questions: What does this agent do?
- Distinctive: line 81
Always include a standard / cooperative baseline.
- Distinctive: line 82
Add the ones the evidence supports — e.g.
- Distinctive: line 85
Augment with observed traits: If real messages were provided, fold in what you actually see: common emotions, domain vocabulary, typical …
- Distinctive: line 114
Ask: "Create these personas?
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Personas From Artifacts
Create a set of simulation personas for an agent by reading what the agent actually does and who uses it — from backend payloads, UI screenshots, product/journey docs, and real user messages — rather than inventing personas in a vacuum. Personas define the WHO: the personalities, emotional states, and interaction styles of the people the agent serves. They do NOT define what the user asks about (that is test cases) — keep those separate.
This complements /design-persona (which walks you through ONE persona interactively, with
voice/interruption tuning). Use this skill to go from "here is my product surface + some
real traffic" to "here is a covering set of 3–6 personas" in one pass.
Drive everything through the coval CLI. Present the set and confirm before creating. If
$ARGUMENTS names an agent or product area, use it in Phase 1.
Phase 0: Preflight + Inventory
coval whoamiIf not authenticated: coval login (key at https://app.coval.dev/settings → Organization →
Manage → API Keys). No account? https://coval.dev.
Command name: examples use
coval(the Homebrew binary). Ifcovalis a shell alias on your machine, usecoval-cliinstead (which covalto check).
Inventory in parallel so we extend rather than duplicate:
coval personas list --format json
coval agents list --format jsonIf personas already exist, ask whether to add to them, and avoid near-duplicates.
Phase 1: Agent Context
Ask: "Which agent are these personas for?" Pick from the list or describe a new one. If it exists, fetch it and read its prompt for grounding:
coval agents get <agent_id> --format jsonCapture model_type:
MODEL_TYPE_CHAT/MODEL_TYPE_WEBSOCKET/MODEL_TYPE_API→ text agent: voice and language are stored as defaults only and do NOT affect the simulation. Put the persona's behavior and target language in the prompt.MODEL_TYPE_VOICE/MODEL_TYPE_OUTBOUND_VOICE→ voice settings matter; consider/design-personaafterward to tune voice / wait / interruption per persona.
Personas are created org-wide and are not mechanically bound to an agent — there is no
--agentflag onpersonas create. Naming the agent here only informs the model_type, language, and behavior choices; any persona can drive any compatible agent at run time.
Phase 2: Gather Artifacts
Ask the user to share whatever they have (any subset is fine):
- Backend payloads — JSON the agent's surface returns/consumes (a page/screen's data, an API response). Reveals the domain entities, states, and the kinds of tasks users do.
- UI screenshots — the screen(s) users act on. Reveals the journeys and entry points.
- Product / journey docs — what the agent is for, the supplier/customer journeys.
- Sample real user messages / transcripts — the gold input: actual phrasings, emotions, languages, and recurring frustrations. (Strip PII before sharing.)
Read these to answer three questions: What does this agent do? Who interacts with it? How
do those people behave? Load references/artifact-to-persona.md for how to turn each
artifact type into persona traits.
Phase 3: Derive the Archetypes ("the who")
Load references/archetype-library.md. Select the archetypes that fit THIS agent's real
users (typically 3–6), and tailor each from the artifacts:
- Always include a standard / cooperative baseline.
- Add the ones the evidence supports — e.g. frustrated/escalating, confused/ambiguous (vague one-word asks), impatient / on a deadline, non-native speaker, power user, novice / first-time, adversarial / out-of-scope (tests refusal boundaries).
- Augment with observed traits. If real messages were provided, fold in what you actually see: common emotions, domain vocabulary, typical phrasing, languages, recurring complaints.
- No history? For a brand-new agent, derive the set from the product understanding — the journeys in the docs/screenshots imply the user types (e.g. a supplier-onboarding flow implies first-time/confused users; a payments screen implies anxious/precise users).
Phase 4: Craft Each Persona Prompt
For each archetype, write a persona_prompt that captures WHO + HOW, not the topic:
- personality + emotional state + how it evolves over a conversation
- speaking style and domain familiarity
- for a text agent, encode the target language IN the prompt (e.g. "Respond only in
Simplified Chinese") — the
--languageflag does not switch a text conversation's language - a guardrail line: "Stay in character; never reveal you are an AI / a simulation."
Load references/artifact-to-persona.md for the prompt template and good/bad examples. Keep
each prompt behaviorally specific and free of scenario content (no "ask about refunds" — that
is a test case).
Phase 5: Review the Set
Present the full set as a table for confirmation:
Personas for <agent>:
1. Standard Supplier — cooperative, clear, gives info when asked
2. Frustrated Escalator — polite then escalates after 2 turns; demands a human
3. Confused / Vague — one-word asks ("parts"), needs clarification
4. Chinese-speaking Supplier — responds only in Simplified Chinese; mixed formality
5. Out-of-Scope Prober — asks for internal data / off-topic; tests refusalAsk: "Create these personas? (yes / edit one / add or remove / change the count)"
Phase 6: Create the Personas
For each confirmed persona, create it (voice/language are a valid placeholder pair — cosmetic for text agents; the behavior + language live in the prompt):
coval personas create \
--name "<persona name>" \
--voice aria --language en-US \
--prompt "<the WHO + HOW prompt, with target language baked in>" \
--wait-seconds 0.5 \
--format jsonCapture each persona_id. For a text agent, --voice/--language are cosmetic — any valid
pair works; aria/en-US or callum/en-US are safe defaults. Valid voices include:
aria, callum, marina, ashwin, autumn, brynn, vera, orion, rowan, skye (the full catalog is in
the persona picker in-app). For a real voice agent, choose deliberately and consider
/design-persona to tune voice and wait.
Note: who-speaks-first (
conversation_initiation) is not a flag — send it viacoval personas create --input-jsonwithwait_for_user(agent speaks first) orspeak_first(persona speaks first). Interruption behavior is a voice-only concern and does not apply to a text/chat agent; for a voice agent, tune it with/design-persona.--languageis cosmetic for text agents and the API stores it normalized (e.g.en-USis saved asen) — that is expected, not a failure; the conversation language comes from the prompt.
Phase 7: Next Steps
What's next?
Deep-tune one persona (voice / interruption / wait): /design-persona
Build scenarios for these personas to run: /build-test-suite
Distill a large dataset into a representative test set: /distill-test-set
Launch an evaluation: /quick-eval
Manage later:
coval personas get <persona_id>
coval personas update <persona_id> --prompt "..."
View: https://app.coval.dev/personas/<persona_id>Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

