agentleFS
coval-aicoval-ai/coval-external-skills/skills/personas/personas-from-artifacts/SKILL.md

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".

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
  1. Distinctive:

    Create a *set* of simulation personas for an agent by reading what the agent actually does and who uses it — from backend payloads, UI …

    line 17
  2. Very specific:

    If not authenticated: coval login (key at https://app.coval.dev/settings → Organization → Manage → API Keys).

    line 34
  3. Distinctive:

    If personas already exist, ask whether to add to them, and avoid near-duplicates.

    line 45
  4. Distinctive:

    Ask: "Which agent are these personas for?" Pick from the list or describe a new one.

    line 48
  5. Distinctive:

    Ask the user to share whatever they have (any subset is fine):

    line 65
  6. Very specific:

    Read these to answer three questions: What does this agent do?

    line 73
  7. Distinctive:

    Always include a standard / cooperative baseline.

    line 81
  8. Distinctive:

    Add the ones the evidence supports — e.g.

    line 82
  9. Distinctive:

    Augment with observed traits: If real messages were provided, fold in what you actually see: common emotions, domain vocabulary, typical …

    line 85
  10. Distinctive:

    Ask: "Create these personas?

    line 114

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 whoami

If 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). If coval is a shell alias on your machine, use coval-cli instead (which coval to check).

Inventory in parallel so we extend rather than duplicate:

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

If 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 json

Capture 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-persona afterward to tune voice / wait / interruption per persona.

Personas are created org-wide and are not mechanically bound to an agent — there is no --agent flag on personas 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 --language flag 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 refusal

Ask: "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 json

Capture 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 via coval personas create --input-json with wait_for_user (agent speaks first) or speak_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. --language is cosmetic for text agents and the API stores it normalized (e.g. en-US is saved as en) — 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>

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.