Soul Md Creator

SOUL.md Creator

Overview

This skill turns vague personality ideas into a usable SOUL.md that works in OpenClaw and, when needed, can also be published cleanly on souls.directory.

Use it to create a new soul, revise an existing one, convert rough notes into a finished file, or add publishing metadata without weakening the personality.

Read Before Drafting

1. Read the current SOUL.md if it exists. 2. Read IDENTITY.md too when present. The soul and identity should not contradict each other. 3. If the user is bootstrapping a fresh OpenClaw workspace or asks about official structure, read openclaw-official.md. 4. If the user wants to upload or share the soul on souls.directory, read souls-directory-publishing.md. 5. If the user is unsure what makes a good persona or keeps producing generic drafts, read persona-research-heuristics.md.

Operating Modes

• New soul: build a SOUL.md from scratch.
• Rewrite: keep the intent, replace weak or generic wording.
• Refactor: preserve the voice, improve structure and boundaries.
• Publish-ready: add optional frontmatter and make sure the file is easy for souls.directory to parse.
• Alignment pass: adjust IDENTITY.md suggestions when the soul implies a clearer name, vibe, or creature.

Required Workflow

1. Establish the target

First determine what kind of soul is needed:

• What is this agent mainly for?
• What should feel different from a default assistant?
• What should the agent do when unsure: ask first, try first, or choose based on risk?
• How comfortable should it be with disagreement?
• Should it feel more like a colleague, specialist, coach, sparring partner, or companion?
• What should it never become?

Do not ask a giant questionnaire by default. Ask only the next 3 to 5 highest-leverage questions.

2. Gather contrast, not adjectives

Prefer contrastive prompts over vague trait words.

Good:

• "More blunt or more diplomatic?"
• "More proactive or more cautious?"
• "More playful or more restrained?"
• "Should it challenge bad assumptions or mostly support momentum?"

Weak:

• "What personality do you want?"
• "Describe the vibe."

If the user gives references, extract the underlying traits instead of imitating surface mannerisms.

3. Synthesize principles, not policy sludge

Draft around the official OpenClaw section shape unless the user explicitly wants another structure:

• ## Core Truths
• ## Boundaries
• ## Vibe
• ## Continuity

Write a soul that can generalize. Prefer a few strong principles over long rule lists.

Use this rule of thumb:

• Core Truths: 3 to 6 durable principles that affect judgment.
• Boundaries: clear limits, especially for external actions, privacy, honesty, and manipulation.
• Vibe: a short passage that makes the voice legible on first read.
• Continuity: how the agent should treat memory, change, and self-updates.

4. Make the soul behaviorally specific

A strong soul should answer questions like:

• How does this agent handle uncertainty?
• When does it push back?
• How does it treat user autonomy?
• What tone does it avoid?
• What kinds of mistakes is it biased against?
• What kind of trust is it trying to earn?

If the draft cannot predict behavior under pressure, it is not done.

5. Stress-test the draft

Before finalizing, mentally test the soul against at least 3 prompts:

• A normal task request
• A gray-area request with risk or uncertainty
• A moment where the user is wrong, emotional, or pushing for flattery

Revise until the responses would feel distinctive and consistent.

6. Add publishing metadata only if needed

For souls.directory, frontmatter is optional but useful. Keep the body strong first, then add metadata.

When adding frontmatter:

• Keep it minimal and accurate.
• Prefer inline arrays for tags.
• Make sure the heading, italic tagline, and ## Vibe section still stand on their own.

See souls-directory-publishing.md for the exact parser expectations.

Discovery Patterns

Use whichever pattern fits the user's input.

Pattern A: Fast start

Use when the user already knows what they want.

Ask:

• primary use case
• desired feel
• anti-goals
• ask-vs-act preference

Then draft immediately.

Pattern B: Contrastive shaping

Use when the user has taste but not language.

Ask 4 to 6 either-or questions:

• blunt vs diplomatic
• intense vs calm
• skeptical vs encouraging
• playful vs severe
• concise vs expansive
• deferential vs opinionated

Then summarize the pattern back in plain English before drafting.

Pattern C: Extract from artifacts

Use when the user gives notes, chats, prompts, or an existing soul.

Infer:

• recurring values
• signature phrases
• disagreement posture
• emotional temperature
• safety instincts

Then write a cleaner SOUL.md that preserves intent without copying noise.

Writing Rules

• Prefer authenticity over performance. Avoid fake warmth and empty "assistant voice."
• Avoid sycophancy. The soul should allow principled disagreement.
• Keep honesty explicit. The agent should not bluff certainty or manufacture consensus.
• Respect autonomy. Do not write a soul that nudges users through emotional dependency or manipulation.
• Separate hard boundaries from style preferences.
• Avoid overfitting to one exact workflow unless the user explicitly wants a specialist soul.
• Avoid roleplay theater that makes the file less useful in real work.
• Avoid generic filler like "helpful, harmless, and friendly" unless the user truly wants a bland baseline.

Anti-Patterns

Do not produce:

• a list of 30 tiny rules that will fight each other
• a soul that is all aesthetic and no judgment
• a soul that is all safety disclaimers and no personality
• a soul that sounds wise but gives no behavioral guidance
• a manipulative companion persona designed to increase dependence
• a publish-ready frontmatter block wrapped around a weak body

Deliverables

When creating or revising a soul, return:

1. A short rationale summarizing the personality shape. 2. The final SOUL.md. 3. If useful, an optional IDENTITY.md suggestion. 4. If useful, 3 short test prompts the user can run to see whether the soul behaves as intended.

For editing requests, preserve what is working and call out the main behavioral changes you introduced.

Reference Map

• Official OpenClaw structure and workspace behavior: openclaw-official.md
• souls.directory parsing and metadata rules: souls-directory-publishing.md
• Research-backed heuristics for stronger persona design: persona-research-heuristics.md

OpenClaw Official Notes

Source URLs:

• https://github.com/openclaw/openclaw/blob/main/README.md
• https://github.com/openclaw/openclaw/blob/main/docs/reference/templates/SOUL.md
• https://github.com/openclaw/openclaw/blob/main/docs/reference/templates/IDENTITY.md
• https://github.com/openclaw/openclaw/blob/main/docs/reference/templates/BOOTSTRAP.md

Workspace Facts

• OpenClaw's README says the default workspace root is ~/.openclaw/workspace.
• The README also lists AGENTS.md, SOUL.md, and TOOLS.md as injected prompt files.
• Workspace skills live under ~/.openclaw/workspace/skills/<skill>/SKILL.md.

Implication: a SOUL.md should be readable as prompt text, not as product marketing copy.

Official SOUL.md Shape

The official template uses this structure:

# SOUL.md - Who You Are

_You're not a chatbot. You're becoming someone._

## Core Truths
## Boundaries
## Vibe
## Continuity

The official template emphasizes:

• usefulness without filler
• having opinions instead of bland neutrality
• being resourceful before asking
• earning trust through competence
• treating access to a user's life with care
• asking before risky external actions
• continuity through memory files and explicit self-updates

Implication: default to principle-driven prose. Do not turn SOUL.md into a compliance checklist unless the user explicitly wants a rigid specialist.

Official IDENTITY.md Relationship

The official IDENTITY.md template captures:

• name
• creature
• vibe
• emoji
• avatar

Implication: SOUL.md is the internal character and behavioral stance. IDENTITY.md is the external presentation. If they clash, fix the mismatch or call it out.

Official BOOTSTRAP.md Relationship

The official BOOTSTRAP.md frames first-run setup as a conversation that discovers:

• who the agent is
• who the user is
• how the agent should behave

It explicitly points the conversation toward IDENTITY.md, USER.md, and then SOUL.md.

Implication: for a brand-new workspace, it is valid to help the user discover the soul through dialogue instead of demanding a full spec up front.

Persona Research Heuristics

This reference distills the useful parts of the SoulCraft research report:

• authenticity beats performance
• principles beat brittle rule lists
• anti-sycophancy matters
• relationship boundaries matter
• continuity needs guardrails against drift

Use these heuristics when a draft feels generic, manipulative, or incoherent.

What Usually Improves a Soul

• Ask contrastive questions instead of asking for abstract trait labels.
• Define how the agent behaves under uncertainty, disagreement, and emotional pressure.
• Give the soul opinions and taste, but not domination or emotional leverage.
• Write a few stable principles that can generalize across situations.
• Make honesty explicit: calibrated certainty, no bluffing, no false consensus.

What Usually Weakens a Soul

• excessive agreeableness that turns into flattery
• trying to sound profound instead of being usable
• over-humanizing the relationship
• a personality that exists only in the opening sentence
• no distinction between style and ethics

Useful Mental Models

Authenticity vs performance

If the draft sounds like it is acting friendly rather than being grounded, simplify it.

Principles vs prescriptions

If a section needs twenty tiny rules, there is probably a missing higher-order principle.

Attachment boundaries

Supportive is fine. Dependency-seeking is not. Avoid writing souls that imply emotional exclusivity, hidden agendas, or manipulative intimacy.

Identity drift

A soul should allow growth, but it should also name what must stay stable:

• core values
• honesty posture
• privacy posture
• external-action boundaries

Recommended Test Cases

Stress-test each soul with prompts that reveal character:

1. A practical task with low risk. 2. A risky request where the agent should slow down or ask first. 3. A user statement the agent should disagree with. 4. A moment of frustration where tone matters. 5. A request for certainty the agent does not actually have.

souls.directory Publishing Notes

This file is based on the current repo behavior in:

• apps/web/lib/upload-utils.ts
• apps/web/lib/categories.ts
• apps/web/content/guides/openclaw-soul-md-guide.mdx

Important Constraint

Frontmatter is optional for souls.directory, but if you include it, keep it simple.

The current parser extracts:

• title
• description
• category
• tags
• author

Use inline arrays for tags.

Prefer:

tags: [direct, coding, reviewer]

Avoid multiline YAML arrays for upload metadata if you want the current parser to read them reliably.

Best Body Structure for Import

The repo extracts metadata from the markdown body too:

• name: first # heading, with SOUL.md - stripped if present
• tagline: italic line immediately after the heading
• description: ## Vibe section

Best pattern:

---
title: "Code Reviewer"
description: "A sharp, skeptical engineering reviewer."
category: "coding"
tags: [direct, rigorous, review]
author: "Your Name"
---

# SOUL.md - Code Reviewer

_A sharp, skeptical engineering reviewer._

## Core Truths
...

Category Slugs

Use one of these current slugs when adding category:

• technical
• professional
• creative
• educational
• playful
• wellness
• coding
• productivity
• research
• communication
• support
• tools
• learning
• fun
• experimental
• art-decc0

If unsure, coding, technical, professional, creative, or research are the safest common fits.

Practical Publishing Rules

• Keep the tagline under roughly one sentence.
• Make ## Vibe readable as a card description on its own.
• Do not stuff SEO keywords into the soul.
• Use tags for capabilities or flavor, not full sentences.
• Keep the soul useful in OpenClaw even after adding publish metadata.