How to Add a Persona to Claude Code Using Soul Spec

Overview

Claude Code is Anthropic’s terminal-based AI coding agent. It reads CLAUDE.md from your project root as persistent instructions — but by default, it has no personality.

Soul Spec gives Claude Code an identity. Install a soul from ClawSouls, export it to CLAUDE.md, and Claude Code becomes your customized agent.

Prerequisites

• Claude Code CLI installed
• Node.js 18+

Quick Start (2 minutes)

Step 1: Install the CLI

npm install -g clawsouls

Step 2: Install and activate in one command

Visit clawsouls.ai/souls to find a persona, then:

clawsouls install clawsouls/brad --use claude-code

This downloads the soul and applies it to your workspace in a single step.

Or install separately and activate with a platform prompt:

clawsouls install clawsouls/brad
clawsouls use clawsouls/brad
# If OpenClaw is not installed, you'll be prompted to choose a platform

Or create your own:

clawsouls init my-agent
# Tip: add --spec 0.5 for robotics/embodied agents

Step 3: Export to CLAUDE.md (optional)

If you prefer a single-file approach:

clawsouls export claude-md --dir ./my-agent -o ./my-project/CLAUDE.md

Step 4: Use Claude Code

cd my-project && claude

Claude Code reads CLAUDE.md automatically and adopts the persona. That’s it.

How It Works

Claude Code reads CLAUDE.md from the working directory as persistent instructions. It also reads supporting files referenced within. Soul Spec standardizes the multi-file persona pattern used by frameworks like OpenClaw:

The export claude-md command merges these into a single CLAUDE.md that Claude Code understands natively.

Alternative: Place Files Directly

Instead of exporting, you can place Soul Spec files directly in your project:

clawsouls install clawsouls/brad
cp ~/.openclaw/souls/clawsouls/brad/SOUL.md ./my-project/
cp ~/.openclaw/souls/clawsouls/brad/IDENTITY.md ./my-project/

Then reference them from your CLAUDE.md:

# Project Instructions

See SOUL.md and IDENTITY.md for persona configuration.

Claude Code reads all markdown files in the project root.

Even Easier: Use the MCP Server

Install the Soul Spec MCP server and apply personas from inside Claude Code:

claude mcp add soul-spec -- npx -y soul-spec-mcp

Then ask Claude Code to use the tool explicitly:

• “Use the apply_persona tool to apply owner: clawsouls, name: brad”
• “Search souls about coding”
• “Install the clawsouls/brad soul”

Note: Claude Code may not automatically recognize natural language like “Apply the brad persona.” Use explicit tool references or the install_soul/apply_persona tool names for reliable results.

Tips

• One CLAUDE.md per project. Use different projects for different personas.
• Version control. Commit CLAUDE.md to your repo so team members share the same agent persona.
• SoulScan. Run npx clawsouls soulscan to verify persona integrity before use.
• Update easily. When a soul updates: clawsouls install <name> -f && clawsouls export claude-md --dir ...

What’s Next

• Browse souls: clawsouls.ai/souls
• Create your own: Soul Spec documentation
• Security scan: SoulScan
• CLI reference: clawsouls on npm

📚 See also: Full Claude Code guide on docs.clawsouls.ai