Documentation
Everything you need to create, package, and publish a persona.
AI agents: this page contains the complete spec. Read it once and you can generate a persona repo from any user's setup.
Persona packages are plain markdown files in a Git repo. They are not tied to any specific AI agent. Any agent that can read text files can use them. The spec is agent-agnostic by design.
What is a persona?
A persona is a portable AI behavioral configuration that defines who an AI agent IS, not just what it can do. It includes identity, communication style, behavioral rules, commands, memory templates, integrations, and blueprints for reproducible project systems.
Package structure
A persona lives in a Git repo with this layout:
PERSONA.md
The identity document. Gets loaded into the AI's context every session. Three sections are required.
## Identity
requiredWho this persona IS. Role, primary directive, relationship to the user. 3-10 sentences in second person ("You are...").
## Communication Style
requiredHow the persona talks. Tone, formatting, vocabulary, specific DO and DON'T rules. Minimum 3 concrete instructions.
## Behavioral Rules
requiredHard constraints and NEVER/ALWAYS rules. Confidentiality, authorization boundaries, uncertainty handling. Minimum 2 rules.
## Context
Company details, team structure, industry, key systems. Use {{VARIABLES}} for personal data.
## Operating Modes
Named behavioral modes (triage, drafting, research). Each mode has an activation trigger and specific rules.
## Integrations
MCP server routing, tool preferences, and fallback behavior when integrations are disconnected.
SETUP.md
Installation instructions. Must work for both AI-assisted and manual setup.
# Setup
## Quick Install (AI-assisted)
Paste into your AI agent:
```
Install the [Display Name] persona from
github.com/you/my-persona -- clone the repo,
read the setup instructions, ask me for my
personal details, replace all template variables,
copy the files to the right config locations,
and walk me through connecting any integrations.
```
## Manual Installation
### 1. Clone the repo
```bash
git clone https://github.com/you/my-persona.git
```
### 2. Edit PERSONA.md
Replace all {{VARIABLE}} placeholders with your info.
### 3. Load the persona into your AI agent
Copy PERSONA.md content into your agent's config.
Every agent has a location for persistent instructions:
Known config paths (examples, not exhaustive):
- Claude Code: ~/.claude/CLAUDE.md
- Cursor: .cursorrules in project root
- Windsurf: .windsurfrules in project root
- OpenClaw/ZeroClaw: personality config dir
For any other agent: find where it reads system
instructions or persistent context, and paste
PERSONA.md there. The format is plain markdown --
it works anywhere.
### 4. Connect integrations (if applicable)
[List each MCP server or API with setup steps]
### 5. Test it works
[Provide a test prompt the user can run to verify]Both paths must be present. The AI-assisted path is the one-sentence install prompt. The manual path numbers every step.
README.md
Human-readable description. This is what people see on GitHub before installing.
What This Is
required1-2 paragraphs. What the persona does, who it's for, what makes it different from a generic AI.
What It Does
requiredBullet list of key behaviors and capabilities. Pull from your highlights.
Install
requiredThe one-sentence AI install prompt. Same as the quick install in SETUP.md.
Blueprints
Table of included project systems: name, complexity, what it builds. Only if your persona has blueprints.
Compatible With
requiredList of AI agents this works with (Claude Code, Cursor, Windsurf, etc.).
persona.yaml
Machine-readable metadata. This is what the catalog indexes.
name: my-persona # lowercase, hyphens, 3-40 chars
display_name: My Persona # human-readable
version: 1.0.0 # semver
description: >
What it does, who it's for. 1-3 sentences.
author:
name: Your Name
github: your-username
category: executive # see categories below
tags: [tag1, tag2, tag3] # 2-8 tags
compatible_with: # agents you've tested with
- Claude Code # list what you've verified
- Cursor # not an exhaustive limit
- OpenClaw # any agent that reads
- ZeroClaw # markdown config files works
integrations: # optional, external services
- name: gmail
type: mcp # mcp, api, service, plugin
required: true
purpose: "Email triage"
- name: notion
type: api
required: false
purpose: "Knowledge base"
required_skills: # optional, third-party skills
- name: xlsx
install: "npx skills add xlsx"
purpose: "Spreadsheet creation and editing"
required: true
variables: # optional
- key: YOUR_NAME
prompt: "What's your name?"
required: true
workflows: # optional, slash commands
- command: /gm
name: Morning Briefing
description: "Pulls calendar, tasks, inbox"
- command: /triage
name: Inbox Triage
description: "Scans and classifies messages"
blueprints: # optional
- telegram-intake # names of dirs in blueprints/
- accounting-pipeline
highlights: # 3-9 key features for catalog
- "What makes this persona distinct, bullet 1"
- "What makes this persona distinct, bullet 2"
- "What makes this persona distinct, bullet 3"
repository: https://github.com/you/my-personaRequired fields: name, display_name, version, description, author (name + github), category, tags
Recommended: compatible_with, highlights, repository, variables
Optional: integrations, required_skills, workflows, blueprints
Note on compatible_with: Persona packages are plain markdown files. They work with ANY AI agent that reads config files. The compatible_with field lists agents the author has tested with, not agents it's limited to. If an agent isn't listed, the persona still works -- the author just hasn't verified it.
Blueprints
Blueprints are reproducible project systems bundled in the persona repo. A command tells the AI what to do in a conversation. A blueprint gives the AI the complete architecture for a system it builds once and then operates.
Examples: a Telegram bot that files documents to Google Drive, an accounting pipeline with a custom spreadsheet, a multi-workflow automation suite, a partnership tracking system.
Blueprint structure
blueprint.yaml
name: telegram-intake
display_name: Telegram Document Intake
version: 1.0.0
description: >
Telegram bot that receives documents, classifies
them with AI, and files them to Google Drive.
complexity: complex # simple | medium | complex
requires:
services:
- name: n8n
purpose: "Workflow automation engine"
required: true
- name: telegram-bot
purpose: "Telegram Bot API token"
required: true
- name: google-drive
purpose: "File storage destination"
required: true
outcomes:
- "Documents sent to Telegram are auto-classified and filed"
- "Every document logged in a tracking spreadsheet"
- "AI renames files with standardized naming"
setup_time_minutes: 30
variables:
- key: TELEGRAM_BOT_TOKEN
prompt: "Paste your Telegram bot token"
description: "Create via @BotFather. Looks like 123456:ABC-DEF..."
required: true
- key: DRIVE_ROOT_FOLDER_ID
prompt: "Google Drive folder ID for filing"
description: "AI creates subfolders inside this. Copy ID from Drive URL."
create: false
- key: TRACKING_SHEET_ID
prompt: "Google Sheet ID for the tracking log"
description: "Leave blank -- AI creates this during setup."
create: trueKey rules
Categories
Every persona gets exactly one category. Pick the best fit.
C-suite support, leadership, strategy, chief of staff
Consulting, compliance, HR, advisory
Code review, DevOps, architecture, language-specific
Writing, content, design, brand, voice cloning
Academic, market research, competitive analysis
Industry-specific expertise (pharma, real estate, etc.)
Life coaching, accountability, journaling, personal growth
Project management, workflows, automation
Tutoring, language learning, curriculum design, study coaching
Trading, investing, accounting, budgeting, financial analysis
Fitness coaching, nutrition, therapy, wellness, biohacking
Contract review, compliance, regulatory analysis
CRM, pipeline, outreach, proposals, deal closing
Customer service, documentation, ticket triage
Reserved variables
Use {{VARIABLE}} placeholders for personal data. These have standard meanings across all personas.
| Variable | Meaning |
|---|---|
| {{YOUR_NAME}} | Full name |
| {{YOUR_FIRST_NAME}} | First name |
| {{YOUR_ROLE}} | Job title |
| {{YOUR_COMPANY}} | Company name |
| {{YOUR_EMAIL}} | Primary email |
| {{YOUR_TIMEZONE}} | IANA timezone |
| {{YOUR_CURRENCY}} | ISO currency code |
| {{YOUR_LANGUAGE}} | Primary language |
Commands
Slash commands live in commands/. Each file is one command. The filename becomes the command name.
# commands/gm.md --- name: gm description: Morning briefing --- # /gm - Good Morning Briefing ## Step 1: Email Triage 1. Fetch unread emails from last 12 hours 2. Classify into Tier 1 (urgent), Tier 2, Tier 3 3. Draft responses for Tier 1 ## Step 2: Calendar Review 1. Fetch today's events 2. Flag back-to-back meetings ## Output Format EMAIL: [count] unread. [count] urgent. CALENDAR: [count] meetings today. GOALS: Top goal status + suggested action.
How to create a persona
If you've customized your AI's behavior, you already have a persona. Here's how to package it.
Open your AI agent, paste the prompt below, and let it do the work.
Copy this prompt and paste it into your AI agent
Read the personas.sh format spec at personas.sh/docs and package my current AI setup as a persona repo. Follow these steps:
1. Scan my full agent setup and report what you find. Check ALL of these: config files (CLAUDE.md, .cursorrules, .windsurfrules, commands/, settings.json, YAML state files), MCP server configs (.claude.json, .cursor/mcp.json), installed skills/plugins (.agents/skills/, any third-party skill directories), memory/state files (.claude/projects/*/memory/), and any hooks or middleware scripts.
2. Analyze the config: identity, communication rules, constraints, integrations, commands, persistent state, domain knowledge.
3. Inventory installed skills and MCP servers. For third-party skills (installed via npm/pip/etc), list them as required_skills with install commands. For custom domain knowledge I wrote myself, include the content in skills/. For MCP servers, list them as integrations with type: mcp.
4. Check for project systems I've built (automations, bots, tracking spreadsheets, workflows). Package each as a blueprint with setup.md, workflow files, and templates.
5. De-identify everything. Replace all personal data with {{VARIABLE}} placeholders. Strip API keys, credentials, tokens, and absolute paths. CRITICAL: also scrub workflow files and automation configs. Replace hardcoded user IDs, bot tokens, Google Drive folder IDs, spreadsheet IDs, webhook URLs, company names, team member names, and any organization-specific logic with descriptive placeholders (YOUR_SHEET_ID, YOUR_FOLDER_ID, YOUR_BOT_TOKEN, YOUR_COMPANY, etc.). The exported workflows should be functional templates, not mirrors of your production setup.
6. Generate the full package: persona.yaml, PERSONA.md (with Identity, Communication Style, Behavioral Rules sections), SETUP.md, README.md, commands/, skills/, blueprints/ if applicable.
7. Show me the file structure and key files for review before writing to disk.
8. After I approve, audit the final output. Read every generated file and verify: does the Identity section actually capture how I use my AI, or is it generic filler? Do the Behavioral Rules reflect my real constraints, or did you invent ones I never set? Are the Communication Style rules specific patterns from my config, not vague best practices you added? Does every blueprint match a real system I built, not something you assumed? Flag anything you're unsure about and ask me rather than guessing.
Your AI will scan your setup, strip personal info, and generate a package that follows the spec. Review it, then push to GitHub and submit.
What makes a good persona
Validation checklist
AI agents: run through this list before presenting the package to the user.
Every item must pass. If something fails, fix it before proceeding.
Structure
De-identification
Completeness
Quality
How to submit
Once your persona repo is on GitHub, submit it to the catalog.
Complete example
All 4 required files for a minimal persona package, plus a blueprint. Copy this structure as a starting point.
persona.yaml
name: sales-closer
display_name: Sales Closer
version: 1.0.0
description: >
Pipeline management and deal execution for B2B
sales teams. Tracks prospects, drafts follow-ups,
and scores deals by close probability.
author:
name: Jane Smith
github: janesmith
category: sales
tags: [sales, b2b, pipeline, deal-closing, crm]
compatible_with:
- Claude Code
- Cursor
integrations:
- name: gmail
type: mcp
required: true
purpose: "Prospect communication"
- name: google-sheets
type: mcp
required: false
purpose: "Pipeline tracking"
required_skills:
- name: xlsx
install: "npx skills add xlsx"
purpose: "Create and edit pipeline spreadsheets"
required: true
variables:
- key: YOUR_NAME
prompt: "Your full name?"
required: true
- key: YOUR_COMPANY
prompt: "Company name?"
required: true
workflows:
- command: /pipeline
name: Pipeline Review
description: "Scans all deals, flags stale ones, suggests next actions"
blueprints:
- deal-tracker
highlights:
- "Flags any deal with no activity in 14+ days. No deals go cold silently."
- "Drafts follow-up emails in your voice, not a template. Ready to send."
- "Scores every deal by close probability based on activity and timeline."
- "Pipeline spreadsheet auto-created with status tracking and reminders."
repository: https://github.com/janesmith/sales-closerPERSONA.md
## Identity
You are the Sales Closer for {{YOUR_NAME}} at
{{YOUR_COMPANY}}. Your job is to move deals through
the pipeline and close them. You track every prospect,
draft follow-up emails in the user's voice, and flag
deals that are going cold. You are a partner in the
sales process, not a reporting tool.
## Communication Style
- Direct and numbers-driven. Lead with metrics.
- No fluff. "Deal X is 60% likely to close by March"
not "Deal X is looking promising."
- Match the user's tone in prospect communications.
- When presenting pipeline: table format, sorted by
close probability descending.
## Behavioral Rules
- NEVER send an email to a prospect without approval.
- NEVER share pipeline data outside the conversation.
- Flag any deal with no activity in 14+ days.
- When a deal is at risk, say so directly. Don't hedge.
## Context
- Company: {{YOUR_COMPANY}}
- Industry: {{YOUR_INDUSTRY}}
- Average deal cycle: {{YOUR_DEAL_CYCLE}} days
## Integrations
- Gmail: prospect email drafting and tracking
- Google Sheets: pipeline spreadsheet
- If Gmail is not connected, draft emails as text blocks
and note they need manual sending.SETUP.md
# Setup
## Quick Install
Paste into your AI agent:
```
Install the Sales Closer persona from
github.com/janesmith/sales-closer -- clone the repo,
read the setup instructions, ask me for my personal
details, replace all template variables, copy the
files to the right config locations, and walk me
through connecting any integrations it needs.
```
## Manual Installation
### 1. Clone the repo
```bash
git clone https://github.com/janesmith/sales-closer.git
cd sales-closer
```
### 2. Edit PERSONA.md
Replace these placeholders with your info:
| Variable | Replace with |
|---|---|
| {{YOUR_NAME}} | Your full name |
| {{YOUR_COMPANY}} | Your company name |
| {{YOUR_INDUSTRY}} | Your industry |
| {{YOUR_DEAL_CYCLE}} | Average deal length in days |
### 3. Copy to your AI config
- Claude Code: copy PERSONA.md content into ~/.claude/CLAUDE.md
- Cursor: copy into .cursorrules in your project root
### 4. Connect Gmail (optional)
Set up the Gmail MCP server for email drafting.
Without it, the persona still works but drafts
emails as text blocks instead of sending directly.
### 5. Test it works
Try: "Review my pipeline and flag anything stale."
You should get a structured table of deals with
status and recommended next actions.README.md
# Sales Closer AI persona for B2B pipeline management and deal execution. Tracks every prospect, drafts follow-ups in your voice, flags stale deals, and scores close probability. ## What It Does - Flags deals with no activity in 14+ days - Drafts follow-up emails ready to send - Scores deals by close probability - Creates pipeline spreadsheet with tracking - Reviews pipeline on command with /pipeline ## Install Paste into Claude Code, Cursor, or any AI agent: ``` Install the Sales Closer persona from github.com/janesmith/sales-closer ``` ## Blueprints | Name | Complexity | What it builds | |---|---|---| | Deal Tracker | Simple | Pipeline spreadsheet with reminders | ## Compatible With - Claude Code - Cursor For manual setup, see [SETUP.md](SETUP.md).
blueprints/deal-tracker/blueprint.yaml
name: deal-tracker
display_name: Deal Tracking Pipeline
version: 1.0.0
description: >
Google Sheets pipeline tracker with automated
follow-up reminders and close probability scoring.
complexity: simple
requires:
services:
- name: google-sheets
purpose: "Pipeline spreadsheet"
required: true
outcomes:
- "All deals tracked in one sheet with status and probability"
- "Automated reminders when deals go cold"
setup_time_minutes: 10
variables:
- key: PIPELINE_SHEET_ID
prompt: "Google Sheet ID for deal tracking"
description: "AI creates this for you during setup. Leave blank."
create: true
required: falseFull technical spec, packaging guide, and classifier prompt: github.com/persona-sh/spec