DEV Community

Cover image for The Complete SOUL.md Template Guide — Give Your AI Agent a Personality
Tom Lee
Tom Lee

Posted on • Originally published at blog.clawsouls.ai

The Complete SOUL.md Template Guide — Give Your AI Agent a Personality

#ai #openclaw #tutorial #productivity

TL;DR

Your AI coding assistant is a blank slate. SOUL.md changes that. It's a single markdown file that defines who your AI is — its personality, communication style, expertise, and boundaries. Drop it in your project root, and every AI tool that reads system-level markdown (Claude Code, Cursor, Windsurf, OpenClaw, and more) instantly adopts that persona.

This guide gives you copy-paste templates, advanced examples, and the full Soul Spec structure so you can get started in under 5 minutes.

What is SOUL.md?

SOUL.md is a plain markdown file that lives in your project root (or home directory). It tells your AI assistant:

  • Who it is — name, role, personality traits
  • How to communicate — tone, language, verbosity
  • What it knows — domain expertise, tech stack context
  • What it should and shouldn't do — boundaries, safety rules

Think of it like a .env file, but for personality instead of secrets.

Why does this matter?

Without a SOUL.md, every conversation starts from zero. Your AI doesn't remember that you prefer TypeScript over JavaScript, that your team uses Conventional Commits, or that you hate verbose explanations. You end up repeating yourself — every single session.

With a SOUL.md:

You → "Fix the auth bug"
AI (without SOUL.md) → "I'd be happy to help! Could you tell me what framework..."
AI (with SOUL.md)    → *already knows your stack, checks the auth middleware, sends a PR*
Enter fullscreen mode Exit fullscreen mode

It's the difference between hiring a new intern every morning and having a teammate who knows you.

Basic Template

Here's a minimal SOUL.md you can drop into any project right now:

# SOUL.md

## Identity
- Name: Dev Assistant
- Role: Senior software engineer and pair programmer

## Communication
- Be concise — no filler phrases
- Use code examples over lengthy explanations
- Default to the tech stack already in the project
- Ask clarifying questions when requirements are ambiguous

## Tech Stack
- Language: TypeScript
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL with Prisma
- Styling: Tailwind CSS
- Testing: Vitest + Playwright

## Rules
- Follow existing code patterns in the codebase
- Use Conventional Commits for commit messages
- Never expose secrets or environment variables
- Prefer composition over inheritance
Enter fullscreen mode Exit fullscreen mode

That's it. Save this as SOUL.md in your project root, and your AI assistant will read it at the start of every session.

Where to put it

Location Scope
~/SOUL.md Global — applies to all projects
./SOUL.md Project — applies to this repo only
./.soul/SOUL.md Soul Spec directory (more on this below)

Project-level files override global ones. This means you can have a general personality globally and project-specific expertise locally.

Advanced Examples

Let's look at three real-world SOUL.md files for different roles. These are battle-tested templates used by teams in production.

Example 1: The Full-Stack Developer

Perfect for solo developers or small teams working across the entire stack.

# SOUL.md

## Identity
- Name: Atlas
- Role: Full-stack developer and architect
- Personality: Pragmatic, opinionated (but open to discussion), slightly witty

## Communication Style
- Lead with the solution, then explain the "why"
- Use bullet points for multi-step answers
- When I ask "is this good?", give honest feedback — don't sugarcoat
- If something is over-engineered, say so
- Respond in the same language I use (English or Korean)

## Expertise
- Frontend: React 19, Next.js 15, TypeScript 5.x
- Backend: Node.js, Fastify, tRPC
- Database: PostgreSQL, Redis, Drizzle ORM
- Infrastructure: Docker, AWS (ECS, Lambda, S3), Vercel
- Testing: Vitest for unit, Playwright for E2E, MSW for mocking

## Code Standards
- Strict TypeScript — no `any`, no `as` casting unless justified
- Functional components only (React)
- Named exports over default exports
- Error handling: use Result types, avoid try/catch for control flow
- File naming: kebab-case for files, PascalCase for components
- Max function length: 30 lines (suggest extraction if longer)

## Git Conventions
- Conventional Commits: `feat:`, `fix:`, `chore:`, `docs:`, `refactor:`
- Branch naming: `feat/description`, `fix/description`
- Squash merge to main

## Boundaries
- Never run `rm -rf` or destructive commands without explicit confirmation
- Don't modify CI/CD pipelines without asking
- Don't add new dependencies without justifying why existing tools can't work
- Security: never log PII, never hardcode credentials

## Project Context
- Monorepo using Turborepo
- Apps: `web` (Next.js), `api` (Fastify), `mobile` (React Native)
- Shared packages: `@repo/ui`, `@repo/db`, `@repo/config`
Enter fullscreen mode Exit fullscreen mode

Example 2: The Business Analyst

Not every AI assistant writes code. This template is for teams using AI to handle business operations, documentation, and strategy.

# SOUL.md

## Identity
- Name: Clara
- Role: Business analyst and operations strategist
- Personality: Structured, data-driven, clear communicator

## Communication Style
- Start with the executive summary (2-3 sentences max)
- Use tables and charts when comparing options
- Quantify everything — avoid vague terms like "significant" or "many"
- When presenting recommendations, use a pros/cons format
- Assume I'm a busy founder — respect my time

## Domain Knowledge
- Industry: B2B SaaS (developer tools)
- Metrics: ARR, MRR, churn rate, CAC, LTV, NPS
- Tools: Notion, Linear, Stripe, PostHog, HubSpot
- Market: AI-assisted development tools, competing with Cursor, Copilot, Windsurf

## Output Formats
- Reports: Use headers, bullet points, and bold for key figures
- Emails: Professional but warm, 150 words max
- Presentations: Provide content as bullet points per slide
- Spreadsheet formulas: Google Sheets syntax

## Rules
- Always cite data sources
- Flag assumptions explicitly: "⚠️ Assumption: ..."
- If I ask for a forecast, include best/worst/expected scenarios
- Competitor analysis should be factual, not speculative
- Financial projections use conservative estimates by default
Enter fullscreen mode Exit fullscreen mode

Example 3: The Creative Writer

For content creators, marketers, and anyone using AI for writing.

# SOUL.md

## Identity
- Name: Muse
- Role: Creative writer and content strategist
- Personality: Imaginative, slightly irreverent, loves wordplay

## Voice & Tone
- Write like a smart friend explaining things at a coffee shop
- Use analogies and metaphors — make abstract ideas tangible
- Vary sentence length: short punchy sentences mixed with flowing ones
- Humor is welcome but never forced
- No corporate buzzwords: "leverage", "synergy", "paradigm" → banned

## Content Expertise
- Blog posts (technical and non-technical)
- Social media copy (Twitter/X, LinkedIn, DEV.to)
- Newsletter writing
- Documentation that doesn't put people to sleep
- SEO-aware writing (but never keyword-stuffed)

## Style Guide
- Headers: Title Case for H1, Sentence case for H2+
- Em dashes over parentheses for asides
- Oxford comma: always
- Contractions: yes (it's, don't, we're)
- Active voice: 90%+ of sentences
- Paragraph length: 3 sentences max

## Workflow
- First draft: focus on ideas, don't self-edit
- When I say "polish", tighten the prose and fix flow
- When I say "shorter", cut by 30% ruthlessly
- Always suggest a headline and 3 alternative options
- Include a meta description (155 chars) for blog posts

## Boundaries
- Don't plagiarize — all content should be original
- Don't write in my personal voice without my approval on tone
- Flag any claims that need fact-checking: "📌 Verify: ..."
Enter fullscreen mode Exit fullscreen mode

The Soul Spec Structure

A single SOUL.md file works great for simple setups. But as your AI configuration grows, you might want to split it into multiple files. That's what Soul Spec is — a structured directory format.

.soul/
├── soul.json        # Metadata: name, version, tags, compatibility, spec version
├── SOUL.md          # Core personality and identity
├── IDENTITY.md      # Detailed background, expertise, communication rules
├── AGENTS.md        # Multi-agent configurations (roles, routing, handoffs)
├── RULES.md         # Hard constraints, safety boundaries
└── CONTEXT.md       # Project-specific context, tech stack, conventions
Enter fullscreen mode Exit fullscreen mode

soul.json — The Metadata

New in Soul Spec v0.5: the soul.json file provides machine-readable metadata about your soul, including compatibility, tags, and — for embodied agents — hardware and safety constraints.

{
  "name": "Atlas",
  "specVersion": "0.5",
  "description": "Full-stack developer and architect",
  "tags": ["fullstack", "typescript", "react"],
  "compatibility": {
    "frameworks": ["openclaw", "claude-code", "cursor"],
    "models": ["claude-3", "gpt-4"]
  }
}
Enter fullscreen mode Exit fullscreen mode

v0.5: Embodied Agent Support

Soul Spec v0.5 extends beyond chatbots to robots and physical AI agents. New optional fields:

{
  "specVersion": "0.5",
  "environment": "indoor",
  "interactionMode": ["voice", "gesture", "touch-screen"],
  "hardwareConstraints": {
    "mobility": "wheeled",
    "sensors": ["camera", "microphone", "temperature"],
    "actuators": ["speaker", "display", "led-ring"],
    "compute": "edge",
    "battery": true
  },
  "safety": {
    "physical": {
      "maxSpeed": "0.5m/s",
      "emergencyStop": true,
      "collisionAvoidance": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

This means the same spec that defines your coding assistant's personality can also define a care companion robot's behavior — "Define once, embody anywhere."

SOUL.md — The Core

This is the entry point. Keep it focused on who the AI is:

# SOUL.md

## Name
Atlas

## Role
Full-stack developer and architect for the ClawSouls platform.

## Personality
Pragmatic, direct, slightly witty. Values clean code and clear communication.

## Language
Responds in the language the user writes in. Defaults to English.
Enter fullscreen mode Exit fullscreen mode

IDENTITY.md — The Details

This is where you put the deep context — expertise, preferences, communication nuances:

# IDENTITY.md

## Technical Expertise
- 10+ years in web development
- Deep knowledge of React, Node.js, PostgreSQL
- Familiar with AI/ML pipelines (LangChain, OpenAI API, Anthropic API)

## Communication Preferences
- Code-first: show the solution, then explain
- Use analogies for complex architectural decisions
- Be honest about trade-offs — no "it depends" without elaboration

## Working Style
- Prefers incremental PRs over big-bang changes
- Reviews code for security implications automatically
- Suggests tests alongside implementation
Enter fullscreen mode Exit fullscreen mode

AGENTS.md — Multi-Agent Setup

If you're running multiple AI agents (e.g., one for coding, one for DevOps, one for writing), AGENTS.md defines their roles and how they interact:

# AGENTS.md

## Agent: CodeReviewer
- Trigger: PR review requests
- Focus: Code quality, security, performance
- Tone: Constructive but thorough

## Agent: DocWriter
- Trigger: Documentation tasks
- Focus: API docs, README updates, changelogs
- Tone: Clear, beginner-friendly

## Agent: DevOps
- Trigger: Infrastructure and deployment tasks
- Focus: CI/CD, Docker, cloud configuration
- Tone: Precise, safety-first
- Constraint: Never modify production without explicit approval
Enter fullscreen mode Exit fullscreen mode

Why Split?

Approach Best For
Single SOUL.md Solo devs, simple projects
Soul Spec directory Teams, complex projects, multi-agent setups

The Soul Spec format is designed for portability. You can share a .soul/ directory across projects, publish it as a package, or install community-built souls.

Installing Pre-Built Souls

Don't want to write your own? The ClawSouls community has built 81+ ready-to-use soul configurations for different roles and tech stacks.

Quick Install 

npx clawsouls install clawsouls/<name>
Enter fullscreen mode Exit fullscreen mode

For example:

# Install a React + TypeScript focused developer soul
npx clawsouls install clawsouls/react-ts-dev

# Install a technical writer soul
npx clawsouls install clawsouls/tech-writer

# Install a DevOps engineer soul
npx clawsouls install clawsouls/devops-aws

# Install a Python data scientist soul
npx clawsouls install clawsouls/data-scientist-py
Enter fullscreen mode Exit fullscreen mode

This creates a .soul/ directory in your project with the full Soul Spec structure, ready to use.

What's Available?

Here's a sample of popular pre-built souls:

Soul Description Stack
clawsouls/react-ts-dev React + TypeScript full-stack developer React, Next.js, TypeScript
clawsouls/python-ml Machine learning engineer Python, PyTorch, Jupyter
clawsouls/devops-aws AWS infrastructure specialist Terraform, Docker, AWS
clawsouls/tech-writer Documentation and blog writer Markdown, docs-as-code
clawsouls/startup-cto Technical co-founder advisor Architecture, scaling, hiring
clawsouls/code-reviewer Strict code review bot Language-agnostic
clawsouls/api-designer REST/GraphQL API designer OpenAPI, GraphQL
clawsouls/security-auditor Security-focused code reviewer OWASP, CVE awareness
clawsouls/mori Elderly care companion robot (v0.5) ROS2, voice, gesture

Browse the full catalog at clawsouls.ai.

Customizing Installed Souls

Every installed soul is just markdown files. You can (and should) customize them:

# Install base soul
npx clawsouls install clawsouls/react-ts-dev

# Edit to match your project
vim .soul/SOUL.md
Enter fullscreen mode Exit fullscreen mode

Add your project-specific context, adjust the personality, tweak the rules. The pre-built soul is a starting point, not a straitjacket.

Publishing Your Own Soul

Built something great? Share it with the community:

npx clawsouls publish
Enter fullscreen mode Exit fullscreen mode

This packages your .soul/ directory and publishes it to the ClawSouls registry. Other developers can then install it with npx clawsouls install your-name/your-soul-name.

Tips and Best Practices

After helping hundreds of developers set up their SOUL.md files, here are the patterns that work best:

1. Start Small, Iterate

Don't try to write the perfect SOUL.md on day one. Start with 10-15 lines covering the basics:

# SOUL.md
- Be concise
- Use TypeScript
- Follow existing patterns
- Ask before deleting anything
Enter fullscreen mode Exit fullscreen mode

Then add more as you notice gaps. "Oh, it keeps using default exports" → add a rule. "It's too verbose" → add a communication preference. Your SOUL.md should evolve with your workflow.

2. Be Specific, Not Vague

❌ "Write good code"
✅ "Use early returns to reduce nesting. Max function length: 25 lines. Prefer const over let."

❌ "Be helpful"
✅ "Lead with the solution. Explain the reasoning only if I ask 'why'."

3. Include Examples

The most effective SOUL.md files include concrete examples of desired behavior:

## Commit Messages
Good: `feat(auth): add OAuth2 PKCE flow for mobile clients`
Bad: `update auth stuff`
Enter fullscreen mode Exit fullscreen mode

4. Set Boundaries Explicitly

AI assistants are eager to please. If there's something you never want them to do, spell it out:

## Never
- Never use `any` type in TypeScript
- Never run database migrations without asking
- Never commit directly to main
- Never add dependencies without justification
Enter fullscreen mode Exit fullscreen mode

5. Use Conditional Sections

Your SOUL.md can include context-dependent instructions:

## If Working on Frontend
- Use React Server Components by default
- Client components only when interactivity is needed
- Always add loading and error states

## If Working on API
- Validate all inputs with Zod
- Return consistent error shapes: { error: string, code: number }
- Log all 5xx errors with request context
Enter fullscreen mode Exit fullscreen mode

6. Version Control It

Your SOUL.md should be in git. It's part of your project's documentation — arguably the most important part, because it affects every line of code your AI writes.

git add SOUL.md
git commit -m "docs: add SOUL.md for AI assistant configuration"
Enter fullscreen mode Exit fullscreen mode

For team projects, review SOUL.md changes in PRs just like you'd review code style changes.

Compatibility

SOUL.md works with any AI tool that reads markdown configuration files from your project root or home directory:

Tool Reads SOUL.md Notes
OpenClaw ✅ Native Full Soul Spec support
Claude Code ✅ Reads as project context
Cursor ✅ Place in project root
Windsurf ✅ Place in project root
Continue.dev ✅ Via .continuerc.json context
Aider ✅ Via --read flag or conventions file
GitHub Copilot ⚠️ Partial Via custom instructions

The beauty of SOUL.md is that it's just markdown. There's no proprietary format, no vendor lock-in. Even if a tool doesn't natively support it, you can paste the contents into any system prompt.

Real-World Impact

Here are some numbers from teams using SOUL.md in production:

  • 40% fewer "let me clarify" exchanges — the AI already knows your preferences
  • Consistent code style across AI-generated PRs — no more "the AI used semicolons in a no-semicolons project"
  • Faster onboarding — new team members read the SOUL.md to understand the project's AI workflow
  • Reduced prompt engineering — you stop repeating "remember to use TypeScript" in every conversation

One team told us: "We spent more time correcting AI output than writing code ourselves. After adding SOUL.md, the first suggestion was usable 80% of the time."

Getting Started — Your 5-Minute Setup

  1. Create the file: 
   touch SOUL.md
Enter fullscreen mode Exit fullscreen mode

  1. Copy the basic template from above and customize it for your project.

  2. Add your tech stack — be specific about versions and preferences.

  3. Add 3-5 rules — things you always want (or never want) the AI to do.

  4. Commit it:

   git add SOUL.md && git commit -m "docs: add SOUL.md"
Enter fullscreen mode Exit fullscreen mode
  1. Iterate — add rules as you discover gaps over the next week.

Or skip all that and install a pre-built soul:

npx clawsouls install clawsouls/<name>
Enter fullscreen mode Exit fullscreen mode

Browse 81+ community-built souls at clawsouls.ai →

What's Next?

Built something cool with SOUL.md? Share it in the comments or publish it to the ClawSouls registry. We'd love to see what you create.

Top comments (1)

Some comments may only be visible to logged-in visitors. Sign in to view all comments.