Open Persona

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.

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.

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

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 runtime bridge; graceful text-only fallback when unavailable. → When configuring avatar (provider, Live2D/VRM, fallback rules): read references/AVATAR.md
• **memory** (cognition) — Cross-session recall via memories.jsonl; set top-level memory.inheritance: "copy" in persona.json to carry memories to child personas at fork. Connected to Soul-Memory Bridge (openpersona state promote).

Soft references: Faculties can declare "install": "clawhub:..." for capabilities not installed locally — the persona will be aware of the dormant capability and can request activation via the Signal Protocol.

Skill

Skills are on-demand actions. Declared as an object array in persona.json:

• Built-in: selfie · music · reminder
• Local: definitions in layers/skills/{name}/ (skill.json + optional SKILL.md)
• External: { "name": "...", "install": "clawhub:<slug>" } — add "trust": "verified"|"community"|"unverified" to participate in the Skill Trust Gate
• Soft references: External skills not installed locally → persona knows what it could do and degrades gracefully

To find external skills: check local layers/skills/, search ClawHub via npx clawhub@latest search "<keywords>", or fetch https://skills.sh/api/search?q=<keywords>.

**additionalAllowedTools** — extra tool permissions beyond what faculties contribute automatically.

For rhythm (heartbeat + circadian) configuration → see Systemic Concepts → Rhythm

Once all fields are gathered, write persona.json and run npx openpersona create --config ./persona.json --install.

Creating Custom Skills

If the user needs a capability not found in any ecosystem:

1. Discuss what the skill should do
2. Create a SKILL.md file with proper frontmatter (name, description, allowed-tools)
3. Write complete implementation instructions (not just a skeleton)
4. Save to ~/.openclaw/skills/<skill-name>/SKILL.md (OpenClaw) or your runner's skill directory
5. Register with your agent runner (e.g. add to openclaw.json for OpenClaw)

Managing Personas

Install & Discover

• Install: npx openpersona install <target> — install from registry slug or owner/repo; --registry <name> selects registry (acnlabs default)
• Search: npx openpersona search <query> — search personas in the registry
• List: npx openpersona list — show all installed personas with active indicator

Switch & Fork

• Switch: npx openpersona switch <slug> — switch active persona
• Fork: npx openpersona fork <parent-slug> --as <new-slug> — derive a child persona inheriting the parent's constraint layer (boundaries, faculties, skills, body.runtime); fresh evolution state + soul/lineage.json recording parent slug, constitution SHA-256 hash, generation depth, and parentPackRevision (when parent has meta)

Update & Maintain

• Update: npx openpersona update <slug> — regenerate from persona.json; preserves state.json, soul/self-narrative.md, and soul/lineage.json
• Reset: npx openpersona reset <slug> — restore soul evolution state to initial values
• Uninstall: npx openpersona uninstall <slug>

Migrate

• Export: npx openpersona export <slug> — export persona pack (with soul state) as a zip archive
• Import: npx openpersona import <file> — import persona from a zip archive and install

Reports & Analytics

• Evolve Report: npx openpersona evolve-report <slug> — formatted evolution report (relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, state history)
• Vitality Score: npx openpersona vitality score <slug> — machine-readable VITALITY_REPORT (tier, score, diagnosis, trend)
• Vitality Report: npx openpersona vitality report <slug> [--output <file>] — human-readable HTML Vitality report
• Living Canvas: npx openpersona canvas <slug> [--output <file>] [--open] — self-contained HTML persona profile page showing all four layers, evolved traits timeline, relationship stage, and A2A "Talk" button when endpoint is available (top-level CLI; conceptually Social expression, not Vitality)

Evolution Tools

• Soul-Memory Bridge: openpersona state promote <slug> [--dry-run] — promote recurring eventLog patterns to evolvedTraits → see Evolution
• Skill Pack Refinement: npx openpersona refine <slug> [--emit] [--apply] — evolve behavior guide → see Evolution

Community

• Contribute: npx openpersona contribute <slug> [--dry-run] — submit persona improvements as a PR to the community; --dry-run shows diff without creating PR; requires gh CLI. → For the full diff review and PR workflow: read references/CONTRIBUTE.md

When multiple personas are installed, only one is active at a time. All install/uninstall/switch operations maintain a local registry at ~/.openpersona/persona-registry.json; on OpenClaw, switching replaces the soul injection block in SOUL.md / IDENTITY.md (preserving user-written content outside the markers). Context Handoff: On switch, a handoff.json is generated with the outgoing persona's relationship stage, mood snapshot, and shared interests — the incoming persona reads it to continue seamlessly. The export and import commands enable cross-device persona transfer.

Publishing Personas

Primary target: OpenPersona — the vertical persona skills directory. Guide the user through:

1. Create the persona: npx openpersona create --config ./persona.json --output ./my-persona
2. Push the persona pack to a public GitHub repo (e.g. alice/my-persona)
3. Register with OpenPersona directory: npx openpersona publish alice/my-persona

The persona will appear in the OpenPersona leaderboard and be installable via npx openpersona install <slug> by anyone.

Persona packs can also be listed on general skill platforms (ClawHub, skills.sh) as supplementary distribution, but OpenPersona is the canonical home for persona-type skill packs.