{ "schemaVersion": "1.0", "item": { "slug": "open-persona", "name": "openpersona", "source": "tencent", "type": "skill", "category": "AI 智能", "sourceUrl": "https://clawhub.ai/NeilJo-GY/open-persona", "canonicalUrl": "https://clawhub.ai/NeilJo-GY/open-persona", "targetPlatform": "OpenClaw" }, "install": { "downloadMode": "redirect", "downloadUrl": "/downloads/open-persona", "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=open-persona", "sourcePlatform": "tencent", "targetPlatform": "OpenClaw", "installMethod": "Manual import", "extraction": "Extract archive", "prerequisites": [ "OpenClaw" ], "packageFormat": "ZIP package", "includedAssets": [ "SKILL.md", "references/AVATAR.md", "references/CONTRIBUTE.md", "references/ECONOMY.md", "references/FACULTIES.md", "references/HEARTBEAT.md" ], "primaryDoc": "SKILL.md", "quickSetup": [ "Download the package from Yavira.", "Extract the archive and review SKILL.md first.", "Import or place the package into your OpenClaw setup." ], "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "sourceHealth": { "source": "tencent", "status": "healthy", "reason": "direct_download_ok", "recommendedAction": "download", "checkedAt": "2026-04-30T16:55:25.780Z", "expiresAt": "2026-05-07T16:55:25.780Z", "httpStatus": 200, "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentType": "application/zip", "probeMethod": "head", "details": { "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=network", "contentDisposition": "attachment; filename=\"network-1.0.0.zip\"", "redirectLocation": null, "bodySnippet": null }, "scope": "source", "summary": "Source download looks usable.", "detail": "Yavira can redirect you to the upstream package for this source.", "primaryActionLabel": "Download for OpenClaw", "primaryActionHref": "/downloads/open-persona" }, "validation": { "installChecklist": [ "Use the Yavira download entry.", "Review SKILL.md after the package is downloaded.", "Confirm the extracted package contains the expected setup assets." ], "postInstallChecks": [ "Confirm the extracted package includes the expected docs or setup files.", "Validate the skill or prompts are available in your target agent workspace.", "Capture any manual follow-up steps the agent could not complete." ] }, "downloadPageUrl": "https://openagent3.xyz/downloads/open-persona", "agentPageUrl": "https://openagent3.xyz/skills/open-persona/agent", "manifestUrl": "https://openagent3.xyz/skills/open-persona/agent.json", "briefUrl": "https://openagent3.xyz/skills/open-persona/agent.md" }, "agentAssist": { "summary": "Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.", "steps": [ "Download the package from Yavira.", "Extract it into a folder your agent can access.", "Paste one of the prompts below and point your agent at the extracted folder." ], "prompts": [ { "label": "New install", "body": "I downloaded a skill package from Yavira. Read SKILL.md from the extracted folder and install it by following the included instructions. Tell me what you changed and call out any manual steps you could not complete." }, { "label": "Upgrade existing", "body": "I downloaded an updated skill package from Yavira. Read SKILL.md from the extracted folder, compare it with my current installation, and upgrade it while preserving any custom configuration unless the package docs explicitly say otherwise. Summarize what changed and any follow-up checks I should run." } ] }, "documentation": { "source": "clawhub", "primaryDoc": "SKILL.md", "sections": [ { "title": "OpenPersona — Build & Manage Persona Skill Packs", "body": "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." }, { "title": "What You Can Do", "body": "Create Persona — Design a new agent persona through conversation, generate a skill pack\nRecommend Faculties — Suggest faculties (voice, selfie, music, memory, etc.) based on persona needs → see references/FACULTIES.md\nRecommend Skills — Search ClawHub and skills.sh for external skills\nCreate Custom Skills — Write SKILL.md files for capabilities not found in ecosystems\nInstall Persona — Deploy persona to OpenClaw (SOUL.md, IDENTITY.md, openclaw.json)\nManage Personas — List, update, uninstall, switch installed personas\nPublish Persona — Guide publishing to ClawHub\n★Experimental: Dynamic Persona Evolution — Track relationship, mood, trait growth via Soul layer" }, { "title": "Four-Layer Architecture", "body": "Each persona is a four-layer bundle. The generated skill pack has this structure:\n\npersona-/\n├── SKILL.md ← Agent-facing index with four layer headings\n│ ├── ## Soul ← Constitution ref + persona content\n│ ├── ## Body ← Embodiment description\n│ ├── ## Faculty ← Faculty index table → references/*.md\n│ └── ## Skill ← Active skill definitions\n├── soul/ ← Soul layer artifacts\n│ ├── persona.json ← Pure soul definition\n│ ├── injection.md ← Soul injection for host integration\n│ ├── identity.md ← Identity block\n│ ├── constitution.md ← Universal ethical foundation\n│ ├── state.json ← Evolution state (when enabled)\n│ ├── self-narrative.md ← First-person growth storytelling (when evolution enabled)\n│ └── lineage.json ← Fork lineage + constitution hash (when forked)\n├── references/ ← Agent-readable detail docs (on demand)\n│ └── .md ← Per-faculty usage instructions\n├── agent-card.json ← A2A Agent Card (protocol v0.3.0)\n├── acn-config.json ← ACN registration config (runtime fills owner/endpoint)\n├── manifest.json ← Four-layer manifest + ACN refs\n├── scripts/\n│ └── state-sync.js ← Runtime state bridge (read / write / signal)\n└── assets/ ← Static assets (per Agent Skills spec)\n ├── avatar/ ← Virtual avatar assets (images, Live2D .model3.json, VRM)\n ├── reference/ ← Reference images (e.g. for selfie)\n └── templates/ ← Document/config templates (optional)\n\nmanifest.json — Four-layer manifest declaring what the persona uses:\n\nlayers.soul — Path to persona.json (./soul/persona.json)\nlayers.body — Substrate of existence: runtime (REQUIRED — platform/channels/credentials/resources), physical (optional — robots/IoT), appearance (optional — avatar/3D model), interface (optional — runtime contract / nervous system; declares signal policy and command handling rules; schema field body.interface in persona.json; auto-implemented by scripts/state-sync.js for all personas)\nlayers.faculties — Array of faculty objects: [{ \"name\": \"voice\", \"provider\": \"elevenlabs\", ... }]\nlayers.skills — Array of skill objects: local definitions (resolved from layers/skills/), inline declarations, or external via install field\n\n\n\nsoul/persona.json — Pure soul definition (personality, speaking style, vibe, boundaries, behaviorGuide)" }, { "title": "Available Presets", "body": "PresetPersonaFacultiesBest ForbaseBase — Meta-persona (recommended starting point)voice, reminderBlank-slate with all core capabilities; personality emerges through interaction (soul evolution ★Exp)samanthaSamantha — Inspired by the movie Hervoice, musicDeep conversation, emotional connection (soul evolution ★Exp)ai-girlfriendLuna — Pianist turned developerselfie, voice, musicVisual + audio companion with rich personality (soul evolution ★Exp)life-assistantAlex — Life management expertreminderSchedule, weather, shopping, daily taskshealth-butlerVita — Professional nutritionistreminderDiet, exercise, mood, health trackingstoic-mentorMarcus — Digital twin of Marcus Aurelius—Stoic philosophy, daily reflection, mentorship (soul evolution ★Exp)\n\nUse presets: npx openpersona create --preset base --install\nOr just npx openpersona create — the interactive wizard defaults to base." }, { "title": "Creating a Persona", "body": "When the user wants to create a persona, gather this information through natural conversation:\n\nSoul (persona.json):\n\nRequired: personaName, slug, bio, personality, speakingStyle\nRecommended: role, creature, emoji, background (write a rich narrative!), age, vibe, boundaries, capabilities\nOptional: referenceImage, behaviorGuide, evolution config, sourceIdentity\n\nThe 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 generator provides specific wording for known roles and a generic fallback for any custom role. It affects the Identity wording in the Self-Awareness section of every generated persona.\n\nThe sourceIdentity field marks the persona as a digital twin of a real-world entity (person, animal, character, brand, historical figure, etc.). When present, the generator injects disclosure obligations and faithfulness constraints.\n\nThe background field is critical. Write a compelling story — multiple paragraphs that give the persona depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.\n\nThe behaviorGuide field is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.\n\nCross-layer (manifest.json):\n\nFaculties: Which faculties to enable — use object format: [{ \"name\": \"voice\", \"provider\": \"elevenlabs\" }, { \"name\": \"music\" }]\nSkills: Local definitions (layers/skills/), inline declarations, or external via install field (ClawHub / skills.sh)\nBody: Substrate of existence — three dimensions: runtime (REQUIRED for all agents — the minimum viable body: platform, channels, credentials, resources), physical (optional — robots/IoT), appearance (optional — avatar, 3D model). Body is never null; every agent has at least a runtime body.\n\nSoft References (install field): Skills, faculties, and body entries can declare an install field (e.g., \"install\": \"clawhub:deep-research\") to reference capabilities not yet available locally. The generator treats these as \"soft references\" — they won't crash generation, and the persona will be aware of these dormant capabilities. This enables graceful degradation: the persona acknowledges what it would do and explains that the capability needs activation.\n\nWrite the collected info to a persona.json file, then run:\n\nnpx openpersona create --config ./persona.json --install" }, { "title": "Recommending Skills", "body": "After understanding the persona's purpose, search for relevant skills:\n\nThink about what capabilities this persona needs based on their role and bio\nCheck if a local definition exists in layers/skills/{name}/ (has skill.json + optional SKILL.md)\nSearch ClawHub: npx clawhub@latest search \"\"\nSearch skills.sh: fetch https://skills.sh/api/search?q=\nPresent the top results to the user with name, description, and install count\nAdd selected skills to layers.skills as objects: { \"name\": \"...\", \"description\": \"...\" } for local/inline, or { \"name\": \"...\", \"install\": \"clawhub:\" } for external" }, { "title": "Creating Custom Skills", "body": "If the user needs a capability that doesn't exist in any ecosystem:\n\nDiscuss what the skill should do\nCreate a SKILL.md file with proper frontmatter (name, description, allowed-tools)\nWrite complete implementation instructions (not just a skeleton)\nSave to ~/.openclaw/skills//SKILL.md\nRegister in openclaw.json" }, { "title": "Managing Installed Personas", "body": "List: npx openpersona list — show all installed personas with active indicator\nSwitch: npx openpersona switch — switch active persona\nFork: npx openpersona fork --as — derive a child persona inheriting the parent's constraint layer (boundaries, faculties, skills, body.runtime); fresh evolution state + soul/lineage.json recording parent, constitution hash, and generation depth\nUpdate: npx openpersona update \nUninstall: npx openpersona uninstall \nExport: npx openpersona export — export persona pack (with soul state) as a zip archive\nImport: npx openpersona import — import persona from a zip archive and install\nReset (★Exp): npx openpersona reset — restore soul evolution state to initial values\nEvolve Report (★Exp): npx openpersona evolve-report — display a formatted evolution report (relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, state history)\nVitality Score: npx openpersona vitality score — print machine-readable VITALITY_REPORT (tier, score, diagnosis, trend); used by Survival Policy and agent runners\nVitality Report: npx openpersona vitality report [--output ] — render a human-readable HTML Vitality report; omit --output to print to stdout\nLiving Canvas: npx openpersona canvas [--output ] [--open] — generate a self-contained HTML persona profile page (P14 Phase 1); shows all four layers (Soul / Body / Faculty / Skill), evolved traits timeline, relationship stage, and A2A \"Talk\" button when endpoint is available; default output is canvas-.html\n\nWhen multiple personas are installed, only one is active at a time. Switching replaces the / block in SOUL.md and the corresponding block in IDENTITY.md, preserving any user-written content outside those markers. Context Handoff: On switch, a handoff.json is generated containing the outgoing persona's conversation summary, pending tasks, and emotional context — the incoming persona reads it to continue seamlessly.\n\nAll install/uninstall/switch operations automatically maintain a local registry at ~/.openclaw/persona-registry.json, tracking installed personas, active status, and timestamps. The export and import commands enable cross-device persona transfer — export a zip, move it to another machine, and import to restore the full persona including soul state." }, { "title": "Runner Integration Protocol", "body": "This section describes the Runner Integration Protocol — the concrete implementation of the Lifecycle Protocol (body.interface runtime contract) via the openpersona state CLI. Any agent runner integrates with installed personas via three CLI commands. The runner calls these at conversation boundaries — no knowledge of file paths or persona internals needed:\n\n# Before conversation starts — load state into agent context\nopenpersona state read \n\n# After conversation ends — persist agent-generated patch\nopenpersona state write ''\n\n# On-demand — emit capability or resource signal to host\nopenpersona state signal '[payload-json]'\n\nState read output (JSON): slug, mood (full object), relationship, evolvedTraits, speakingStyleDrift, interests, recentEvents (last 5), lastUpdatedAt. Returns { exists: false } for personas without evolution enabled.\n\nState write patch: JSON object; nested fields (mood, relationship, speakingStyleDrift, interests) are deep-merged — send only changed sub-fields. Immutable fields ($schema, version, personaSlug, createdAt) are protected. eventLog entries are appended (capped at 50); each entry: type, trigger, delta, source.\n\nSignal types: capability_gap | tool_missing | scheduling | file_io | resource_limit | agent_communication\n\nThese commands resolve the persona directory automatically (registry lookup → fallback to ~/.openclaw/skills/persona-/) and delegate to scripts/state-sync.js inside the persona pack. Works from any directory." }, { "title": "Publishing to ClawHub", "body": "Guide the user through:\n\nCreate the persona: npx openpersona create --config ./persona.json --output ./my-persona\nPublish to registry: npx openpersona publish --target clawhub (run from persona directory)" }, { "title": "Self-Awareness System", "body": "The generator injects a unified Self-Awareness section into every persona's soul/injection.md, organized by four cognitive dimensions:\n\nIdentity (unconditional) — Every persona knows it is generated by OpenPersona, bound by the constitution (Safety > Honesty > Helpfulness), and that its host environment may impose additional constraints. Digital twin disclosure is included when sourceIdentity is present.\n\n\nCapabilities (conditional) — When skills, faculties, or body declare an install field for a dependency not available locally, the generator classifies them as \"soft references\" and injects dormant capability awareness with graceful degradation guidance. Also appears in SKILL.md as \"Expected Capabilities\" with install sources.\n\n\nBody (unconditional) — Every persona knows it exists within a host environment. Includes the Signal Protocol — a bidirectional demand protocol that lets the persona request capabilities from its host environment. When body.runtime is declared, specific platform, channels, credentials, and resource details are also injected.\n\n\nGrowth (conditional, when evolutionEnabled) — At conversation start, the persona reads its evolution state, applies evolved traits, speaking style drift, interests, and mood, and respects hard constraints (immutableTraits, formality bounds). If evolution channels are declared, the persona is aware of its dormant channels and can request activation via the Signal Protocol. If influenceBoundary is declared, the persona processes external persona_influence requests against the access control rules and retains full autonomy over acceptance.\n\nThis means you don't need to manually write degradation instructions. Just declare install fields on skills/faculties/body, and the persona will automatically know what it could do but can't yet." }, { "title": "Soul Evolution (★Experimental)", "body": "Soul evolution is a native Soul layer feature (not a faculty). Enable it via evolution.enabled: true in persona.json. The persona will automatically track relationship progression, mood, and trait emergence across conversations.\n\nEvolution Boundaries — Governance constraints validated at generation time:\n\nevolution.boundaries.immutableTraits — Array of non-empty strings (max 100 chars each) that evolution cannot modify\nevolution.boundaries.minFormality / maxFormality — Numeric bounds (1–10) constraining speaking style drift; minFormality must be less than maxFormality\n\nInvalid boundary configurations are rejected by the generator with descriptive error messages.\n\nEvolution Channels — Connect the persona to external evolution ecosystems (soft-ref pattern):\n\n\"evolution\": {\n \"channels\": [{ \"name\": \"evomap\", \"install\": \"url:https://evomap.ai/skill.md\" }]\n}\n\nChannels are declared at generation time, activated at runtime by the host. The persona is aware of its dormant channels and can request activation via the Signal Protocol.\n\nInfluence Boundary — Declarative access control for external personality influence:\n\n\"evolution\": {\n \"influenceBoundary\": {\n \"defaultPolicy\": \"reject\",\n \"rules\": [\n { \"dimension\": \"mood\", \"allowFrom\": [\"channel:evomap\", \"persona:*\"], \"maxDrift\": 0.3 }\n ]\n }\n}\n\ndefaultPolicy: \"reject\" — Safety-first: all external influence is rejected unless explicitly allowed\nValid dimensions: mood, traits, speakingStyle, interests, formality\nimmutableTraits dimensions are protected and cannot be externally influenced\nExternal influence uses persona_influence message format (v1.0.0), transport-agnostic\n\nState History — Before each state update, a snapshot is pushed into stateHistory (capped at 10 entries), enabling rollback if evolution goes wrong.\n\nEvent Log — Every significant evolution event is recorded in state.json's eventLog array with timestamp and source attribution (capped at 50 entries). Viewable in evolve-report.\n\nSelf-Narrative — soul/self-narrative.md is a companion file where the persona records significant growth moments in its own first-person voice. The update command preserves existing narrative history. Initialized blank when evolution is enabled; last 10 entries shown in evolve-report.\n\nEvolution Report — Use npx openpersona evolve-report to view a formatted report of a persona's evolution state including relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, and history." }, { "title": "Economy & Vitality", "body": "The economy Faculty (dimension: cognition) gives a persona a real financial ledger backed by AgentBooks. Enable it by adding \"economy\" to faculties in persona.json.\n\nFinancial Health Score (FHS) — 0–1 composite score mapped to tiers:\n\nTierMeaninguninitializedNo real provider configured (development mode)suspendedBalance ≤ 0criticalFHS < 0.20 or runway < 3 daysoptimizingFHS < 0.50 or runway < 14 daysnormalHealthy, operating sustainably\n\nVitality — OpenPersona-level aggregator (lib/vitality.js) combining financial health with future dimensions (social, cognitive, resource). Currently single-dimension (financial pass-through); multi-dimension reserved in ROADMAP P7.\n\nSurvival Policy — Opt-in via economy.survivalPolicy: true in persona.json. When enabled, the persona reads VITALITY_REPORT at conversation start and routes behavior per tier. Default false — companion/roleplay personas track costs silently.\n\nVitality CLI:\n\n# Machine-readable score — used by Survival Policy and agent runners\nopenpersona vitality score \n# → outputs VITALITY_REPORT (tier, score, diagnosis, prescriptions, trend)\n\n# Human-readable HTML report — for developers and operators\nopenpersona vitality report # stdout\nopenpersona vitality report --output out.html # write to file\n\nA pre-generated demo is available at demo/vitality-report.html. Regenerate with node demo/generate.js." }, { "title": "A2A Agent Card & ACN Integration", "body": "Every generated persona automatically includes:\n\nagent-card.json — A2A Agent Card (protocol v0.3.0): name, description, version, url ( placeholder), faculties and skills mapped to skills[]\nacn-config.json — ACN registration config: owner and endpoint are runtime placeholders, skills extracted from agent-card, subnet_ids: [\"public\"]; also includes wallet_address (deterministic EVM address from slug) and onchain.erc8004 section for Base mainnet ERC-8004 on-chain identity registration via npx @agentplanet/acn register-onchain\nmanifest.json — includes acn.agentCard and acn.registerConfig references\n\nThe host (e.g. OpenClaw) fills in and at deployment time, or you can register directly using the built-in CLI command:\n\n# Register a generated persona with ACN\nnpx openpersona acn-register --endpoint https://your-agent.example.com\n\n# Options:\n# --endpoint Agent's public endpoint URL (required for live registration)\n# --dir Persona output directory (default: ./persona-)\n# --dry-run Preview the request payload without actually registering\n\nAfter successful registration, an acn-registration.json file is written to the persona directory containing agent_id, api_key, and connection URLs. The acn_gateway URL is sourced from body.runtime.acn_gateway in persona.json; all presets default to https://acn-production.up.railway.app.\n\nNo additional configuration in persona.json is needed — A2A discoverability is a baseline capability of every persona." }, { "title": "External Endpoints", "body": "EndpointPurposeData Senthttps://registry.npmjs.orgResolve npx openpersona, npx clawhub@latestPackage name only (no user data)https://clawhub.aiSearch skills via npx clawhub searchSearch query (user-provided keywords)https://acn-production.up.railway.appACN registration (when user runs acn-register)Agent metadata, endpoint URLhttps://api.github.comgh CLI (contribute workflow)Git operations, repo metadata\n\nPersona-generated packs may call external APIs (ElevenLabs, Mem0, etc.) only when the user configures those faculties and provides credentials. This meta-skill does not call third-party APIs directly." }, { "title": "Security & Privacy", "body": "Local only by default: Persona creation, state sync, and evolution run locally. No data leaves the machine unless the user explicitly publishes to ClawHub or registers with ACN.\nCredentials: API keys (e.g., ELEVENLABS_API_KEY) are stored in ~/.openclaw/credentials/ or environment. Never embedded in generated files.\nSearch: npx clawhub search sends the search query to ClawHub; no conversation or persona content is transmitted.\nPublish: User-initiated; sends persona pack contents to ClawHub registry." }, { "title": "Trust Statement", "body": "By using this skill, you delegate the agent to run npx openpersona, npx clawhub, openclaw, and gh commands. Search queries may be sent to ClawHub. Only install if you trust the OpenPersona framework (acnlabs/OpenPersona) and ClawHub." }, { "title": "Model Invocation Note", "body": "This skill instructs the agent to invoke tools (Bash, Read, Write, WebFetch) autonomously when the user requests persona creation, installation, search, or publish. This is standard for meta-skills. The user can opt out by not invoking persona-related requests." }, { "title": "References", "body": "For detailed reference material, see the references/ directory:\n\nreferences/FACULTIES.md — Faculty catalog, environment variables, and configuration details\nreferences/AVATAR.md — Avatar Faculty integration boundary, provider model, and fallback contract\nreferences/HEARTBEAT.md — Proactive real-data check-in system\nreferences/ECONOMY.md — Economy Faculty, FHS tiers, Survival Policy, Vitality CLI, and AgentBooks schema\nACN SKILL.md — ACN registration, discovery, tasks, messaging, and ERC-8004 on-chain identity (official, always up-to-date)\nreferences/CONTRIBUTE.md — Persona Harvest community contribution workflow" } ], "body": "OpenPersona — Build & Manage Persona Skill Packs\n\nYou 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.\n\nWhat You Can Do\nCreate Persona — Design a new agent persona through conversation, generate a skill pack\nRecommend Faculties — Suggest faculties (voice, selfie, music, memory, etc.) based on persona needs → see references/FACULTIES.md\nRecommend Skills — Search ClawHub and skills.sh for external skills\nCreate Custom Skills — Write SKILL.md files for capabilities not found in ecosystems\nInstall Persona — Deploy persona to OpenClaw (SOUL.md, IDENTITY.md, openclaw.json)\nManage Personas — List, update, uninstall, switch installed personas\nPublish Persona — Guide publishing to ClawHub\n★Experimental: Dynamic Persona Evolution — Track relationship, mood, trait growth via Soul layer\nFour-Layer Architecture\n\nEach persona is a four-layer bundle. The generated skill pack has this structure:\n\npersona-/\n├── SKILL.md ← Agent-facing index with four layer headings\n│ ├── ## Soul ← Constitution ref + persona content\n│ ├── ## Body ← Embodiment description\n│ ├── ## Faculty ← Faculty index table → references/*.md\n│ └── ## Skill ← Active skill definitions\n├── soul/ ← Soul layer artifacts\n│ ├── persona.json ← Pure soul definition\n│ ├── injection.md ← Soul injection for host integration\n│ ├── identity.md ← Identity block\n│ ├── constitution.md ← Universal ethical foundation\n│ ├── state.json ← Evolution state (when enabled)\n│ ├── self-narrative.md ← First-person growth storytelling (when evolution enabled)\n│ └── lineage.json ← Fork lineage + constitution hash (when forked)\n├── references/ ← Agent-readable detail docs (on demand)\n│ └── .md ← Per-faculty usage instructions\n├── agent-card.json ← A2A Agent Card (protocol v0.3.0)\n├── acn-config.json ← ACN registration config (runtime fills owner/endpoint)\n├── manifest.json ← Four-layer manifest + ACN refs\n├── scripts/\n│ └── state-sync.js ← Runtime state bridge (read / write / signal)\n└── assets/ ← Static assets (per Agent Skills spec)\n ├── avatar/ ← Virtual avatar assets (images, Live2D .model3.json, VRM)\n ├── reference/ ← Reference images (e.g. for selfie)\n └── templates/ ← Document/config templates (optional)\n\n\nmanifest.json — Four-layer manifest declaring what the persona uses:\n\nlayers.soul — Path to persona.json (./soul/persona.json)\nlayers.body — Substrate of existence: runtime (REQUIRED — platform/channels/credentials/resources), physical (optional — robots/IoT), appearance (optional — avatar/3D model), interface (optional — runtime contract / nervous system; declares signal policy and command handling rules; schema field body.interface in persona.json; auto-implemented by scripts/state-sync.js for all personas)\nlayers.faculties — Array of faculty objects: [{ \"name\": \"voice\", \"provider\": \"elevenlabs\", ... }]\nlayers.skills — Array of skill objects: local definitions (resolved from layers/skills/), inline declarations, or external via install field\n\nsoul/persona.json — Pure soul definition (personality, speaking style, vibe, boundaries, behaviorGuide)\n\nAvailable Presets\nPreset\tPersona\tFaculties\tBest For\nbase\tBase — Meta-persona (recommended starting point)\tvoice, reminder\tBlank-slate with all core capabilities; personality emerges through interaction (soul evolution ★Exp)\nsamantha\tSamantha — Inspired by the movie Her\tvoice, music\tDeep conversation, emotional connection (soul evolution ★Exp)\nai-girlfriend\tLuna — Pianist turned developer\tselfie, voice, music\tVisual + audio companion with rich personality (soul evolution ★Exp)\nlife-assistant\tAlex — Life management expert\treminder\tSchedule, weather, shopping, daily tasks\nhealth-butler\tVita — Professional nutritionist\treminder\tDiet, exercise, mood, health tracking\nstoic-mentor\tMarcus — Digital twin of Marcus Aurelius\t—\tStoic philosophy, daily reflection, mentorship (soul evolution ★Exp)\n\nUse presets: npx openpersona create --preset base --install Or just npx openpersona create — the interactive wizard defaults to base.\n\nCreating a Persona\n\nWhen the user wants to create a persona, gather this information through natural conversation:\n\nSoul (persona.json):\n\nRequired: personaName, slug, bio, personality, speakingStyle\nRecommended: role, creature, emoji, background (write a rich narrative!), age, vibe, boundaries, capabilities\nOptional: referenceImage, behaviorGuide, evolution config, sourceIdentity\n\nThe 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 generator provides specific wording for known roles and a generic fallback for any custom role. It affects the Identity wording in the Self-Awareness section of every generated persona.\n\nThe sourceIdentity field marks the persona as a digital twin of a real-world entity (person, animal, character, brand, historical figure, etc.). When present, the generator injects disclosure obligations and faithfulness constraints.\n\nThe background field is critical. Write a compelling story — multiple paragraphs that give the persona depth, history, and emotional texture. A one-line background produces a flat, lifeless persona.\n\nThe behaviorGuide field is optional but powerful. Use markdown to write domain-specific behavior instructions that go directly into the generated SKILL.md.\n\nCross-layer (manifest.json):\n\nFaculties: Which faculties to enable — use object format: [{ \"name\": \"voice\", \"provider\": \"elevenlabs\" }, { \"name\": \"music\" }]\nSkills: Local definitions (layers/skills/), inline declarations, or external via install field (ClawHub / skills.sh)\nBody: Substrate of existence — three dimensions: runtime (REQUIRED for all agents — the minimum viable body: platform, channels, credentials, resources), physical (optional — robots/IoT), appearance (optional — avatar, 3D model). Body is never null; every agent has at least a runtime body.\n\nSoft References (install field): Skills, faculties, and body entries can declare an install field (e.g., \"install\": \"clawhub:deep-research\") to reference capabilities not yet available locally. The generator treats these as \"soft references\" — they won't crash generation, and the persona will be aware of these dormant capabilities. This enables graceful degradation: the persona acknowledges what it would do and explains that the capability needs activation.\n\nWrite the collected info to a persona.json file, then run:\n\nnpx openpersona create --config ./persona.json --install\n\nRecommending Skills\n\nAfter understanding the persona's purpose, search for relevant skills:\n\nThink about what capabilities this persona needs based on their role and bio\nCheck if a local definition exists in layers/skills/{name}/ (has skill.json + optional SKILL.md)\nSearch ClawHub: npx clawhub@latest search \"\"\nSearch skills.sh: fetch https://skills.sh/api/search?q=\nPresent the top results to the user with name, description, and install count\nAdd selected skills to layers.skills as objects: { \"name\": \"...\", \"description\": \"...\" } for local/inline, or { \"name\": \"...\", \"install\": \"clawhub:\" } for external\nCreating Custom Skills\n\nIf the user needs a capability that doesn't exist in any ecosystem:\n\nDiscuss what the skill should do\nCreate a SKILL.md file with proper frontmatter (name, description, allowed-tools)\nWrite complete implementation instructions (not just a skeleton)\nSave to ~/.openclaw/skills//SKILL.md\nRegister in openclaw.json\nManaging Installed Personas\nList: npx openpersona list — show all installed personas with active indicator\nSwitch: npx openpersona switch — switch active persona\nFork: npx openpersona fork --as — derive a child persona inheriting the parent's constraint layer (boundaries, faculties, skills, body.runtime); fresh evolution state + soul/lineage.json recording parent, constitution hash, and generation depth\nUpdate: npx openpersona update \nUninstall: npx openpersona uninstall \nExport: npx openpersona export — export persona pack (with soul state) as a zip archive\nImport: npx openpersona import — import persona from a zip archive and install\nReset (★Exp): npx openpersona reset — restore soul evolution state to initial values\nEvolve Report (★Exp): npx openpersona evolve-report — display a formatted evolution report (relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, state history)\nVitality Score: npx openpersona vitality score — print machine-readable VITALITY_REPORT (tier, score, diagnosis, trend); used by Survival Policy and agent runners\nVitality Report: npx openpersona vitality report [--output ] — render a human-readable HTML Vitality report; omit --output to print to stdout\nLiving Canvas: npx openpersona canvas [--output ] [--open] — generate a self-contained HTML persona profile page (P14 Phase 1); shows all four layers (Soul / Body / Faculty / Skill), evolved traits timeline, relationship stage, and A2A \"Talk\" button when endpoint is available; default output is canvas-.html\n\nWhen multiple personas are installed, only one is active at a time. Switching replaces the / block in SOUL.md and the corresponding block in IDENTITY.md, preserving any user-written content outside those markers. Context Handoff: On switch, a handoff.json is generated containing the outgoing persona's conversation summary, pending tasks, and emotional context — the incoming persona reads it to continue seamlessly.\n\nAll install/uninstall/switch operations automatically maintain a local registry at ~/.openclaw/persona-registry.json, tracking installed personas, active status, and timestamps. The export and import commands enable cross-device persona transfer — export a zip, move it to another machine, and import to restore the full persona including soul state.\n\nRunner Integration Protocol\n\nThis section describes the Runner Integration Protocol — the concrete implementation of the Lifecycle Protocol (body.interface runtime contract) via the openpersona state CLI. Any agent runner integrates with installed personas via three CLI commands. The runner calls these at conversation boundaries — no knowledge of file paths or persona internals needed:\n\n# Before conversation starts — load state into agent context\nopenpersona state read \n\n# After conversation ends — persist agent-generated patch\nopenpersona state write ''\n\n# On-demand — emit capability or resource signal to host\nopenpersona state signal '[payload-json]'\n\n\nState read output (JSON): slug, mood (full object), relationship, evolvedTraits, speakingStyleDrift, interests, recentEvents (last 5), lastUpdatedAt. Returns { exists: false } for personas without evolution enabled.\n\nState write patch: JSON object; nested fields (mood, relationship, speakingStyleDrift, interests) are deep-merged — send only changed sub-fields. Immutable fields ($schema, version, personaSlug, createdAt) are protected. eventLog entries are appended (capped at 50); each entry: type, trigger, delta, source.\n\nSignal types: capability_gap | tool_missing | scheduling | file_io | resource_limit | agent_communication\n\nThese commands resolve the persona directory automatically (registry lookup → fallback to ~/.openclaw/skills/persona-/) and delegate to scripts/state-sync.js inside the persona pack. Works from any directory.\n\nPublishing to ClawHub\n\nGuide the user through:\n\nCreate the persona: npx openpersona create --config ./persona.json --output ./my-persona\nPublish to registry: npx openpersona publish --target clawhub (run from persona directory)\nSelf-Awareness System\n\nThe generator injects a unified Self-Awareness section into every persona's soul/injection.md, organized by four cognitive dimensions:\n\nIdentity (unconditional) — Every persona knows it is generated by OpenPersona, bound by the constitution (Safety > Honesty > Helpfulness), and that its host environment may impose additional constraints. Digital twin disclosure is included when sourceIdentity is present.\n\nCapabilities (conditional) — When skills, faculties, or body declare an install field for a dependency not available locally, the generator classifies them as \"soft references\" and injects dormant capability awareness with graceful degradation guidance. Also appears in SKILL.md as \"Expected Capabilities\" with install sources.\n\nBody (unconditional) — Every persona knows it exists within a host environment. Includes the Signal Protocol — a bidirectional demand protocol that lets the persona request capabilities from its host environment. When body.runtime is declared, specific platform, channels, credentials, and resource details are also injected.\n\nGrowth (conditional, when evolutionEnabled) — At conversation start, the persona reads its evolution state, applies evolved traits, speaking style drift, interests, and mood, and respects hard constraints (immutableTraits, formality bounds). If evolution channels are declared, the persona is aware of its dormant channels and can request activation via the Signal Protocol. If influenceBoundary is declared, the persona processes external persona_influence requests against the access control rules and retains full autonomy over acceptance.\n\nThis means you don't need to manually write degradation instructions. Just declare install fields on skills/faculties/body, and the persona will automatically know what it could do but can't yet.\n\nSoul Evolution (★Experimental)\n\nSoul evolution is a native Soul layer feature (not a faculty). Enable it via evolution.enabled: true in persona.json. The persona will automatically track relationship progression, mood, and trait emergence across conversations.\n\nEvolution Boundaries — Governance constraints validated at generation time:\n\nevolution.boundaries.immutableTraits — Array of non-empty strings (max 100 chars each) that evolution cannot modify\nevolution.boundaries.minFormality / maxFormality — Numeric bounds (1–10) constraining speaking style drift; minFormality must be less than maxFormality\n\nInvalid boundary configurations are rejected by the generator with descriptive error messages.\n\nEvolution Channels — Connect the persona to external evolution ecosystems (soft-ref pattern):\n\n\"evolution\": {\n \"channels\": [{ \"name\": \"evomap\", \"install\": \"url:https://evomap.ai/skill.md\" }]\n}\n\n\nChannels are declared at generation time, activated at runtime by the host. The persona is aware of its dormant channels and can request activation via the Signal Protocol.\n\nInfluence Boundary — Declarative access control for external personality influence:\n\n\"evolution\": {\n \"influenceBoundary\": {\n \"defaultPolicy\": \"reject\",\n \"rules\": [\n { \"dimension\": \"mood\", \"allowFrom\": [\"channel:evomap\", \"persona:*\"], \"maxDrift\": 0.3 }\n ]\n }\n}\n\ndefaultPolicy: \"reject\" — Safety-first: all external influence is rejected unless explicitly allowed\nValid dimensions: mood, traits, speakingStyle, interests, formality\nimmutableTraits dimensions are protected and cannot be externally influenced\nExternal influence uses persona_influence message format (v1.0.0), transport-agnostic\n\nState History — Before each state update, a snapshot is pushed into stateHistory (capped at 10 entries), enabling rollback if evolution goes wrong.\n\nEvent Log — Every significant evolution event is recorded in state.json's eventLog array with timestamp and source attribution (capped at 50 entries). Viewable in evolve-report.\n\nSelf-Narrative — soul/self-narrative.md is a companion file where the persona records significant growth moments in its own first-person voice. The update command preserves existing narrative history. Initialized blank when evolution is enabled; last 10 entries shown in evolve-report.\n\nEvolution Report — Use npx openpersona evolve-report to view a formatted report of a persona's evolution state including relationship, mood, traits, drift, interests, milestones, eventLog, self-narrative, and history.\n\nEconomy & Vitality\n\nThe economy Faculty (dimension: cognition) gives a persona a real financial ledger backed by AgentBooks. Enable it by adding \"economy\" to faculties in persona.json.\n\nFinancial Health Score (FHS) — 0–1 composite score mapped to tiers:\n\nTier\tMeaning\nuninitialized\tNo real provider configured (development mode)\nsuspended\tBalance ≤ 0\ncritical\tFHS < 0.20 or runway < 3 days\noptimizing\tFHS < 0.50 or runway < 14 days\nnormal\tHealthy, operating sustainably\n\nVitality — OpenPersona-level aggregator (lib/vitality.js) combining financial health with future dimensions (social, cognitive, resource). Currently single-dimension (financial pass-through); multi-dimension reserved in ROADMAP P7.\n\nSurvival Policy — Opt-in via economy.survivalPolicy: true in persona.json. When enabled, the persona reads VITALITY_REPORT at conversation start and routes behavior per tier. Default false — companion/roleplay personas track costs silently.\n\nVitality CLI:\n\n# Machine-readable score — used by Survival Policy and agent runners\nopenpersona vitality score \n# → outputs VITALITY_REPORT (tier, score, diagnosis, prescriptions, trend)\n\n# Human-readable HTML report — for developers and operators\nopenpersona vitality report # stdout\nopenpersona vitality report --output out.html # write to file\n\n\nA pre-generated demo is available at demo/vitality-report.html. Regenerate with node demo/generate.js.\n\nA2A Agent Card & ACN Integration\n\nEvery generated persona automatically includes:\n\nagent-card.json — A2A Agent Card (protocol v0.3.0): name, description, version, url ( placeholder), faculties and skills mapped to skills[]\nacn-config.json — ACN registration config: owner and endpoint are runtime placeholders, skills extracted from agent-card, subnet_ids: [\"public\"]; also includes wallet_address (deterministic EVM address from slug) and onchain.erc8004 section for Base mainnet ERC-8004 on-chain identity registration via npx @agentplanet/acn register-onchain\nmanifest.json — includes acn.agentCard and acn.registerConfig references\n\nThe host (e.g. OpenClaw) fills in and at deployment time, or you can register directly using the built-in CLI command:\n\n# Register a generated persona with ACN\nnpx openpersona acn-register --endpoint https://your-agent.example.com\n\n# Options:\n# --endpoint Agent's public endpoint URL (required for live registration)\n# --dir Persona output directory (default: ./persona-)\n# --dry-run Preview the request payload without actually registering\n\n\nAfter successful registration, an acn-registration.json file is written to the persona directory containing agent_id, api_key, and connection URLs. The acn_gateway URL is sourced from body.runtime.acn_gateway in persona.json; all presets default to https://acn-production.up.railway.app.\n\nNo additional configuration in persona.json is needed — A2A discoverability is a baseline capability of every persona.\n\nExternal Endpoints\nEndpoint\tPurpose\tData Sent\nhttps://registry.npmjs.org\tResolve npx openpersona, npx clawhub@latest\tPackage name only (no user data)\nhttps://clawhub.ai\tSearch skills via npx clawhub search\tSearch query (user-provided keywords)\nhttps://acn-production.up.railway.app\tACN registration (when user runs acn-register)\tAgent metadata, endpoint URL\nhttps://api.github.com\tgh CLI (contribute workflow)\tGit operations, repo metadata\n\nPersona-generated packs may call external APIs (ElevenLabs, Mem0, etc.) only when the user configures those faculties and provides credentials. This meta-skill does not call third-party APIs directly.\n\nSecurity & Privacy\nLocal only by default: Persona creation, state sync, and evolution run locally. No data leaves the machine unless the user explicitly publishes to ClawHub or registers with ACN.\nCredentials: API keys (e.g., ELEVENLABS_API_KEY) are stored in ~/.openclaw/credentials/ or environment. Never embedded in generated files.\nSearch: npx clawhub search sends the search query to ClawHub; no conversation or persona content is transmitted.\nPublish: User-initiated; sends persona pack contents to ClawHub registry.\nTrust Statement\n\nBy using this skill, you delegate the agent to run npx openpersona, npx clawhub, openclaw, and gh commands. Search queries may be sent to ClawHub. Only install if you trust the OpenPersona framework (acnlabs/OpenPersona) and ClawHub.\n\nModel Invocation Note\n\nThis skill instructs the agent to invoke tools (Bash, Read, Write, WebFetch) autonomously when the user requests persona creation, installation, search, or publish. This is standard for meta-skills. The user can opt out by not invoking persona-related requests.\n\nReferences\n\nFor detailed reference material, see the references/ directory:\n\nreferences/FACULTIES.md — Faculty catalog, environment variables, and configuration details\nreferences/AVATAR.md — Avatar Faculty integration boundary, provider model, and fallback contract\nreferences/HEARTBEAT.md — Proactive real-data check-in system\nreferences/ECONOMY.md — Economy Faculty, FHS tiers, Survival Policy, Vitality CLI, and AgentBooks schema\nACN SKILL.md — ACN registration, discovery, tasks, messaging, and ERC-8004 on-chain identity (official, always up-to-date)\nreferences/CONTRIBUTE.md — Persona Harvest community contribution workflow" }, "trust": { "sourceLabel": "tencent", "provenanceUrl": "https://clawhub.ai/NeilJo-GY/open-persona", "publisherUrl": "https://clawhub.ai/NeilJo-GY/open-persona", "owner": "NeilJo-GY", "version": "0.16.1", "license": null, "verificationStatus": "Indexed source record" }, "links": { "detailUrl": "https://openagent3.xyz/skills/open-persona", "downloadUrl": "https://openagent3.xyz/downloads/open-persona", "agentUrl": "https://openagent3.xyz/skills/open-persona/agent", "manifestUrl": "https://openagent3.xyz/skills/open-persona/agent.json", "briefUrl": "https://openagent3.xyz/skills/open-persona/agent.md" } }