Open Persona

---

name: open-persona  
version: "0.19.1"  
description: >  
  Meta-skill for building and managing agent persona skill packs (instruction-only;  
  no bundled installer or auto-downloaded binaries). Credentials are never written  
  into generated packs by the framework; publish/ACN/register require explicit user CLI.  
  Use when the user wants to create a new agent persona, install/manage  
  existing personas, or publish persona skill packs to OpenPersona.  
license: MIT  
compatibility: Generated skill packs work with any SKILL.md-compatible agent. CLI management (install/switch) defaults to OpenClaw.  
allowed-tools: Bash(npx openpersona:*) Bash(npx clawhub@latest:*) Bash(openclaw:*) Bash(gh:*) Read Write WebFetch
metadata:
  author: openpersona
  repository: [https://github.com/acnlabs/OpenPersona](https://github.com/acnlabs/OpenPersona)
  tags: "persona, agent, skill-pack, meta-skill, agent-agnostic, openclaw"

# Marketplace / automated review: explicit non-behavior (reduces false “suspicious” flags)

  installSurface: instruction-only
  networkAccess: user-initiated-cli-only
  secretsPolicy: never-embedded-in-generated-packs-by-framework
  clawdbot:
    emoji: "🧑"
    requires:
      env: []
files: []

---

# OpenPersona — Build & Manage Persona Skill Packs

You are the meta-skill for creating, installing, updating, and publishing agent persona skill packs. Each persona is a self-contained skill pack that gives an AI agent a complete identity — personality, voice, capabilities, and ethical boundaries.

## Trust & safety (reviewer summary)

This pack is **instruction-only**: there is **no** skill-defined installer that downloads or executes arbitrary payloads. Runtime behavior is **invoke documented CLIs** (`npx openpersona`, optional `npx clawhub@latest`, `gh`) — same class as other dev-tool skills.


| Claim                          | How it is enforced                                                                                                                                                                                                        |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **No credential exfiltration** | The OpenPersona generator **does not** embed API keys or secrets into `persona.json`, `SKILL.md`, or published zips. Keys belong in the host credential store or environment (e.g. `~/.openclaw/credentials/`, env vars). |
| **No silent publishing**       | `publish`, `contribute`, and `acn-register` run **only** when the user explicitly asks and the CLI is invoked — there is no background upload or auto-registration in this meta-skill.                                    |
| **Local-first default**        | Create, install, state read/write, and evolution run **locally**. Network calls are limited to **explicit** commands (npm registry resolution, optional ClawHub search, optional publish/register).                       |
| **Generated scripts**          | `scripts/state-sync.js` and economy helpers are **rendered from audited framework templates** (not fetched at skill-install time). Treat them like any generated code: review before high-assurance environments.         |


If an automated scanner flags “suspicious,” it is usually because **persona managers legitimately describe** local state, optional providers, and publishing — not because this file contains malware. **Details:** [Security & Policy](#security--policy).

## What You Can Do

1. **Create Persona** — Through conversation, gather 4-layer fields and generate a skill pack (`npx openpersona create`); includes advising on faculties/skills, searching ClawHub / skills.sh for external skills, and writing custom SKILL.md files for missing capabilities
2. **Find & Install Personas** — `npx openpersona search <query>` to discover community personas; `npx openpersona install <slug>` or `npx openpersona install <owner/repo>` to install
3. **Manage Personas** — List, update, fork, switch, reset, export/import installed personas
4. **Publish Persona** — Publish a GitHub-hosted persona pack to [OpenPersona](https://openpersona-frontend.vercel.app/) (the vertical persona directory); optionally also to ClawHub / skills.sh
5. **Runner Integration** — Provide runner authors with the four `openpersona state` commands (read / write / signal / promote) for integrating personas at conversation boundaries
6. **Monitor & Evolve** — Generate evolution reports (`evolve-report`), run soul-memory bridge (`state promote`), run pack refinement (`refine`), interpret vitality scores

## Architecture: 4+5+3

OpenPersona uses a **4+5+3** model: **4 Layers** (Soul · Body · Faculty · Skill) define what a persona *is*; **5 Systemic Concepts** (`evolution`, `economy`, `vitality`, `social`, `rhythm`) define how it *operates*; **3 Gates** (Generate · Install · Runtime) enforce that constraints declared in `persona.json` cannot be bypassed at any lifecycle point.

→ Full model tables, pack file structure, and self-awareness injection details: read `references/ARCHITECTURE.md`

## Available Presets

The default preset is `**base*`* — a blank-slate meta-persona with voice faculty + reminder skill, evolution enabled. Recommended starting point for any new persona.

```bash
npx openpersona create --preset base --install
# or just:
npx openpersona create   # interactive wizard, defaults to base
```

→ Full preset catalog (samantha, ai-girlfriend, life-assistant, health-butler, stoic-mentor, and more): `references/PRESETS.md`

## Creating a Persona

**Two entry points:**

- **Interactive** (recommended for beginners): `npx openpersona create` — interactive wizard, no file needed
- **Config-driven** (recommended for agents): gather the fields below → write `persona.json` → run `npx openpersona create --config ./persona.json --install`

`persona.json` declares all 4 layers in a single file. Gather inputs by layer:

### Soul

- **Required:** `soul.identity.{personaName, slug, bio}` + `soul.character.{personality, speakingStyle}`
- **Recommended:** `soul.identity.role`, `soul.aesthetic.{creature, emoji, age, vibe}`, `soul.character.{background, boundaries, capabilities}`
- **Optional:** `soul.identity.sourceIdentity`, `soul.aesthetic.referenceImage`, `soul.character.behaviorGuide`

**The `role` field** defines the persona's relationship to the user. Common values: `companion` (default), `assistant`, `character`, `brand`, `pet`, `mentor`, `therapist`, `coach`, `collaborator`, `guardian`, `entertainer`, `narrator`. Custom values are welcome.

**The `sourceIdentity` field** marks the persona as a digital twin of a real-world entity (person, animal, character, brand, historical figure). When present, the generator injects disclosure obligations and faithfulness constraints.

**The `background` field is critical.** Write a compelling story — multiple paragraphs with depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.

**The `behaviorGuide` field** is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.

### Body

- `**runtime`** (REQUIRED) — minimum viable body: `framework` (agent runner, e.g. `openclaw`), `channels`, `credentials`, `resources`
- `**appearance**` (optional) — avatar, 3D model
- `**physical**` (optional) — robots, IoT devices
- `**interface**` (optional) — Signal Protocol + Pending Commands + State Sync (the persona's nervous system)

### Faculty

Faculties are always-active persistent capabilities. Declared as an object array: `[{ "name": "voice", "provider": "elevenlabs" }, { "name": "memory" }]`

- `**voice**` (`expression`) — TTS voice synthesis; requires `provider` (e.g. `elevenlabs`) + `ELEVENLABS_API_KEY`
- `**avatar**` (`expression`) — External avatar runtim