🎁 Get the FREE AI Skills Starter Guide β€” Subscribe β†’
BytesAgainBytesAgain
BytesAgain β€Ί Skills β€Ί AI Persona Engine
πŸ¦€ ClawHub

AI Persona Engine

by @spfadvisors

Create and customize AI personas with voice, face, personality, memory, and cross-platform behavior using an interactive wizard and safe update tools.

Versionv2.1.0
Downloads511
#clawhub
TERMINAL
clawhub install persona-engine

πŸ“– About This Skill

AI Persona Engine

Skill Name: ai-persona-engine Version: 2.0 Author: SPFAdvisors

Create a fully realized AI persona β€” voice, face, personality, and memory β€” in under 5 minutes.

Quick Start

# Install from ClawHub
clawhub install ai-persona-engine
Create your first persona

openclaw persona create
That's it. The wizard handles everything.

Commands

persona create

Interactive wizard that walks through persona creation step by step.

openclaw persona create
With flags

openclaw persona create --dry-run          # Show what would be generated
openclaw persona create --workspace=~/.openclaw/workspace-new

The wizard covers 7 steps:

1. Name & Identity β€” name, emoji, description, nickname 2. Personality β€” archetype selection, blending, communication style, relationship boundaries 3. Voice β€” provider selection (ElevenLabs, Grok TTS, built-in), voice testing 4. Visual Identity β€” appearance description, reference image generation 5. Your Context β€” USER.md with your name, timezone, preferences 6. Memory β€” daily notes, long-term curation, heartbeat maintenance 7. Platforms β€” channel selection and per-channel behavior

Output: SOUL.md, USER.md, IDENTITY.md, MEMORY.md, AGENTS.md, HEARTBEAT.md, and updated openclaw.json.

persona update

Modify specific persona fields without re-running the full wizard. Includes safe update pipeline with automatic backup and diff preview.

# Update voice provider
openclaw persona update --voice-provider elevenlabs --voice-id abc123
Add or remove personality traits

openclaw persona update --add-trait "sarcastic" --remove-trait "formal"
Update appearance and regenerate reference image

openclaw persona update --appearance "new description..." --regen-image
Regenerate SOUL.md from current config (with backup + diff)

openclaw persona update --regen-soul
Force regeneration (skip diff review)

openclaw persona update --regen-soul --force
Interactive mode (step-by-step, choose what to change)

openclaw persona update -i

Safe Update Pipeline: Before any --regen operation, the tool: 1. Creates .persona-backup/ with current files 2. Regenerates the target file 3. Shows a diff of what changed 4. Asks for confirmation (or use --force to skip)

persona export

Package the persona into a portable .persona bundle.

# Basic export (no memory, no API keys)
openclaw persona export
Include memory files

openclaw persona export --name pepper-backup --include-memory
Include voice config (still excludes API keys)

openclaw persona export --include-voice-config
Export from a specific workspace

openclaw persona export --workspace ~/.openclaw/workspace-ultron

persona import

Import a .persona bundle into a workspace.

# Interactive import (confirms each file)
openclaw persona import pepper.persona
Import into a specific workspace

openclaw persona import pepper.persona --workspace ~/.openclaw/workspace-new
Overwrite existing files without prompting

openclaw persona import pepper.persona --force

persona preview

Generate sample conversations showing how the persona would respond. Template-based, no LLM calls.

# Preview from config
python3 scripts/persona-preview.py --archetype companion --name "Pepper" --emoji "🌢️"
Preview from workspace

python3 scripts/persona-preview.py --workspace ~/.openclaw/workspace
Preview from profile JSON

python3 scripts/persona-preview.py --input persona-config.json

Shows 4 scenarios: greeting, asking for help, user mistake, emotional moment.

persona migrate

Reverse-engineer a persona config from existing workspace files.

# Migrate workspace to config JSON
python3 scripts/persona-migrate.py --workspace ~/.openclaw/workspace
Output to file

python3 scripts/persona-migrate.py --workspace ~/.openclaw/workspace --output persona-config.json

See references/migration-guide.md for detailed migration instructions.

persona validate

Check workspace for missing or malformed persona files.

python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace
With config validation

python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace --config ~/.openclaw/openclaw.json
JSON output for scripting

python3 scripts/persona-validate.py --workspace ~/.openclaw/workspace --json

persona diff

Compare current workspace files against what the generator would produce.

python3 scripts/persona-diff.py --workspace ~/.openclaw/workspace --config ~/.openclaw/openclaw.json

persona list

List all personas across workspaces.

python3 scripts/persona-list.py
JSON output

python3 scripts/persona-list.py --json

persona fleet

Show a fleet view of all agents across machines.

python3 scripts/persona-fleet.py
JSON output

python3 scripts/persona-fleet.py --json

voice audition

Audition multiple voices for a provider.

# List ElevenLabs voices
python3 scripts/voice-setup.py --audition --provider elevenlabs
Filter by gender

python3 scripts/voice-setup.py --audition --provider elevenlabs --gender female
List built-in voices

python3 scripts/voice-setup.py --audition --provider builtin

Personality Blending

Create hybrid personalities by blending multiple archetypes with weighted percentages.

# During wizard: choose "Blend with a second archetype" option
openclaw persona create
Programmatically:

cat > blend-profile.json << 'EOF'
{
    "name": "Muse",
    "emoji": "🎨",
    "archetypes": [
        {"name": "companion", "weight": 0.7},
        {"name": "creative", "weight": 0.3}
    ]
}
EOF
python3 scripts/generate-soul.py --input blend-profile.json --output SOUL.md

Blending merges:

  • Traits: Combined from both profiles, weighted by presence
  • Brevity: Weighted average (e.g., 0.7Γ—3 + 0.3Γ—4 = 3.3 β†’ 3)
  • Emotional depth: Weighted average mapped to levels
  • Vibe summaries: Concatenated from both profiles
  • Platform notes: Combined, deduplicated

    • Community Templates

    Pre-built personality profiles for common use cases in assets/community-templates/:

    | Template | Description | |----------|-------------| | financial-advisor | Informed, cautious, data-driven financial guide | | fitness-coach | Motivating, knowledgeable, encouraging workout companion | | kids-tutor | Patient, fun, age-appropriate learning buddy (ages 6-12) | | creative-writer | Lyrical, perceptive collaborative writing partner | | sales-rep | Persuasive, empathetic, goal-oriented sales professional | | therapist | Empathetic, boundaried emotional wellness companion | | gaming-buddy | Enthusiastic, strategic, competitive gaming partner | | executive-assistant | Anticipatory, discreet, ultra-efficient EA |

    Use community templates directly or blend them with built-in archetypes:

    python3 scripts/generate-soul.py --archetype therapist --name "Sage" --emoji "🧘"

    File Structure

    ai-persona-engine/
β”œβ”€β”€ SKILL.md                     # This file
β”œβ”€β”€ DESIGN.md                    # Full design document
β”œβ”€β”€ scripts/
β”‚   β”œβ”€β”€ persona-create.sh        # Setup wizard (v2: blending, --dry-run, --workspace)
β”‚   β”œβ”€β”€ persona-update.sh        # Field updater (v2: safe update pipeline)
β”‚   β”œβ”€β”€ persona-export.sh        # Bundle exporter (v2: cross-workspace)
β”‚   β”œβ”€β”€ persona-import.sh        # Bundle importer (v2: cross-workspace)
β”‚   β”œβ”€β”€ persona-preview.py       # [NEW] Sample conversation generator
β”‚   β”œβ”€β”€ persona-migrate.py       # [NEW] Reverse-engineer config from workspace
β”‚   β”œβ”€β”€ persona-validate.py      # [NEW] Workspace validation
β”‚   β”œβ”€β”€ persona-diff.py          # [NEW] Diff workspace vs generated
β”‚   β”œβ”€β”€ persona-list.py          # [NEW] List all personas across workspaces
β”‚   β”œβ”€β”€ persona-fleet.py         # [NEW] Fleet view of all agents
β”‚   β”œβ”€β”€ generate-soul.py         # SOUL.md generator (v2: blending support)
β”‚   β”œβ”€β”€ generate-user.py         # USER.md generator
β”‚   β”œβ”€β”€ generate-identity.py     # IDENTITY.md generator
β”‚   β”œβ”€β”€ generate-memory.py       # MEMORY.md + memory/ scaffolding
β”‚   β”œβ”€β”€ voice-setup.py           # Voice provider config (v2: --audition)
β”‚   β”œβ”€β”€ image-setup.py           # Image provider config + reference image
β”‚   └── lib/
β”‚       β”œβ”€β”€ providers.py         # Provider abstraction layer
β”‚       β”œβ”€β”€ templates.py         # Template engine + personality blending
β”‚       β”œβ”€β”€ config.py            # openclaw.json helpers
β”‚       └── prompts.py           # Wizard prompt definitions
β”œβ”€β”€ references/
β”‚   β”œβ”€β”€ voice-providers.md       # Voice provider setup guide
β”‚   β”œβ”€β”€ image-providers.md       # Image provider setup guide
β”‚   β”œβ”€β”€ personality-archetypes.md # Archetype reference
β”‚   β”œβ”€β”€ soul-writing-guide.md    # SOUL.md writing tips
β”‚   β”œβ”€β”€ config-schema.md         # openclaw.json schema reference
β”‚   └── migration-guide.md       # [NEW] Migration guide for existing users
β”œβ”€β”€ assets/
β”‚   β”œβ”€β”€ personality-profiles/    # JSON presets per archetype (5 built-in)
β”‚   β”œβ”€β”€ community-templates/     # [NEW] 8 community personality profiles
β”‚   └── templates/               # Handlebars templates for generated files
└── tests/
    β”œβ”€β”€ test-generators.py       # 77 unit tests (v2: blending, migration, etc.)
    β”œβ”€β”€ test-wizard.sh
    └── test-export-import.sh

    Configuration

    The persona engine adds a persona section to openclaw.json. Key fields:

    | Field | Type | Description | |-------|------|-------------| | persona.name | string | Agent's display name | | persona.emoji | string | Agent's emoji identifier | | persona.identity | object | Creature type, vibe, nickname | | persona.voice | object | Voice provider and settings | | persona.image | object | Image provider and canonical look | | persona.personality | object | Archetype, traits, communication style | | persona.personality.archetypes | array | [NEW] Blend sources with weights | | persona.memory | object | Memory capture and curation settings |

    See references/config-schema.md for the full schema.

    Dependencies

    Required:

  • OpenClaw (any version with skill support)
  • Python 3.9+
  • Node.js 22+

    • Optional (based on chosen providers):

  • ElevenLabs API key (voice)
  • Gemini API key (image generation)
  • xAI API key (Grok TTS / Grok Imagine)
  • ffmpeg (audio format conversion for WhatsApp voice messages)

    • Further Reading

  • Voice Providers Guide
  • Image Providers Guide
  • Personality Archetypes
  • SOUL.md Writing Guide
  • Config Schema Reference
  • Migration Guide
  • Design Document

    • πŸ’‘ Examples

    # Install from ClawHub
clawhub install ai-persona-engine
    Create your first persona
    
openclaw persona create
    That's it. The wizard handles everything.

    βš™οΈ Configuration

    The persona engine adds a persona section to openclaw.json. Key fields:

    | Field | Type | Description | |-------|------|-------------| | persona.name | string | Agent's display name | | persona.emoji | string | Agent's emoji identifier | | persona.identity | object | Creature type, vibe, nickname | | persona.voice | object | Voice provider and settings | | persona.image | object | Image provider and canonical look | | persona.personality | object | Archetype, traits, communication style | | persona.personality.archetypes | array | [NEW] Blend sources with weights | | persona.memory | object | Memory capture and curation settings |

    See references/config-schema.md for the full schema.