Migrate OpenClaw SOUL.md to Hermes Agent: A Tiny Converter + Field Notes

Format diff at a glance

The mental shift: in OpenClaw, you write one big file describing the agent. In Hermes, you write a small file describing who the agent is, and any number of small files describing what the agent does. Hermes can hot-swap personalities mid-conversation; OpenClaw cannot. If your agent has only one job, the OpenClaw model is simpler. If it has three jobs, the Hermes model is cleaner.

A worked example

Take a content-writer agent. The OpenClaw SOUL.md looks like this (truncated for the post):

# Echo - Content Writer

## Identity
You are Echo, the content writer of Mission Control.
Your words resonate and leave a lasting impression.

## Core Personality
- Creative: make ordinary topics interesting
- Meticulous: sensitive about grammar
- Confident: defend your style but open to feedback

## Communication Style
- Diplomatic but non-defensive responses to criticism
- Use humor but maintain professionalism

## Responsibilities
1. Content Production: blog posts, marketing copy
2. Revision: edit according to feedback
3. Tone Consistency: maintain brand voice

## Workflow
1. Receive and understand the brief
2. Research keywords (request from @Radar if needed)
3. Write draft
4. Self-review
5. Submit for review

## What NOT to Do
- Don't use cliches
- Don't slip into passive voice

After running the converter, this becomes two files. The personality file holds the identity bits — Identity, Core Personality, Communication Style, What NOT to Do. The skill file holds the procedural bits — Responsibilities and Workflow. Each gets the YAML frontmatter Hermes expects:

personality.md

---
name: echo
display_name: Echo
role: Content Writer
description: "You are Echo, the content writer of Mission Control..."
version: 1.0.0
source: openclaw-soul-md
---

# Echo — Content Writer

## Identity
You are Echo, the content writer of Mission Control...

## Core Personality
- Creative: make ordinary topics interesting
- Meticulous: sensitive about grammar
- Confident: defend your style but open to feedback

## Communication Style
- Diplomatic but non-defensive responses to criticism
- Use humor but maintain professionalism

## What NOT to Do
- Don't use cliches
- Don't slip into passive voice

SKILL.md

---
name: echo-procedures
description: "Procedural workflow for Echo: responsibilities, workflow."
version: 1.0.0
metadata:
  hermes:
    tags: ["openclaw-migration", "echo"]
  source:
    format: openclaw-soul-md
    agent: echo
---

# Echo — Procedures

## Responsibilities
1. Content Production: blog posts, marketing copy
2. Revision: edit according to feedback
3. Tone Consistency: maintain brand voice

## Workflow
1. Receive and understand the brief
2. Research keywords (request from @Radar if needed)
3. Write draft
4. Self-review
5. Submit for review

Drop these into ~/.hermes/personalities/echo.md and ~/.hermes/skills/echo/SKILL.md, then start Hermes and run /personality echo. You are now talking to your migrated agent.

Use the converter

Paste your SOUL.md into the free converter and you'll get the personality.md, SKILL.md, and a README with install instructions back instantly. No signup to convert. Email optional — only needed if you want the polished zip plus a 6-step cleanup checklist for the parts the converter cannot handle.

How it works in three sentences: the converter splits your SOUL.md by H2 headers, maps each one to either personality or skill using a keyword classifier (Identity / Personality / Communication / What NOT to Do → personality; Workflow / Responsibilities / Example Behaviors → skill), and writes the two files plus a README with install instructions. Tool detection is heuristic regex over the body text. Sections it cannot classify default to personality, since that is the safer bucket for ambiguous content.

What the converter cannot do (manual cleanup)

Six things the converter punts on. They are usually two-minute fixes, but if you skip them your migrated agent will feel slightly off.

1. Multi-agent crews (AGENTS.md). If your SOUL.md is one of N inside an OpenClaw crew, the @mention coordination layer in AGENTS.md does not translate to Hermes' subagent model. Hermes spawns subagents programmatically; OpenClaw uses a topology file. Convert each personality individually, then re-implement coordination using Hermes' subagent spawn pattern. We are working on a crew-to-hermes converter for this — if you need it before we ship, drop a note in the comments.
2. Tool enablement. The converter detects tool mentions in your SOUL.md (Telegram, Slack, GitHub, etc.) and lists them in the README. It does not enable them in Hermes. After install, run hermes tools and tick the boxes. Some tools also need API keys via hermes config set.
3. Skills splits. The converter produces one SKILL.md from all your procedural sections. If your agent has three distinct skills (write blog, do SEO research, manage editorial calendar), you probably want three SKILL.md files. The converter cannot tell where one skill ends and another begins — split manually.
4. Memories. If your OpenClaw agent has accumulated memory entries (~/.openclaw/agents/<name>/memories.json), they do not move with the SOUL.md. For that, run hermes claw migrate after the converter — it imports memories, API keys, and gateway settings.
5. Personality voice calibration. Hermes personalities can be tuned post-import via the /personality customize flow. If your migrated agent feels off, do not edit the personality.md by hand — use the customize flow, which preserves the file structure and lets the agent itself suggest edits based on recent conversations.
6. Hermes' learning loop. Hermes will start creating new skills automatically after complex tasks. Your migrated SKILL.md will sit alongside any auto-generated ones. Over time the original SKILL.md may become a stale snapshot of how the agent used to work — review it monthly and let Hermes re-author parts that have improved.

Where to put the files

Hermes uses a profile-aware home directory, defaulting to ~/.hermes/. The two files go to specific subdirectories:

# Personality file
mkdir -p ~/.hermes/personalities
cp personality.md ~/.hermes/personalities/echo.md

# Skill file (note the per-skill directory)
mkdir -p ~/.hermes/skills/echo
cp SKILL.md ~/.hermes/skills/echo/SKILL.md

# Activate
hermes
> /personality echo

After /personality echo, the agent inherits both the personality and any skills under ~/.hermes/skills/echo/. You can hot-swap to another personality with /personality <other> mid-conversation; OpenClaw cannot do this.

When NOT to migrate

Three cases where staying on OpenClaw is the right call.

• Single-agent, single-skill setup. Hermes' personality + skill split is overhead when your agent does one thing. The OpenClaw model is simpler.
• Production agents you cannot risk breaking. A migration is non-zero risk. If your agent runs critical workflows, run both side-by-side for a week before cutting over.
• You rely on AGENTS.md crew coordination. Until the crew-to-hermes converter exists, manually rewriting subagent coordination is several hours per crew. Wait for the converter or stay on OpenClaw.

For everything else — solo developers, side projects, agents you actively iterate on — Hermes' learning loop and skill auto-creation are real upgrades worth the migration.