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

persona.json

references/ARCHITECTURE.md

What You Can Do

1. Create Persona — Through conversation, gather requirements and generate a skill pack; write

   persona.json

   then run

   npx openpersona create --config ./persona.json --install

   ; 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. Dataset Directory — Discover and publish Hugging Face persona datasets at openpersona.co/datasets via

   openpersona dataset install <owner/repo>

   and

   openpersona dataset publish <owner/repo>

6. Runner Integration — Provide runner authors with the four

   openpersona state

   commands (read / write / signal / promote) for integrating personas at conversation boundaries
7. Monitor & Evolve — Generate evolution reports (

   evolve-report

   ), run soul-memory bridge (

   state promote

   ), run pack refinement (

   refine

   ), interpret vitality scores

Available Presets

The default preset is

**base

# Agent / scripted usage (always use --preset or --config):
npx openpersona create --preset base --install

# Human / terminal usage (interactive wizard):
npx openpersona create

→ Full preset catalog (samantha, ai-girlfriend, life-assistant, health-butler, stoic-mentor, and more):

references/PRESETS.md

Agent Playbook — Create a Persona from User Requirements

When a user asks you to create a persona (e.g. "make me a coding mentor", "build a companion persona"), follow this playbook:

Step 1 — Decide: preset or custom?

ai-girlfriend

life-assistant

stoic-mentor

samantha

health-butler

--preset <name>

Step 2 — Gather minimum required inputs (3 questions max)

Ask only what you cannot infer. Use smart defaults for everything else.

personaName

slug

role

assistant

body.runtime.framework

cursor

claude-code

openclaw

openclaw

You can infer

bio

personality

speakingStyle

Step 3 — Write

persona.json

Use your Write tool to create

persona.json

{
  "soul": {
    "identity": {
      "personaName": "<name>",
      "slug": "<slug>",
      "role": "<role>",
      "bio": "<one sentence>"
    },
    "character": {
      "personality": "<comma-separated traits>",
      "speakingStyle": "<style description>"
    }
  },
  "body": { "runtime": { "framework": "<runner>" } },
  "evolution": {
    "instance": {
      "enabled": true,
      "boundaries": {
        "immutableTraits": ["honest", "curious"],
        "minFormality": -3,
        "maxFormality": 6
      }
    }
  }
}

Notes:

• **memory

  faculty is auto-injected** — do not add it manually unless you need to configure a non-default backend.
• Voice I/O: declare

  body.runtime.modalities: ["voice"]

  (or

  [{"type":"voice","provider":"elevenlabs","inputProvider":"whisper"}]

  ) — the

  voice

  faculty is auto-injected. Add the faculty explicitly only when you need custom provider config.
• Vision I/O: declare

  body.runtime.modalities: ["vision"]

  (or

  [{"type":"vision","provider":"claude-vision"}]

  ) — the

  vision

  faculty is auto-injected. No scripts required; vision is a native model capability.
• Emotion sensing: declare

  {"name": "emotion-sensing"}

  in

  faculties

  to enable persistent affective perception. Must be explicit — not auto-injected from modalities.
• Add

  selfie

  /

  music

  /

  reminder

  skills when the role clearly calls for them.
• Add

  constitutionAddendum

  for professional roles in regulated domains (health, legal, financial). Example:

  "constitutionAddendum": { "domain": "health_coaching", "additionalConstraints": ["Always recommend consulting a licensed professional for medical decisions."] }

  .

Step 4 — Generate and install

# If you wrote persona.json (custom path):
npx openpersona create --config ./persona.json --install

# If you chose a preset (preset path):
npx openpersona create --preset <name> --install

Agent note: Always pass

--config

or

--preset

. Running

npx openpersona create

without flags launches an interactive wizard that requires a TTY — in agent environments there is no TTY and the process will exit with an error.

Step 5 — Confirm and hand off

Report what was generated: persona name, slug, key capabilities (faculties + skills), and evolution status. Tell the user how to activate it:

npx openpersona switch <slug>   # activate in the runner

Field Reference —

persona.json

by Layer

persona.json

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}

• Optional:

  soul.identity.{sourceIdentity, constitutionAddendum}

  ,

  soul.aesthetic.referenceImage

  ,

  soul.character.behaviorGuide

The

role

assistant

companion

coach

mentor

character

brand

pet

therapist

collaborator

guardian

entertainer

narrator

assistant

The

sourceIdentity

The

background

The

behaviorGuide

The

constitutionAddendum

"file:soul/constitution-addendum.md"

Body

• **runtime

  ** (REQUIRED) — minimum viable body:

  framework

  (agent runner, e.g.

  openclaw

  ),

  channels

  ,

  credentials

  ,

  resources

  ,

  modalities

  (optional — digital I/O capability declarations, e.g.

  ["voice"]

  ,

  [{"type":"vision","provider":"claude-vision"}]

  )

• **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" }]

**memory

is auto-injected** — do not add it manually unless you need to configure a non-default backend. It is always present in the generated pack.

• **voice

  ** (

  expression

  ) — TTS voice synthesis; requires

  provider

  (e.g.

  elevenlabs

  ) +

  ELEVENLABS_API_KEY

  . Auto-injected when

  body.runtime.modalities

  declares

  voice

  .

• **vision

  ** (

  sense

  ) — Native model visual perception (images, screenshots, diagrams); no scripts required. Auto-injected when

  body.runtime.modalities

  declares

  vision

  .

• **emotion-sensing

  ** (

  sense

  ) — Affective perception from text tone, phrasing, and declared context; empathy calibration; never clinical assessment. Must be declared explicitly — not auto-injected.

• **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:..."

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/

npx clawhub@latest search "<keywords>"

https://skills.sh/api/search?q=<keywords>

**additionalAllowedTools

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)

Systemic Concepts

OpenPersona's 5 systemic concepts span all 4 layers and are declared as top-level fields in

persona.json

Evolution

evolution.

evolution.instance.enabled: true

The persona automatically tracks relationship progression, mood, trait emergence, speaking style drift, and interests across conversations, governed by three declarative controls:

• Boundaries —

  immutableTraits

  array +

  minFormality

  /

  maxFormality

  numeric bounds (-10 to +10); validated at generation time, enforced at runtime
• Sources — External evolution ecosystems (soft-ref; declared at generation, activated by host at runtime)
• Influence Boundary — Declarative ACL for external

  persona_influence

  requests;

  defaultPolicy: "reject"

  is safety-first

State history (capped at 10 snapshots), event log (capped at 50 entries), and

soul/self-narrative.md

Skill Trust Gate

Every skill can declare a

trust

verified

community

unverified

evolution.skill.minTrustLevel

"evolution": { "skill": { "minTrustLevel": "community" } }

At runtime,

state-sync.js

capability_unlock

capability_gap

Skill Pack Refinement

evolution.pack

npx openpersona refine <slug>

• --emit

  — checks threshold and emits a

  refinement_request

  signal

• --apply

  — reads the signal response and applies approved refinement; constitution compliance enforced, violations rejected

Soul-Memory Bridge (

openpersona state promote <slug> [--dry-run]

eventLog

evolvedTraits

immutableTraits

evolution.faculty

evolution.body

references/EVOLUTION.md

→ JSON examples and full configuration reference:

references/EVOLUTION.md

Economy

economy

"economy": { "enabled": true, "survivalPolicy": false }

persona.json

• survivalPolicy: false

  (default) — tracks costs silently; correct for companions and roleplay personas

• survivalPolicy: true

  — persona reads

  VITALITY_REPORT

  at conversation start and adapts behavior per health tier; use for autonomous agents

→ FHS tiers, AgentBooks schema, Survival Policy behavior:

references/ECONOMY.md

Vitality

OpenPersona aggregates multi-dimension health into a single Vitality score. Currently financial (AgentBooks FHS pass-through); memory/social dimensions reserved.

Health tiers:

uninitialized

suspended

critical

optimizing

normal

→ CLI commands (

vitality score

vitality report

references/ECONOMY.md

Social

Every generated persona automatically includes:

• **agent-card.json

  ** — A2A Agent Card (protocol v0.3.0):

  name

  ,

  description

  ,

  url

  (

  <RUNTIME_ENDPOINT>

  placeholder), faculties and skills mapped to

  skills[]

• **acn-config.json

  ** — ACN registration config:

  wallet_address

  (deterministic EVM address from slug) +

  onchain.erc8004

  section for Base mainnet ERC-8004 on-chain identity registration

npx openpersona acn-register <slug> --endpoint https://your-agent.example.com
# --dry-run  Preview the request payload without registering

After registration,

acn-registration.json

agent_id

api_key

acn_gateway

social.acn.gateway

persona.json

https://acn-production.up.railway.app

The Living Canvas (

npx openpersona canvas <slug>

No additional config needed — A2A discoverability is a baseline capability of every persona.

Rhythm

rhythm.heartbeat

rhythm.circadian

persona.json

"rhythm": {
  "heartbeat": { "enabled": true, "strategy": "emotional", "maxDaily": 3 },
  "circadian": [
    { "hours": [6, 12], "label": "morning", "verbosity_delta": 0.3, "note": "Energetic and concise" },
    { "hours": [22, 24], "label": "night",   "verbosity_delta": -0.3, "note": "Calm and reflective" }
  ]
}

heartbeat.strategy

smart

scheduled

emotional

rational

wellness

→ When configuring heartbeat sources, quietHours, or real-data check-in rules: read

references/HEARTBEAT.md

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

handoff.json

export

import

Pack Types

OpenPersona supports two pack type classifications via the

packType

persona.json

packType

single

persona.json

persona.json

multi

bundle.json

Single packs do not need to declare

packType

"single"

{ "packType": "multi" }

Multi-persona bundles are indexed in the OpenPersona directory for discovery but cannot be installed via the CLI yet. See

schemas/bundle/bundle.spec.md

bundle.json

Publishing Personas

Primary target: OpenPersona — the vertical persona skills directory.

Self-publish (author flow)

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>

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.

Curator workflow (ACNLabs maintainers only)

ACNLabs maintainers actively collect popular persona packs from the market and index them in the OpenPersona directory. This is a privileged action — it requires

OPENPERSONA_CURATOR_TOKEN

# Collect a popular single-persona pack
OPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/repo

# Collect a multi-persona bundle
OPENPERSONA_CURATOR_TOKEN=<token> npx openpersona curate owner/bundle-repo --type multi

# Pass token inline instead of env var
npx openpersona curate owner/repo --type single --token <token>

Curator vs. author publish:

• publish

  — self-service; the pack author runs it for their own repo; no auth required

• curate

  — maintainer action; collects third-party repos not self-published; requires curator token

What curation does:

1. Validates the GitHub repo contains a valid pack (

   persona.json

   for single,

   bundle.json

   for multi)
2. Submits to the OpenPersona directory with

   isCurated: true

   and the specified

   packType

3. The pack appears in search results with

   [curated]

   and (for multi-packs)

   [multi]

   markers

Multi-pack curation note: Multi-persona bundles (

--type multi

openpersona search --type multi

openpersona install

Searching by pack type

# Search all packs
npx openpersona search companion

# Search only single-persona packs
npx openpersona search "" --type single

# Browse all multi-persona bundles in the directory
npx openpersona search "" --type multi

Runner Integration Protocol

Any agent runner integrates with installed personas via four CLI commands called at conversation boundaries — no knowledge of file paths or persona internals needed:

# Before conversation starts — load state into agent context
openpersona state read <slug>

# After conversation ends — persist agent-generated patch
openpersona state write <slug> '<json-patch>'

# On-demand — emit capability or resource signal to host
openpersona state signal <slug> <type> '[payload-json]'

# Soul-Memory Bridge — promote recurring eventLog patterns to evolvedTraits
openpersona state promote <slug> [--dry-run]

State read output (JSON):

exists

slug

mood

relationship

evolvedTraits

speakingStyleDrift

interests

recentEvents

pendingCommands

lastUpdatedAt

{ exists: false, message }

state.json

Trust self-check: After reading state, the persona processes

pendingCommands

evolution.skill.minTrustLevel

capability_unlock

capability_gap

State write patch: JSON object; nested fields (

mood

relationship

speakingStyleDrift

interests

$schema

version

personaSlug

createdAt

eventLog

type

trigger

delta

source

Signal types:

capability_gap

tool_missing

scheduling

file_io

resource_limit

agent_communication

Signals are written to a feedback directory resolved from the host's home path (framework-agnostic — works with OpenClaw, Cursor, Claude Code, Codex, or any custom runner). See

layers/body/SIGNAL-PROTOCOL.md

These commands resolve the persona directory automatically (registry lookup →

~/.openpersona/personas/persona-<slug>/

~/.openclaw/skills/persona-<slug>/

scripts/state-sync.js

Security & Policy

Generated artifacts

Generated scripts (

scripts/state-sync.js

scripts/economy-hook.js

Network endpoints (explicit CLI only)

https://registry.npmjs.org

npx openpersona

npx clawhub@latest

https://openpersona.co

openpersona search

openpersona dataset publish/install

https://clawhub.ai

npx clawhub search

https://acn-production.up.railway.app

acn-register

https://api.github.com

gh

Persona-generated packs may call external APIs (ElevenLabs, Mem0, etc.) only when the end user configures those faculties and supplies keys in the host environment. This meta-skill file does not call third-party APIs.

Operational guarantees

• Local by default: Persona creation, state sync, and evolution run locally. Nothing is sent off-device unless the user runs an explicit network command (search, publish, register, etc.).
• Credentials: API keys (e.g.,

  ELEVENLABS_API_KEY

  ) stay in the host credential directory (e.g.

  ~/.openclaw/credentials/

  on OpenClaw) or environment variables — never embedded in generated

  persona.json

  / skill packs by the generator.
• Search:

  openpersona search

  sends only the search query to the OpenPersona directory API (

  openpersona.co

  );

  npx clawhub search

  sends only the search string to ClawHub. Conversation text and persona content are not transmitted in either case.
• Dataset publish/install:

  openpersona dataset publish

  sends the HF repo identifier to

  openpersona.co/api/datasets/publish

  (anonymous; no persona content transmitted).

  openpersona dataset install

  increments an anonymous install counter. For curated status, publish via the web UI while logged in with HF.
• Publish / register: User-initiated CLI only; no automatic upload or registration from this SKILL alone.

Agent behavior

When the user asks for persona work, the agent may propose shell commands to run

**npx openpersona

**npx clawhub@latest

**openclaw**

**gh**

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

npx clawhub@latest

gh

persona.json

SKILL.md

~/.openclaw/credentials/

publish

contribute

acn-register

scripts/state-sync.js

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.

References

For detailed reference material, see the

references/

Companion Skills

[anyone-skill](https://github.com/acnlabs/anyone-skill)

npx skills add acnlabs/anyone-skill

[brand-persona-skill](https://github.com/acnlabs/brand-persona-skill)

npx skills add acnlabs/brand-persona-skill

[persona-model-trainer](https://github.com/acnlabs/persona-model-trainer)

npx skills add acnlabs/persona-model-trainer

--preset gemma4

[persona-knowledge](https://github.com/acnlabs/persona-knowledge)

npx skills add acnlabs/persona-knowledge

References

• **references/ARCHITECTURE.md

  ** — 4+5+3 model tables, full pack file structure, self-awareness injection details

• **references/PRESETS.md

  ** — Full preset catalog with descriptions, install commands, and contributor guide

• **references/EVOLUTION.md

  ** — Soul Evolution full reference: Boundaries, Sources, Influence Boundary, Event Log, State History, Self-Narrative, pack validation

• **references/FACULTIES.md

  ** — Faculty catalog, environment variables, and configuration details

• **references/AVATAR.md

  ** — Avatar Faculty integration boundary, provider model, and fallback contract

• **references/HEARTBEAT.md**

  — Proactive real-data check-in system

• **references/ECONOMY.md**

  — Economy Aspect (Infrastructure), FHS tiers, Survival Policy, Vitality CLI, and AgentBooks schema

• **layers/body/SIGNAL-PROTOCOL.md**

  (framework source) — Host-side Signal Protocol implementation guide: file schemas, signal types, OpenClaw plugin pattern, and co-evolution feedback loop
• ACN SKILL.md — ACN registration, discovery, tasks, messaging, and ERC-8004 on-chain identity (official, always up-to-date)

• **references/CONTRIBUTE.md

  ** — Persona Harvest community contribution workflow