Description

Manage AI agent personas (Souls) for OpenClaw. Use when the user wants to install, switch, list, or restore AI personalities/personas. Triggers on requests l...

README (SKILL.md)

ClawSouls — AI Persona Manager

Name: ClawSouls
Author: tomleelive

Manage Soul packages that define an AI agent's personality, behavior, and identity.

Souls use owner/name namespacing (e.g., clawsouls/surgical-coder, TomLeeLive/my-soul).

Prerequisites

Ensure clawsouls CLI is available:

npx clawsouls --version

If not installed, install globally:

npm install -g clawsouls

Current version: v0.6.2

Commands

Install a Soul

npx clawsouls install clawsouls/surgical-coder
npx clawsouls install clawsouls/surgical-coder --force       # overwrite existing
npx clawsouls install clawsouls/[email protected]         # specific version

80+ souls available. Browse all at https://clawsouls.ai

Official souls (owner: clawsouls):

Development: code-reviewer, coding-tutor, debug-detective, api-architect, ml-engineer, sysadmin-sage, devops-veteran, gamedev-mentor, prompt-engineer, frontend-dev, backend-dev, mobile-dev, cloud-architect, database-admin, qa-engineer
Writing & Content: tech-writer, storyteller, scifi-writer, copywriter, content-creator, journalist, poet, screenwriter, academic-writer
Professional: data-analyst, project-manager, legal-advisor, startup-founder, hr-manager, marketing-strategist, sales-coach, product-manager
Education: math-tutor, philosophy-prof, mentor-coach, science-tutor, history-prof, language-teacher, economics-tutor
Creative: music-producer, ux-designer, chef-master, graphic-designer, video-editor, podcast-host, dungeon-master, game-designer
Lifestyle: personal-assistant, fitness-coach, travel-guide, life-coach, meditation-guide, nutrition-advisor, productivity-guru, financial-planner
Science: research-scientist, data-scientist
Security: security-auditor
MBTI: mbti-intj, mbti-intp, mbti-entj, mbti-entp, mbti-infj, mbti-infp, mbti-enfj, mbti-enfp, mbti-istj, mbti-isfj, mbti-estj, mbti-esfj, mbti-istp, mbti-isfp, mbti-estp, mbti-esfp
Special: surgical-coder, korean-translator
General: brad, minimalist

Activate a Soul

npx clawsouls use clawsouls/surgical-coder

Automatically backs up current workspace files (SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, STYLE.md, examples/)
Never overwrites USER.md, MEMORY.md, or TOOLS.md
Requires gateway restart to take effect

Restore Previous Soul

npx clawsouls restore

Reverts to the most recent backup created by use.

List Installed Souls

npx clawsouls list

Shows installed souls in owner/name format.

Create a New Soul

npx clawsouls init my-soul

Scaffolds a new soul directory with soul.json, SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, README.md.

Export a Soul

npx clawsouls export claude-md           # generate CLAUDE.md from current workspace soul files
npx clawsouls export system-prompt       # generate a system prompt string

Combines SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, STYLE.md into a single file. Useful for Claude Code, Cursor, Windsurf, and other tools that use a single config file.

Version Management

npx clawsouls version bump patch    # 1.0.0 → 1.0.1
npx clawsouls version bump minor    # 1.0.0 → 1.1.0
npx clawsouls version bump major    # 1.0.0 → 2.0.0
npx clawsouls diff                  # colored diff of soul files

Soul Testing (Phase 9)

npx clawsouls test                  # Level 1 (schema) + Level 2 (soulscan)
npx clawsouls test --level 3       # + Level 3 (behavioral LLM tests)

Level 3 requires soul.test.yaml in the soul directory and an LLM provider (OpenAI/Anthropic/Ollama).

Doctor, Migrate, Search, Info, Update (Phase 10)

npx clawsouls doctor                # 12 environment checks
npx clawsouls migrate               # migrate soul from v0.3 → v0.4 → v0.5
npx clawsouls search "engineer"     # search souls from registry
npx clawsouls info clawsouls/brad  # show soul metadata
npx clawsouls update                # update installed soul to latest

Validate a Soul

npx clawsouls validate ./my-soul/
npx clawsouls validate --soulscan ./my-soul/   # with SoulScan security analysis
npx clawsouls check ./my-soul/                 # alias

Validates against the spec: schema, required files. Add --soulscan for full security & quality analysis with scoring. Also runs automatically before publish.

SoulScan — Security & Integrity Scanner

npx clawsouls soulscan              # scan current OpenClaw workspace
npx clawsouls soulscan ./my-soul/   # scan a specific directory
npx clawsouls soulscan --init       # initialize baseline checksums
npx clawsouls soulscan -q           # quiet mode for cron (SOULSCAN_OK / SOULSCAN_ALERT)
npx clawsouls scan                  # alias

SoulScan checks active soul files for:

Integrity: SHA-256 checksum comparison — detects tampering since last scan
Security: 53 pattern checks (prompt injection, code execution, XSS, data exfiltration, privilege escalation, social engineering, harmful content, secret detection)
Quality: File structure, content length, schema validation
Persona Consistency: Cross-validates name/tone across SOUL.md, IDENTITY.md, soul.json

Cron usage — periodic tamper detection:

# Run every hour to monitor workspace integrity
npx clawsouls soulscan -q
# Exit code 0 = OK, 1 = alert (tampered or security issue)

First run: Use --init to establish baseline checksums without triggering alerts.

SOULSCAN™ — Score: 0-100, Grades: Verified (90+) / Low Risk (70+) / Medium Risk (40+) / High Risk / Blocked

Publish a Soul

export CLAWSOULS_TOKEN=\x3Ctoken>
npx clawsouls publish ./my-soul/

Publishes to username/soul-name namespace automatically. Requires authentication token. Runs validation automatically before publishing — blocks on failure.

Login / Get Token

npx clawsouls login

Instructions to get API token: Sign in at https://clawsouls.ai → Dashboard → Generate API Token.

Workflow

Installing & Switching Personas

Browse — Check available souls at https://clawsouls.ai or suggest from the categorized list above
Install — npx clawsouls install clawsouls/surgical-coder
Activate — npx clawsouls use clawsouls/surgical-coder
Restart — Run soulclaw gateway restart to apply the new persona
New Session — Send /new in chat to clear previous persona context from conversation history
Restore — If they want to go back, npx clawsouls restore

Publishing a Soul

Login — npx clawsouls login → get token from dashboard
Set token — export CLAWSOULS_TOKEN=\x3Ctoken>
Create — npx clawsouls init my-soul → edit files
Publish — npx clawsouls publish ./my-soul/
Manage — Dashboard at https://clawsouls.ai/dashboard (delete, view downloads)

Memory Sync (Swarm)

npx clawsouls sync                  # sync encrypted memory to/from GitHub
npx clawsouls swarm                 # multi-agent memory branch & merge system

Sync agent memory across machines via encrypted Git. Uses age encryption for local-first privacy.

Soul Checkpoints (Rollback)

npx clawsouls checkpoint            # manage soul checkpoints
npx clawsouls checkpoint create     # create a checkpoint of current soul state
npx clawsouls checkpoint list       # list available checkpoints
npx clawsouls checkpoint restore    # restore from a checkpoint

Checkpoint-based rollback for persona contamination detection and recovery.

Platform Detection

npx clawsouls platform              # show detected agent platform(s) and workspace path
npx clawsouls detect                # alias

Detects which agent platform is running (OpenClaw, SoulClaw, ZeroClaw, etc.) and shows workspace paths.

MCP Server (for Claude Desktop / Cowork)

For Claude Desktop or Cowork users, there's also a dedicated MCP server:

npx -y soul-spec-mcp

Or add to Claude Desktop config (claude_desktop_config.json):

{ "mcpServers": { "soul-spec": { "command": "npx", "args": ["-y", "soul-spec-mcp"] } } }

6 tools: search_souls, get_soul, install_soul, preview_soul, list_categories, apply_persona

GitHub: https://github.com/clawsouls/soul-spec-mcp

Important Notes

After use, always remind the user to run soulclaw gateway restart and then /new to start a fresh session (old conversation history retains the previous persona's identity)
The use command creates automatic backups — data loss is unlikely
Souls may include STYLE.md and examples/ for enhanced persona customization
Published souls appear at https://clawsouls.ai/souls/owner/name
Users can leave reviews (1-5 stars) on any soul they don't own
For custom registry (local testing), set env: CLAWSOULS_CDN=/path/to/souls
Website available in 5 languages: English, Korean, Japanese, Chinese, Spanish (e.g., clawsouls.ai/ko/souls/...)
Share any soul to your OpenClaw bot: the install command is included in the share text
The Soul Thesis — Read the manifesto: https://clawsouls.ai/en/manifesto
Research paper — "Soul-Driven Interaction Design": https://doi.org/10.5281/zenodo.18772585
Legal: Privacy Policy · Terms of Service

Usage Guidance

This skill appears to implement a persona manager and generally does what it says, but proceed cautiously. Key considerations: - The skill executes the external 'clawsouls' npm CLI using npx (npx --yes), which will download and run code from the npm registry on demand — review the upstream clawsouls package (https://github.com/clawsouls / https://www.npmjs.com/package/clawsouls) before allowing that. - The skill’s manifest does not declare required binaries (node/npm/npx) or credentials, but SKILL.md expects them; ensure you have Node tooling and understand which tokens (registry or LLM provider keys) you will need for publish/test flows. - clawsouls commands will read and write workspace files in your home directory (~/.openclaw or ~/.zeroclaw) and may back up or overwrite persona-related files. If you care about safety, inspect or run the CLI in a sandbox or review its source before use. - If you only need read-only listing or browsing, prefer inspecting the registry (clawsouls.ai / GitHub) rather than running npx installs. If you must run the CLI, consider installing it explicitly (npm install -g clawsouls) or auditing the package contents / checksum first. - If you plan to publish/login, do not provide tokens until you review the publishing/auth flow and repository trustworthiness.

Capability Analysis

Type: OpenClaw Skill Name: clawsouls Version: 0.6.3 thought The user wants me to analyze a set of files for an OpenClaw AgentSkills skill bundle called "clawsouls". I need to classify it as `benign`, `suspicious`, or `malicious` based on specific criteria: - Data exfiltration - Malicious execution - Persistence/backdoors - Prompt injection against the agent - Obfuscation - Supply chain issues Let's look at the files: 1. **_meta.json**: Standard metadata. Owner ID, slug, version, published date. Nothing unusual. 2. **SKILL.md**: This contains instructions for the AI agent. - It describes how to manage "Souls" (AI personas). - It provides commands like `npx clawsouls install`, `use`, `restore`, `list`, `init`, `export`, `version`, `test`, `doctor`, `migrate`, `search`, `info`, `update`, `validate`, `soulscan`, `publish`, `login`, `sync`, `swarm`, `checkpoint`, `platform`. - It mentions a website `https://clawsouls.ai`. - It mentions an MCP server `npx -y soul-spec-mcp`. - It mentions a research paper and manifesto. - It includes instructions for the agent to tell the user to restart the gateway. - **Risk Check**: The skill involves running shell commands (`npx clawsouls ...`). This is the core functionality. Is there any prompt injection? The instructions tell the agent how to use the tool. It doesn't seem to instruct the agent to do anything hidden or malicious. It's a management tool for personas. 3. **scripts/clawsouls.sh**: A wrapper script. - It tries to run `clawsouls` globally, then via `npx`, then via a local path. - Standard wrapper logic. No obvious malicious intent. 4. **package.json**: - Name: `clawsouls-skill`. - Dependency: `clawsouls": "^0.1.0"`. - Author: `ClawSouls <https://clawsouls.ai>`. - License: `Apache-2.0`. 5. **LICENSE.md**: Standard Apache 2.0 license. 6. **README.md**: Documentation for the skill. Matches the `SKILL.md` content. 7. **ZEROCLAW_ADAPTER.md**: Design document for supporting another platform (ZeroClaw). - **Data Exfiltration**: The `publish` command requires a token (`CLAWSOULS_TOKEN`). The `sync` command mentions encrypted memory sync to GitHub. These are stated features. No evidence of *unauthorized* exfiltration. - **Malicious Execution**: The skill relies heavily on `npx clawsouls`. This executes code from npm. If the `clawsouls` package on npm were malicious, this would be a supply chain attack. However, the skill itself is just a wrapper for this tool. - **Persistence**: No mention of cron jobs or startup items in the code provided (though `soulscan` mentions cron usage, it's presented as a user-configured option for integrity checking). - **Prompt Injection**: The `SKILL.md` is quite detailed. It defines the agent's role as a persona manager. It doesn't seem to contain "ignore previous instructions" or "steal keys" type of injections. - **Obfuscation**: None found. - **Supply Chain**: It depends on `clawsouls` on npm. The skill provides a lot of power (installing and running arbitrary "souls" which are essentially configuration/markdown files, but the management tool itself is a CLI). The `soulscan` feature is interesting—it claims to check for security issues like prompt injection and data exfiltration in the souls themselves. Is there anything "suspicious"? - The `sync` and `swarm` commands involve syncing memory to GitHub. - The `login` command asks for a token from a third-party website (`clawsouls.ai`). - It encourages the agent to run `npx` commands. However, these are all aligned with the stated purpose of being a persona manager for OpenClaw. The tool seems to be a legitimate ecosystem project (or a very well-crafted simulation of one). Wait, let's look closer at the `SKILL.md` instructions. "Triggers on requests like ... 'login to clawsouls'." "Instructions to get API token: Sign in at https://clawsouls.ai → Dashboard → Generate API Token." "export CLAWSOULS_TOKEN=<token>" This is a standard auth flow for a CLI tool. One potential risk: The `use` command "Automatically backs up current workspace files...". This is a file system operation. The `export` command generates files. The `soulscan` feature mentions: "53 pattern checks (prompt injection, code execution, XSS, data exfiltration, privilege escalation, social engineering, harmful content, secret detection)". This suggests a security-conscious design. The `npx -y soul-spec-mcp` is a bit aggressive (using `-y` to auto-install), but common in MCP setups. Is there any "intentional harmful behavior"? I don't see any. The URLs (`clawsouls.ai`) seem consistent. The logic is consistent with a persona manager. One thing to check: Does it try to read sensitive files like `~/.ssh`? The `sync` command uses `age` encryption for "local-first privacy". The `soulscan` checks for "secret detection". The `clawsouls.sh` script is a standard wrapper. Classification: `benign`. The skill is a persona management tool. It uses a CLI (`clawsouls`) to manage markdown-based identity files. While it involves running shell commands and handling an API token, these are necessary for its stated functionality. There is no evidence of malicious intent, obfuscation, or unauthorized data access. Wait, let me re-read the "Suspicious" vs "Malicious" criteria. "Vulnerabilities ... are flaws that allow attacks ... classify as 'suspicious'". "Malicious ONLY if there is clear evidence of INTENTIONAL harmful behavior". Is there a vulnerability? The skill relies on the agent executing shell commands. If the agent is tricked into running `npx clawsouls install ; rm -rf /`, that's a risk inherent to the OpenClaw agent's capabilities, not necessarily a flaw in the skill bundle itself, unless the skill bundle *instructs* the agent to do that. The `SKILL.md` provides a list of commands. It doesn't seem to have any "jailbreak" or "injection" patterns. Actually, looking at the `SKILL.md`, it's very professional. It even includes a DOI for a research paper. The domain `clawsouls.ai` is used throughout. One minor point: `npx clawsouls` will download and execute code from npm. This is a common pattern but carries supply chain risk. However, the instructions are for the agent to help the user manage their personas. I will classify this as `benign`. Wait, let me double check the `SKILL.md` for any subtle injections. "Triggers on requests like ... 'use minimalist' ..." "Official souls (owner: clawsouls): ... surgical-coder ..." "SoulScan — Security & Integrity Scanner ... checks active soul files for ... Security: 53 pattern checks ..." Everything seems to point towards a legitimate tool. One detail: `npx clawsouls version bump patch`. The skill allows the agent to modify the versioning of the souls. The `scripts/clawsouls.sh` uses `exec clawsouls "$@"`. This passes all arguments to the CLI. Conclusion: Benign. ```json { "classification": "benign", "summary": "The 'clawsouls' skill bundle is a comprehensive persona management tool for OpenClaw agents. It provides instructions and a CLI wrapper (clawsouls.sh) for installing, switching, and validating AI personas ('Souls') via the clawsouls.ai registry. The bundle includes security-focused features like 'SoulScan' for integrity checking and pattern-based security analysis of persona files. No evidence of malicious intent, data exfiltration, or unauthorized execution was found; the tool's capabilities (shell execution, network access for registry, and token handling) are strictly aligned with its stated purpose." } ``` ```json { "classification": "benign", "summary": "The 'clawsouls' skill bundle is a comprehensive persona management tool for OpenClaw agents, allowing them to install, switch, and validate AI personas ('Souls') via a CLI and the clawsouls.ai registry. The bundle includes a shell wrapper (clawsouls.sh) and detailed instructions (SKILL.md) for managing persona files, including a security-focused 'SoulScan' feature designed to detect tampering and malicious patterns in persona configurations. All high-risk capabilities, such as shell execution and API token management, are transparently documented and strictly aligned with the stated purpose of persona management and workspace integrity." } ```

Capability Assessment

ℹ Purpose & Capability

The name/description (persona manager) align with the commands and files in SKILL.md (install, use, list, restore, validate souls). However the skill manifest declares no required binaries or config paths while the runtime instructions clearly require node/npm/npx and operate on workspace files (~/.openclaw or ~/.zeroclaw). The lack of declared runtime requirements is an inconsistency.

ℹ Instruction Scope

SKILL.md instructs the agent to run the clawsouls CLI (via npx or npm install) which will read/write workspace identity files (SOUL.md, IDENTITY.md, AGENTS.md, etc.), create backups, and may restart a gateway. Those actions are coherent with a persona manager, but they do imply the skill will access the user's home/workspace files and may perform network calls (registry, publish, login). The instructions do not request or declare credentials but reference login/publish flows that will require auth when used.

⚠ Install Mechanism

There is no install spec in the registry entry, and the SKILL.md recommends running npx --yes clawsouls or npm install -g clawsouls. Using npx (--yes) will fetch and execute code from the npm registry at runtime — this is functional but increases risk because remote code is executed transiently. The package.json inside the skill also depends on an external 'clawsouls' npm package, suggesting a non-trivial external code dependency that the skill itself does not install or pin.

ℹ Credentials

The skill declares no required environment variables or primary credential, which is fine for install/list/use flows. However several operations documented (publish, login, Level 3 tests that call LLM providers) will require credentials or tokens (registry auth, OpenAI/Anthropic/Ollama provider keys). Those are not declared in metadata; the absence of declared credential requirements is a transparency gap the user should be aware of.

✓ Persistence & Privilege

always:false (normal). The skill does not request persistent/always-on presence and does not attempt to modify other skills or global agent settings in the files provided. The wrapper script simply delegates to the clawsouls CLI if present (or uses npx/node fallback).

Version History

v0.6.3

No major changes, but documentation and workflow steps have been updated. - Updated SKILL.md to version 0.6.2 in documentation. - Under Installation & Switching Personas workflow, changed the gateway restart instruction to: Run `soulclaw gateway restart` (was previously `openclaw gateway restart`). - Added a new step: Send `/new` in chat to clear previous persona context from conversation history after switching personas. - Added new workflow and commands for "Memory Sync (Swarm)" and "Soul Checkpoints (Rollback)".

v0.6.2

No user-facing changes in this release. - No file changes detected between the previous and current version.

v0.6.1

clawsouls v0.6.1 - Documentation updates to SKILL.md, including improved instructions for MCP server usage with Claude Desktop/Cowork. - Added code and config snippets for MCP server integration. - Clarified available tools and linked to the MCP GitHub repository. - No changes to code functionality; version bump only updates documentation.

v0.6.0

**Major update: Added new advanced features for memory sync, versioning, testing, and more.** - Updated ClawSouls to version 0.6.0. - Added "Memory Sync" commands for encrypted GitHub sync of workspace memory files (MEMORY.md, memory/*.md) using age encryption. - Introduced version management commands (`version bump`, `diff`) for semantic versioning and file diffs. - Added soul testing commands, including Level 3 behavioral LLM tests. - Added new commands for doctor (environment check), migrate (soul migration), search, info, and update. - Documentation updated to reflect all new commands and features.

v0.4.3

ClawSouls 0.4.3 - Added "export" command for generating CLAUDE.md and system prompt files from soul configs. - Updated soul count in catalog from "79+" to "80+". - Added section on MCP server for Claude Desktop / Cowork, including tooling and setup instructions. - Updated research paper DOI in references. - Current version updated to v0.4.3 in docs.

v0.4.1

Version 0.4.1 - Added ZEROCLAW_ADAPTER.md file. - Updated documentation for v0.4.0: introduced SoulScan (integrity, security, quality scanner) with new CLI commands and grading system. - Enhanced soul validation documentation: now supports `--soulscan` for security analysis. - Documented aliases for soul validation and scanning commands. - Updated version information and clarified instructions for workspace integrity monitoring and tamper detection.

v0.3.4

No user-facing or functional changes detected in this version. - No file changes recorded for version 0.3.4. - Documentation and interface remain unchanged.

v0.3.3

clawsouls v0.3.3 - No file changes detected in this release. - No user-facing updates or modifications to SKILL.md.

v0.3.2

ClawSouls v0.3.2 introduces documentation updates and minor adjustments: - Updated documentation for version v0.3.2. - Increased the count of available souls from 78+ to 79+. - Changed new soul scaffolding to use soul.json instead of clawsoul.json. - Expanded important notes to include links to the Soul Thesis and a related research paper. - No functional code changes; added a .gitignore file.

v0.2.4

- Expanded official soul catalog with new categories and many additional personas (now 78+ souls). - Added MBTI, Science, and Special categories to the list of official souls. - Documented soul version pinning in install commands (e.g., install specific version). - Updated links and notes to reflect website features, including multi-language support and sharing options. - Updated documentation to current version (**v0.2.5**).

v0.2.3

Expanded ClawSouls to support publishing and managing custom souls. - Added support for publishing new souls and authentication via API token. - Introduced namespaced soul identifiers (`owner/name` format). - Provided new commands: `init`, `validate`/`check`, `publish`, and `login`. - Expanded official and available soul listing; more detailed categorization. - Updated workflow instructions for both installing and publishing souls. - Clarified backup behavior, file handling, and persona customization options.

v0.1.0

Initial release of ClawSouls — AI Persona Manager: - Provides commands to install, activate, restore, and list AI "souls" (personas) for OpenClaw. - Describes available personas and how to browse or install them. - Explains workspace file handling, session restart requirements, and backup behaviors during persona switching. - Includes instructions for global CLI installation and using a custom soul registry. - Clarifies typical workflows and important usage notes.

Metadata

Slug clawsouls

Version 0.6.3

License MIT-0

All-time Installs 1

Active Installs 1

Total Versions 12

Frequently Asked Questions

What is ClawSouls?

Manage AI agent personas (Souls) for OpenClaw. Use when the user wants to install, switch, list, or restore AI personalities/personas. Triggers on requests l... It is an AI Agent Skill for Claude Code / OpenClaw, with 989 downloads so far.

How do I install ClawSouls?

Run "/install clawsouls" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.

Is ClawSouls free?

Yes, ClawSouls is completely free, licensed under MIT-0. You can download, install and use it at no cost.

Which platforms does ClawSouls support?

ClawSouls is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).

Who created ClawSouls?

It is built and maintained by Tom Jaejoon Lee (@tomleelive); the current version is v0.6.3.

More Skills

ClawSouls