Skill: wpank/persona-docs (version 0.1.0)

--- name: persona-docs model: reasoning version: 1.0.0 description: > Create persona documentation for a product or codebase. Use when asked to create persona docs, document target users, define user journeys, document onboarding flows, or when starting a new product and needing to define its audience. Persona docs should be the first documentation created for any product. tags: [personas, user-research, product, documentation, onboarding, user-journey] --- # Persona Docs Create user-centered documentation that defines who a product is for and how they interact with it. Persona docs establish the foundation for product-driven development — every feature decision, design choice, and prioritization call flows from understanding your users. ## Installation ### OpenClaw / Moltbot / Clawbot ```bash npx clawhub@latest install persona-docs ``` ## When to Create Persona docs should be the first thing fleshed out for any product. Even minimal documentation about who uses the product helps direct development and design decisions. - **Project inception** — before writing code, define who you're building for - **Pivoting to a new audience** — document the shift so the team aligns - **Team lacks clarity on target users** — when people disagree on "who is this for?" - **Before major feature planning** — validate that planned features serve actual users - **New team member onboarding** — give them context on who they're building for ## Process 1. **Analyze the codebase** — look for existing documentation, README, landing pages, or marketing copy that hints at the target audience 2. **Ask clarifying questions** if the target user isn't clear: - "Who is the primary user of this product?" - "What problem does this solve for them?" - "How would they discover this product?" - "What's the first thing they'd do after finding it?" 3. **Start minimal** — a few sentences per section is better than nothing 4. **Read the template** — see `references/template.md` for the full structure 5. **Iterate** — revisit and expand as you learn more about actual users ## Core Components ### 1. Target User Profile Who they are, their background, their context. Be specific enough to be useful. **Good:** "Backend engineers at mid-size SaaS companies who debug production issues under time pressure, typically 3-8 years of experience, comfortable with command-line tools." **Too vague:** "Developers." Include: - Role, job title, or archetype - Technical level and relevant skills - Industry or domain context - When and where they'd use this product - Team size and organizational context ### 2. User Needs and Pain Points The problems this product solves. What frustrations or gaps exist in their current workflow? Structure as: - **Primary pain point** — the single biggest problem you solve - **Secondary pain points** — additional problems you address - **Current workarounds** — what they do today without your product - **Why existing solutions fail** — what alternatives exist and why they're insufficient ### 3. Discovery Path How they find the product. This informs marketing, positioning, and first-impression design. - **Search** — what queries lead them here? - **Referral** — word of mouth, colleague recommendation? - **Content** — blog posts, tutorials, conference talks? - **Marketplace** — app store, plugin directory, package registry? - **The hook** — what makes them click "sign up" or "download"? ### 4. Onboarding Flow The simplest possible path from "I found this" to "I'm getting value." Define: - **First encounter** — landing page, app store listing, GitHub README - **Registration/Login** — minimum viable auth (email-only? OAuth? no account?) - **Time to value** — how quickly can they experience the core benefit? - **First success moment** — the specific action that makes them think "this is useful" - **Friction points** — where do users drop off, and how do you minimize that? Example flow: > User lands on homepage → clicks "Try it" → pastes their data → sees result in <30 seconds → decides to create account ### 5. User Journey Map Key touchpoints and interactions across the user lifecycle. **New User (Day 1):** - Discovers product via [channel] - Takes [first action] - Achieves [first success] **Returning User (Week 1):** - Key repeated action they perform - Features they explore - Integrations or customizations they set up **Power User (Month 1+):** - Advanced features they rely on - Workflows they've established - How they'd describe the product to others ### 6. Feature Touchpoints Map where users encounter key features in their journey: | Feature | When Encountered | User Need at That Moment | |---------|------------------|--------------------------| | [Feature 1] | [Journey stage] | [What they're trying to do] | | [Feature 2] | [Journey stage] | [What they're trying to do] | ## Multi-Persona Products If your product serves multiple distinct user types: 1. **Identify the primary persona first** — who must you serve to survive? 2. **Document secondary personas separately** — one file per persona 3. **Note conflicts** — where persona needs clash, document the tradeoff 4. **Prioritize ruthlessly** — you can't optimize for everyone simultaneously ## Output Location Place persona docs at: - `docs/PERSONA.md` — single file for simple products - `docs/personas/` — directory for multiple personas Keep it in the repo so it evolves with the product. ## Quality Criteria A good persona doc should: - Be **specific** enough that two team members would build the same feature from it - Include **evidence** — data, quotes, or observations, not just assumptions - Be **actionable** — reading it should change how you build - Be **maintained** — outdated personas are worse than none - Be **honest** — don't describe aspirational users; describe actual users ## NEVER Do 1. **NEVER skip personas for a new product** — building without knowing your user is guessing, and guessing is expensive 2. **NEVER describe users as demographics alone** — "25-34 male" tells you nothing about what they need; describe behaviors and goals 3. **NEVER create personas in isolation** — involve the team; one person's assumptions become the whole product's blind spots 4. **NEVER treat personas as permanent** — users change, markets shift; review personas quarterly 5. **NEVER create more than 3 personas initially** — if you try to serve everyone, you serve no one; start with your primary user 6. **NEVER write aspirational personas** — document who actually uses your product, not who you wish did

path: README.md
content: # Persona Docs

Create user-centered documentation that defines who a product is for and how they interact with it. Persona docs establish the foundation for product-driven development — every feature decision, design choice, and prioritization call flows from understanding your users.

## What's Inside

- Core components: Target User Profile, User Needs and Pain Points, Discovery Path, Onboarding Flow, User Journey Map, Feature Touchpoints
- Process for analyzing codebases and asking clarifying questions
- Multi-persona product guidance (primary vs secondary personas, conflict resolution)
- Quality criteria for effective persona documentation
- Template reference file for full structure
- Output location conventions

## When to Use

- Creating persona docs or documenting target users
- Defining user journeys or onboarding flows
- Starting a new product and needing to define its audience
- Before major feature planning to validate features serve actual users
- New team member onboarding for user context

## Installation

```bash
npx add https://github.com/wpank/ai/tree/main/skills/writing/persona-docs
```

### OpenClaw / Moltbot / Clawbot

```bash
npx clawhub@latest install persona-docs
```

### Manual Installation

#### Cursor (per-project)

From your project root:

```bash
mkdir -p .cursor/skills
cp -r ~/.ai-skills/skills/writing/persona-docs .cursor/skills/persona-docs
```

#### Cursor (global)

```bash
mkdir -p ~/.cursor/skills
cp -r ~/.ai-skills/skills/writing/persona-docs ~/.cursor/skills/persona-docs
```

#### Claude Code (per-project)

From your project root:

```bash
mkdir -p .claude/skills
cp -r ~/.ai-skills/skills/writing/persona-docs .claude/skills/persona-docs
```

#### Claude Code (global)

```bash
mkdir -p ~/.claude/skills
cp -r ~/.ai-skills/skills/writing/persona-docs ~/.claude/skills/persona-docs
```

## Related Skills

- **game-changing-features** — Use personas to inform high-leverage feature decisions
- **brainstorming** — Explore ideas with persona context in mind

---

Part of the [Writing](..) skill category.


path: references/template.md
content: # Persona Doc Template

Use this template to create persona documentation. Replace bracketed placeholders with actual content. Delete sections that don't apply, but try to cover each area even briefly.

---

# [Product Name] - Persona Documentation

## Target User

**Who they are:** [Role, job title, or description - e.g., "Solo developers building side projects", "Marketing managers at mid-size companies"]

**Background:** [Their technical level, industry, typical workday]

**Context:** [When/where they'd use this product - at work, on mobile, during specific tasks]

## Problems Solved

**Pain points:**
- [Problem 1 - what frustrates them today]
- [Problem 2 - what takes too long or is too hard]
- [Problem 3 - what they wish existed]

**Why existing solutions fail:** [What alternatives exist and why they're insufficient]

## Discovery

**How they find us:**
- [Channel 1 - e.g., "Google search for [problem]"]
- [Channel 2 - e.g., "Recommendation from colleague"]
- [Channel 3 - e.g., "Blog post about [topic]"]

**What convinces them to try:** [The hook - what makes them click "sign up" or "download"]

## Onboarding

**First encounter:** [Landing page, app store, GitHub README - what do they see first]

**Registration/Login:** [Simplest viable auth - email-only? OAuth? No account needed?]

**Time to value:** [How quickly can they experience the core benefit - seconds, minutes, days?]

**First success moment:** [The specific action that makes them think "this is useful"]

Example:
> User lands on homepage → clicks "Try it" → pastes their data → sees result in <30 seconds → decides to create account

## User Journey

### New User (Day 1)
- Discovers product via [channel]
- [First action]
- [Second action]
- Achieves [first success]

### Returning User (Week 1)
- [Key repeated action]
- [Feature they explore]
- [Integration or customization]

### Power User (Month 1+)
- [Advanced features used]
- [Workflows established]
- [How they'd describe product to others]

## Feature Touchpoints

Map where users encounter key features:

| Feature | When Encountered | User Need at That Moment |
|---------|------------------|--------------------------|
| [Feature 1] | [Journey stage] | [What they're trying to do] |
| [Feature 2] | [Journey stage] | [What they're trying to do] |

---

## Tips

- **Start minimal**: A few sentences per section beats an empty doc
- **Be specific**: "Developers" is too broad; "Backend engineers debugging production issues" is useful
- **Update often**: Revisit as you learn more about actual users
- **One persona first**: If you have multiple user types, document the primary one first


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: suspicious | SkillSpector: clean (LOW)