Skill: tomleelive/clawsouls (version 0.6.3)

--- name: clawsouls 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 like "install a soul", "switch persona", "change personality", "list souls", "restore my old soul", "use minimalist", "browse personas", "what souls are available", "publish a soul", or "login to clawsouls". --- # ClawSouls — AI Persona Manager 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: ```bash npx clawsouls --version ``` If not installed, install globally: ```bash npm install -g clawsouls ``` Current version: **v0.6.2** ## Commands ### Install a Soul ```bash npx clawsouls install clawsouls/surgical-coder npx clawsouls install clawsouls/surgical-coder --force # overwrite existing npx clawsouls install clawsouls/surgical-coder@0.1.0 # 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 ```bash 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 ```bash npx clawsouls restore ``` Reverts to the most recent backup created by `use`. ### List Installed Souls ```bash npx clawsouls list ``` Shows installed souls in `owner/name` format. ### Create a New Soul ```bash 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 ```bash 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 ```bash 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) ```bash 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) ```bash 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 ```bash 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 ```bash 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: ```bash # 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 ```bash export CLAWSOULS_TOKEN=<token> 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 ```bash npx clawsouls login ``` Instructions to get API token: Sign in at https://clawsouls.ai → Dashboard → Generate API Token. ## Workflow ### Installing & Switching Personas 1. **Browse** — Check available souls at https://clawsouls.ai or suggest from the categorized list above 2. **Install** — `npx clawsouls install clawsouls/surgical-coder` 3. **Activate** — `npx clawsouls use clawsouls/surgical-coder` 4. **Restart** — Run `soulclaw gateway restart` to apply the new persona 5. **New Session** — Send `/new` in chat to clear previous persona context from conversation history 6. **Restore** — If they want to go back, `npx clawsouls restore` ### Publishing a Soul 1. **Login** — `npx clawsouls login` → get token from dashboard 2. **Set token** — `export CLAWSOULS_TOKEN=<token>` 3. **Create** — `npx clawsouls init my-soul` → edit files 4. **Publish** — `npx clawsouls publish ./my-soul/` 5. **Manage** — Dashboard at https://clawsouls.ai/dashboard (delete, view downloads) ### Memory Sync (Swarm) ```bash 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) ```bash 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 ```bash 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: ```bash npx -y soul-spec-mcp ``` Or add to Claude Desktop config (`claude_desktop_config.json`): ```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](https://clawsouls.ai/en/privacy) · [Terms of Service](https://clawsouls.ai/en/terms)

path: package.json
content: {
  "name": "clawsouls-skill",
  "version": "0.6.3",
  "description": "OpenClaw skill for managing AI agent personas via ClawSouls",
  "keywords": [
    "openclaw",
    "skill",
    "ai",
    "persona",
    "soul",
    "clawsouls"
  ],
  "author": "ClawSouls <https://clawsouls.ai>",
  "license": "Apache-2.0",
  "repository": {
    "type": "git",
    "url": "git+https://github.com/clawsouls/clawsouls-skill.git"
  },
  "homepage": "https://clawsouls.ai",
  "dependencies": {
    "clawsouls": "^0.1.0"
  }
}


path: ZEROCLAW_ADAPTER.md
content: # ZeroClaw Adapter Design

## Overview

ZeroClaw is a Rust-based alternative to OpenClaw that already supports OpenClaw-style markdown identity files via its `IdentityConfig` trait. This adapter extends ClawSouls CLI to install/use souls on ZeroClaw.

## ZeroClaw Identity System

### Config Location
- `~/.zeroclaw/config.toml` — main config
- Workspace directory — identity files (SOUL.md, IDENTITY.md, etc.)

### IdentityConfig Trait
ZeroClaw supports two identity formats:
1. **OpenClaw (markdown)** — SOUL.md, IDENTITY.md, AGENTS.md, HEARTBEAT.md, STYLE.md
2. **AIEOS v1.1 (JSON)** — alternative format

Since ZeroClaw already reads OpenClaw-style markdown, Soul files work **out of the box** if placed in the workspace.

## Adapter Strategy

### Option A: CLI Flag (Minimal)
Add `--platform zeroclaw` flag to existing commands:

```bash
npx clawsouls install clawsouls/surgical-coder --platform zeroclaw
npx clawsouls use clawsouls/surgical-coder --platform zeroclaw
```

**Differences from OpenClaw:**
- Workspace: `~/.zeroclaw/` instead of `~/.openclaw/workspace/`
- Restart: `zeroclaw gateway restart` instead of `openclaw gateway restart`
- No `restore` needed — same backup logic

### Option B: Auto-detect (Smart)
CLI detects which platform is running:

```
1. Check if ~/.openclaw/ exists → OpenClaw mode
2. Check if ~/.zeroclaw/ exists → ZeroClaw mode
3. Both exist → prompt user
4. Neither → error
```

### Recommended: Option B (auto-detect) with Option A as override

## Implementation Plan

### Phase 1: Detection
- `src/utils/platform.ts` — detect OpenClaw vs ZeroClaw
- Return workspace path, restart command, config format

### Phase 2: Install/Use
- Modify `install` command to use detected workspace
- Modify `use` command to copy to correct directory
- Modify restart hint to show correct command

### Phase 3: SKILL.md Update
- Add ZeroClaw instructions to SKILL.md
- Document both platforms

## File Mapping

| Soul File | OpenClaw Location | ZeroClaw Location |
|-----------|-------------------|-------------------|
| SOUL.md | ~/.openclaw/workspace/SOUL.md | ~/.zeroclaw/workspace/SOUL.md |
| IDENTITY.md | ~/.openclaw/workspace/IDENTITY.md | ~/.zeroclaw/workspace/IDENTITY.md |
| AGENTS.md | ~/.openclaw/workspace/AGENTS.md | ~/.zeroclaw/workspace/AGENTS.md |
| STYLE.md | ~/.openclaw/workspace/STYLE.md | ~/.zeroclaw/workspace/STYLE.md |
| HEARTBEAT.md | ~/.openclaw/workspace/HEARTBEAT.md | ~/.zeroclaw/workspace/HEARTBEAT.md |

## Testing

1. Install ZeroClaw locally (`cargo install`)
2. Run `npx clawsouls install clawsouls/surgical-coder`
3. Verify files placed in `~/.zeroclaw/workspace/`
4. Run `zeroclaw agent -m "who are you?"` → should respond as Surgical Coder


path: scripts/clawsouls.sh
content: #!/usr/bin/env bash
# ClawSouls CLI wrapper
# Usage: ./clawsouls.sh <command> [args...]
# Commands: install, use, restore, list

set -euo pipefail

# Check if clawsouls is installed globally
if command -v clawsouls &>/dev/null; then
  exec clawsouls "$@"
fi

# Check if npx is available
if command -v npx &>/dev/null; then
  exec npx --yes clawsouls "$@"
fi

# Fallback: try node directly
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
CLI_PATH="$SCRIPT_DIR/../node_modules/clawsouls/dist/bin/clawsouls.js"

if [ -f "$CLI_PATH" ]; then
  exec node "$CLI_PATH" "$@"
fi

echo "Error: clawsouls CLI not found. Install with: npm install -g clawsouls"
exit 1


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)