Documentation & Support

Everything you need to use, contribute to, and integrate the Persona Library into your workflow.

Overview

What is the Persona Library?

The Persona Library is an open-source collection of deep, research-grade persona profiles for the tools that run modern work. Each persona represents a real archetype — not a marketing segment, but someone with specific goals, frustrations, workflows, and decision patterns.

Every persona follows a consistent 14-field schema that captures identity, intention, outcome, goals, frustrations, worldview, scenarios, context, impact, composability notes, aha moments, job stories (JTBD), success signals, and churn triggers.

200 personas across 17 categories, each community-validated and exportable in Markdown or PDF.

Persona Schema

YAML Schema Reference

Each persona is defined as a YAML file with front matter and structured fields. Here is the full schema:

name: "The [App] [Role/Archetype]"
pid: APP-001
app: AppName
category: productivity
tags: [tag1, tag2, tag3]
version: 1.0

identity: >
  A detailed paragraph describing who this
  person is and their relationship to the tool.

intention: >
  The specific action they sit down to do —
  concrete and operational, not aspirational.

outcome: >
  The tangible artifact or state change that
  results when the intention succeeds.

goals:
  - Primary goal
  - Secondary goal
  - Tertiary goal

frustrations:
  - Key pain point
  - Another frustration

worldview:
  - Core belief about their work
  - How they see the tool category

scenario: >
  A day-in-the-life narrative showing how
  they interact with the product.

context: >
  Industry, team size, and environmental
  factors that shape their experience.

impact:
  - Business outcome they achieve
  - Personal outcome they value

composability: >
  How this persona overlaps with or differs
  from adjacent personas.

aha_moment: >
  The specific moment they realized the
  product was worth adopting.

jtbd: >
  When I [situation], I want to [motivation],
  so I can [expected outcome].

success_signal: >
  Observable behavior that indicates adoption.

churn_trigger: >
  The event or pattern that causes them to
  leave or downgrade.

Field Descriptions

pidUnique identifier in the format APP-NNN

identityWho this person is — role, company size, relationship to the tool

intentionThe specific action they are trying to take — concrete and operational

outcomeThe tangible deliverable or state change when the intention succeeds

goalsWhat they are trying to achieve with the product

frustrationsPain points and friction they experience

worldviewCore beliefs that shape how they evaluate tools

scenarioA realistic day-in-the-life narrative

contextEnvironmental factors — industry, team, constraints

impactBusiness and personal outcomes they achieve

composabilityHow this persona relates to others in the library

aha_momentThe moment of realization that drove adoption

jtbdJob-to-be-done story in When/Want/So format

success_signalObservable behavior indicating successful adoption

churn_triggerWhat causes this persona to abandon the product

Contributing

How to Contribute

Every field in every persona can be confirmed, corrected, or extended by real users. There are two ways to contribute:

Via the Website

Click the + button next to any section on a persona detail page. Choose your contribution type and write from lived experience. Your submission creates a GitHub pull request automatically.

Contribution Types

addSomething missing from the persona that should be included

confirmValidate that existing content matches your real experience

correctFix inaccurate information based on your lived experience

edge-caseA notable exception or unusual pattern worth documenting

contextIndustry-specific or regional context that adds nuance

Via GitHub

Fork the repository, add or modify YAML files in the personas/ directory, and submit a pull request. Follow the schema reference above and review the CONTRIBUTING.md for detailed guidelines.

API & Exports

Export Formats

Every persona can be exported for use in your tools, presentations, or research workflows.

Markdown Export

Click Export MD on any persona detail page to download a complete Markdown file with front matter and all fields. Compatible with Notion, Obsidian, Confluence, and any Markdown editor.

PDF Export

Click Export PDF to generate a print-friendly version. The page uses a clean print stylesheet that removes navigation and interactive elements.

Raw YAML

Access the raw persona YAML files directly from the GitHub repository. Each file in personas/apps/ is a self-contained persona definition.

JSON API

Access persona data programmatically via the built-in JSON API:

GET /api/personas

Response:
{
  "count": 200,
  "categories": ["analytics", "design", ...],
  "personas": [
    {
      "pid": "APP-001",
      "name": "The Airtable Ops Manager",
      "app": "airtable",
      "category": "technical",
      "tags": ["airtable", "operations", "no-code"],
      "identity": "An operations manager who...",
      "slug": "airtable-primary-user",
      "depth_score": 10,
      "comment_count": 0
    },
    ...
  ]
}

Programmatic Access (Git)

# Clone the repo
git clone https://github.com/jonathan-trustOS/Persona-Library.git

# Parse all personas
ls personas/apps/*.md

# Use the JSON API
curl https://www.persona-library.com/api/personas

MCP Integration

Using Personas with MCP

The Model Context Protocol (MCP) lets AI agents read structured data before responding. Personas are a natural fit: load a persona as context and the AI stops giving generic answers. It understands who the user is, what frustrates them, and what success looks like.

Why MCP + Personas? Most AI tools respond generically because they have no user context. A persona file gives the AI a complete mental model — role, goals, frustrations, worldview, aha moment — so responses are grounded in real user research instead of assumptions.

Expose Personas as MCP Resources

Serve persona markdown files directly as MCP resources. The AI can request any persona by slug and receive the full 14-field profile.

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import fs from "fs";

const server = new McpServer({ name: "persona-library" });

// Expose a single persona as a resource
server.resource(
  "persona-notion-user",
  "persona://notion-primary-user",
  async (uri) => ({
    contents: [{
      uri: uri.href,
      mimeType: "text/markdown",
      text: fs.readFileSync(
        "personas/apps/notion-primary-user.md", "utf-8"
      )
    }]
  })
);

// Or expose all personas via a resource template
server.resource(
  "persona-by-slug",
  new ResourceTemplate("persona://{slug}", { list: undefined }),
  async (uri, { slug }) => ({
    contents: [{
      uri: uri.href,
      mimeType: "text/markdown",
      text: fs.readFileSync(
        `personas/apps/${slug}.md`, "utf-8"
      )
    }]
  })
);

Search Personas as an MCP Tool

Use the JSON API as an MCP tool so AI agents can search and filter personas by app, category, or keyword.

server.tool(
  "search-personas",
  "Search the Persona Library by app name or category",
  {
    query: z.string().optional(),
    category: z.string().optional(),
  },
  async ({ query, category }) => {
    const res = await fetch(
      "https://www.persona-library.com/api/personas"
    );
    const data = await res.json();

    let results = data.personas;
    if (query) {
      const q = query.toLowerCase();
      results = results.filter(p =>
        p.name.toLowerCase().includes(q) ||
        p.app.toLowerCase().includes(q) ||
        p.tags.some(t => t.includes(q))
      );
    }
    if (category) {
      results = results.filter(
        p => p.category === category
      );
    }

    return {
      content: [{
        type: "text",
        text: JSON.stringify(results, null, 2)
      }]
    };
  }
);

System Prompt Patterns

Three proven patterns for injecting persona context into AI interactions:

Pattern 1: Support Agent

You are a support agent for Notion. Before responding,
consider this user persona:

{contents of notion-primary-user.md}

Use this context to tailor your tone, anticipate their
frustrations, and speak to what this user actually
cares about. Reference their worldview when explaining
tradeoffs.

Pattern 2: Product Review Simulation

You are role-playing as this persona:

{contents of figma-primary-user.md}

Review the following feature proposal from this
persona's perspective. Be specific about how it
helps or hinders their goals. Reference their
scenario and frustrations. Be honest — they would be.

Pattern 3: Multi-Persona Comparison

Consider these two personas for the same product:

Persona A: {stripe-primary-user.md}
Persona B: {stripe-platform-builder.md}

How do their goals create tension? What product
decisions would satisfy both? Where must the team
choose one over the other?

What Each Field Gives the AI

identityWho this person is — role, mindset, experience level

intentionWhat they are trying to accomplish right now

outcomeThe result they expect to produce

goalsWhat drives their product usage

frustrationsWhat to avoid saying or doing

worldviewHow they think — language, mental models, values

scenarioA real workflow the AI can reference in answers

contextEnvironmental constraints that shape realistic advice

aha_momentThe experience that made the product click

jtbdThe underlying job they hired the product for

success_signalHow they define "this is working"

churn_triggerWhat would make them leave

Claude Desktop & Cursor Setup

Add the Persona Library as an MCP server in your AI tool of choice. Clone the repo and point your config at it:

// claude_desktop_config.json
{
  "mcpServers": {
    "persona-library": {
      "command": "node",
      "args": ["path/to/persona-mcp-server.js"],
      "env": {
        "PERSONAS_DIR": "/path/to/Persona-Library/personas/apps"
      }
    }
  }
}

// .cursor/mcp.json (Cursor IDE)
{
  "mcpServers": {
    "persona-library": {
      "command": "node",
      "args": ["path/to/persona-mcp-server.js"]
    }
  }
}

Or use the JSON API directly — no local clone required. Point any HTTP-capable MCP server at https://www.persona-library.com/api/personas and build tools that search, filter, and inject persona context on demand.

Use Cases

Using Personas in Your Workflow

Product & UX Research

Import personas into your research tools as starting hypotheses. Use the aha_moment and jtbd fields to inform interview guides. Validate with your own users and contribute findings back to the library.

Design Sprints

Print persona cards for design sprint exercises. The structured format makes it easy to reference goals, frustrations, and scenarios during ideation sessions.

AI & LLM Context

Use persona YAML files as context for AI-assisted design, copywriting, or product analysis. The structured schema is optimized for LLM consumption — paste a persona into any AI tool to get role-specific feedback.

Composability

Many real users match multiple personas. Use the composability field to understand overlaps and create composite user profiles for more nuanced product decisions.

FAQ

Frequently Asked Questions

Are these real people?

No. Personas are research-grade archetypes based on patterns observed across real users. They represent common behaviors, not specific individuals.

Can I use these commercially?

Yes. The Persona Library is open source. You can use, modify, and distribute personas in your commercial projects.

How are contributions reviewed?

Every contribution creates a GitHub pull request. Maintainers review for accuracy, specificity, and alignment with the persona schema before merging.

How do I suggest a new persona?

Create a new YAML file following the schema reference and submit a pull request on GitHub. Include as many fields as possible from your experience.

What if a persona is inaccurate?

Click the + button on the relevant section and select "Something needs correcting." Describe the inaccuracy and what the correct information should be.

Can I request a specific app or tool?

Yes! Open a GitHub issue with the app name and any initial observations about its user archetypes. The community can then build on that foundation.

Support

Getting Help

GitHub Issues

Report bugs, request features, or ask questions

Open an Issue →

GitHub Discussions

Join community conversations about personas and research methodology

Join Discussions →

Contributing Guide

Detailed instructions for contributing to the library

Read Guide →