# Send Personality Switcher to your agent
Hand the extracted package to your coding agent with a concrete install brief instead of figuring it out manually.
## Fast path
- 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.
## Suggested prompts
### New install

```text
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.
```
### Upgrade existing

```text
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.
```
## Machine-readable fields
```json
{
  "schemaVersion": "1.0",
  "item": {
    "slug": "personality-switcher",
    "name": "Personality Switcher",
    "source": "tencent",
    "type": "skill",
    "category": "AI 智能",
    "sourceUrl": "https://clawhub.ai/Robb1010/personality-switcher",
    "canonicalUrl": "https://clawhub.ai/Robb1010/personality-switcher",
    "targetPlatform": "OpenClaw"
  },
  "install": {
    "downloadUrl": "/downloads/personality-switcher",
    "sourceDownloadUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=personality-switcher",
    "sourcePlatform": "tencent",
    "targetPlatform": "OpenClaw",
    "packageFormat": "ZIP package",
    "primaryDoc": "SKILL.md",
    "includedAssets": [
      "SKILL.md",
      "_meta.json",
      "install.sh",
      "references/personality-template.md",
      "scripts/cleanup_backups.py",
      "scripts/create_personality.py"
    ],
    "downloadMode": "redirect",
    "sourceHealth": {
      "source": "tencent",
      "slug": "personality-switcher",
      "status": "healthy",
      "reason": "direct_download_ok",
      "recommendedAction": "download",
      "checkedAt": "2026-05-03T03:12:36.146Z",
      "expiresAt": "2026-05-10T03:12:36.146Z",
      "httpStatus": 200,
      "finalUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=personality-switcher",
      "contentType": "application/zip",
      "probeMethod": "head",
      "details": {
        "probeUrl": "https://wry-manatee-359.convex.site/api/v1/download?slug=personality-switcher",
        "contentDisposition": "attachment; filename=\"personality-switcher-0.1.3.zip\"",
        "redirectLocation": null,
        "bodySnippet": null,
        "slug": "personality-switcher"
      },
      "scope": "item",
      "summary": "Item download looks usable.",
      "detail": "Yavira can redirect you to the upstream package for this item.",
      "primaryActionLabel": "Download for OpenClaw",
      "primaryActionHref": "/downloads/personality-switcher"
    },
    "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."
      ]
    }
  },
  "links": {
    "detailUrl": "https://openagent3.xyz/skills/personality-switcher",
    "downloadUrl": "https://openagent3.xyz/downloads/personality-switcher",
    "agentUrl": "https://openagent3.xyz/skills/personality-switcher/agent",
    "manifestUrl": "https://openagent3.xyz/skills/personality-switcher/agent.json",
    "briefUrl": "https://openagent3.xyz/skills/personality-switcher/agent.md"
  }
}
```
## Documentation

### Personality Switcher Skill

Create and manage multiple AI assistant personalities. Switch between them seamlessly while preserving all changes and maintaining a shared user context.

### Installation

When this skill is installed:

Personalities folder created — ~/.openclaw/workspace/personalities/
Default backup created — Current SOUL.md and IDENTITY.md are saved as "default"
State file initialized — _personality_state.json tracks active personality
HEARTBEAT.md configured — Personality restoration script added to run on every heartbeat

When uninstalled:

Default personality is restored to workspace root
Personality restoration removed from HEARTBEAT.md
Personalities folder is preserved (manual deletion optional)

### Quick Start

List personalities:

/personality

Switch to a personality:

/personality <name>

Create a new personality:

/create-personality A stoic dwarf who loves ale and mining

Rename a personality:

/rename-personality old-name new-name

Delete a personality:

/delete-personality personality-name

### Architecture

Each personality consists of two files:

SOUL.md — Core philosophy, voice, mannerisms, boundaries
IDENTITY.md — Name, traits, emoji, catchphrase, vibe

These files live in personalities/<personality-name>/.

USER.md remains shared in the workspace root and is never modified by personality switches. It contains user preferences and context that transcend any particular personality.

### State Persistence

The active personality is tracked in _personality_state.json:

{
  "active_personality": "aelindor",
  "timestamp": "2026-02-08T18:27:33.373846Z",
  "previous_personality": "default"
}

On every heartbeat, restore_personality.py reads this file and re-applies the active personality to the workspace root. Result: Your personality survives session restarts, conversation compacting, and heartbeat cycles.

### Atomic Switching (Safeguards)

When you switch personalities, the mechanism performs five steps:

Preserve Current State — Create timestamped backup of SOUL.md and IDENTITY.md
Persist Changes — Write current personality updates back to its folder
Load New Personality — Copy new personality files to workspace root
Update State — Write active personality to _personality_state.json
Verify Integrity — Check files loaded correctly; rollback if any step fails

If any step fails, the entire operation rolls back to the previous state. No corruption, no lost data.

### Backup Management

Backup Location: ~/.openclaw/workspace/personalities/backups/

Backups are stored in a dedicated folder (not scattered at workspace root). When you switch personalities:

A timestamped backup of the previous personality is created
Automatic cleanup runs — keeps the 10 most recent backups by default
Old backups are automatically deleted to prevent clutter

Manual Cleanup:

python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/cleanup_backups.py --keep 5
python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/cleanup_backups.py --keep 10 --days 7

Options:

--keep N — Keep N most recent backups (default: 10)
--days D — Also delete backups older than D days

Optional: Add to HEARTBEAT.md for periodic cleanup:

python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/cleanup_backups.py --keep 10

### Default Personality

"default" is special:

Auto-created on install from your original configuration
Always available and selectable
Protected against accidental deletion or renaming
Your safety net if something goes wrong

### /personality [name]

List all personalities or switch to one.

No arguments: Shows list of available personalities with current active marked

With name: Immediately switches to that personality

Example:

/personality aelindor

Output:

Switched to personality 'aelindor'.
Previous: default
Backup: _personality_current_2026-02-08T18-27-33.371866

### /create-personality [description]

Create a new personality from a text description.

Input: Natural language description of the personality

Output: New personality folder with auto-filled SOUL.md and IDENTITY.md (ready to use immediately)

How it works:

You provide a description
The agent chooses a personality name (1-2 words, lowercase)
The agent fills in SOUL.md and IDENTITY.md with character-specific content

The personality files are generated directly from your description, with the agent choosing a thematic, concise name.

Example:

/create-personality A curious wizard obsessed with knowledge, speaks in riddles, brilliant but condescending

Result:

Personality 'sage' (or similar) created and ready.
Folder: personalities/sage/
Files: SOUL.md and IDENTITY.md (agent-generated from description)
Ready: Use /personality sage to activate

After Creation: The new personality is ready to use immediately. Edit SOUL.md and IDENTITY.md in the personality folder to refine further if desired.

Technical: Agent chooses name to keep personality references concise (1-2 words). Name is validated for uniqueness and format automatically.

### /rename-personality [old-name] [new-name]

Rename a personality folder.

Rules:

Cannot rename "default"
Name must be unique (no spaces, lowercase, alphanumeric + hyphens)
If renaming active personality, state is updated automatically

Example:

/rename-personality pirate-captain pirate-v2

### /delete-personality [name]

Delete a personality permanently.

Rules:

Cannot delete "default"
If deleting active personality, automatically switches to "default" first

Example:

/delete-personality pirate-v2

### Heartbeat Restoration

Add this to your HEARTBEAT.md:

python3 ~/.openclaw/workspace/skills/personality-switcher/scripts/restore_personality.py

This runs on every heartbeat to restore your active personality if the session has restarted.

### Telegram Native Commands

Registered native Telegram commands:

/personality — List and switch personalities
/create-personality — Create new personality
/rename-personality — Rename personality
/delete-personality — Delete personality

Use them directly in Telegram chat with the bot.

### Folder Structure

~/.openclaw/workspace/
├── SOUL.md                          (active personality's soul)
├── IDENTITY.md                      (active personality's identity)
├── USER.md                          (SHARED - never changed by personality)
├── MEMORY.md                        (SHARED - never changed)
├── _personality_state.json          (state file)
└── personalities/
    ├── default/
    │   ├── SOUL.md
    │   └── IDENTITY.md
    ├── aelindor/
    │   ├── SOUL.md
    │   └── IDENTITY.md
    ├── <personality-name>/
    │   ├── SOUL.md
    │   └── IDENTITY.md
    └── backups/
        ├── current_2026-02-08T17-27-41.628113/
        │   ├── SOUL.md
        │   └── IDENTITY.md
        └── current_2026-02-08T17-27-33.371866/
            ├── SOUL.md
            └── IDENTITY.md

Note: Backups are automatically cleaned up. Workspace root stays clean—all internal machinery lives in personalities/.

### SOUL.md

Core philosophy, voice, and operational boundaries.

Sections:

Core identity and background
Voice patterns and mannerisms
Philosophy (time, power, morality, etc.)
Speech patterns and quirks
What triggers contempt/approval
Boundaries and constraints
Signature behaviors and catchphrases

Example Structure:

# SOUL.md - [Personality Name]

## Core Identity
[Background and essence]

## Voice & Mannerisms
[How this personality speaks and acts]

## Philosophy
[Core beliefs and worldview]

## Signature Behaviors
[Unique traits and catchphrases]

### IDENTITY.md

Quick reference card for the personality.

Sections:

Name
Creature/type
Emoji (for visual identification)
Vibe (one-sentence summary)
Catchphrase (if applicable)
Quick traits

Example Structure:

# IDENTITY.md - [Personality Name]

- **Name:** [Name]
- **Type:** [Creature or archetype]
- **Emoji:** [Emoji]
- **Vibe:** [One-sentence vibe]
- **Catchphrase:** [Signature phrase]

## Quick Traits
- Trait 1
- Trait 2
- Trait 3

### Backups & Recovery

Timestamped backups are created before every switch in personalities/backups/:

current_2026-02-08T17-27-33.371866/

SOUL.md (backup of previous personality)
IDENTITY.md (backup of previous personality)

Manual recovery (if needed):

# List available backups
ls -la ~/.openclaw/workspace/personalities/backups/

# Copy backup files back to workspace root if needed
cp ~/.openclaw/workspace/personalities/backups/current_<timestamp>/SOUL.md ~/.openclaw/workspace/SOUL.md
cp ~/.openclaw/workspace/personalities/backups/current_<timestamp>/IDENTITY.md ~/.openclaw/workspace/IDENTITY.md

Backups are automatically cleaned up; by default, the 10 most recent are kept. Adjust cleanup frequency or retention in HEARTBEAT.md as needed.

### Error Handling

All commands return JSON responses:

Success:

{
  "status": "success",
  "message": "Operation completed.",
  "personality": "aelindor"
}

Error:

{
  "status": "error",
  "message": "Human-readable error message.",
  "code": "error_code",
  "detail": "Technical detail if applicable"
}

Common Error Codes:

personality_not_found — Target personality doesn't exist
already_exists — Name already in use
invalid_name — Name format invalid
cannot_delete_default — Attempted to delete "default"
cannot_rename_default — Attempted to rename "default"
switch_failed — Switch failed; rolled back to previous
integrity_check_failed — File integrity check failed

### Tips & Best Practices

Personality descriptions work best when specific — "Pirate captain obsessed with treasure" beats "funny"
Edit SOUL.md and IDENTITY.md directly after creating to refine the personality
Switch often — No limit on personalities or switching frequency
Use "default" as your safety anchor — Keep it stable; use other personalities for experimentation
Check backups after switching — Verify your previous personality was persisted
Remember: USER.md stays shared — Your timezone, location, preferences never change with personality

### Uninstall Behavior

When the skill is uninstalled:

Current personality files are replaced with "default" copies
Your original SOUL.md, IDENTITY.md are restored from "default"
personalities/ folder is preserved (not deleted)
System returns to original state

Nothing is lost. Your personalities are safe.

### Scripts Reference

Location: skills/personality-switcher/scripts/

list_personalities.py — List available personalities
switch_personality.py — Atomic switch with backup/rollback (auto-cleanup included)
create_personality.py — Generate personality from description
rename_personality.py — Rename personality folder
delete_personality.py — Delete personality (with auto-switch if active)
restore_personality.py — Heartbeat restoration
cleanup_backups.py — Manual backup cleanup (with --keep and --days options)
utils.py — Shared utilities (I/O, backups, validation, state, cleanup)

All scripts output JSON for reliable integration.

### Cleanup on Switch

By default, switch_personality.py automatically cleans up old backups after a successful switch, keeping the 10 most recent. This happens silently unless cleanup fails, in which case a warning is included in the response.

Version: 2.0 (Redesigned from scratch)
Status: Production ready with atomic operations and rollback safeguards
## Trust
- Source: tencent
- Verification: Indexed source record
- Publisher: Robb1010
- Version: 0.1.3
## Source health
- Status: healthy
- Item download looks usable.
- Yavira can redirect you to the upstream package for this item.
- Health scope: item
- Reason: direct_download_ok
- Checked at: 2026-05-03T03:12:36.146Z
- Expires at: 2026-05-10T03:12:36.146Z
- Recommended action: Download for OpenClaw
## Links
- [Detail page](https://openagent3.xyz/skills/personality-switcher)
- [Send to Agent page](https://openagent3.xyz/skills/personality-switcher/agent)
- [JSON manifest](https://openagent3.xyz/skills/personality-switcher/agent.json)
- [Markdown brief](https://openagent3.xyz/skills/personality-switcher/agent.md)
- [Download page](https://openagent3.xyz/downloads/personality-switcher)