Log in

How to Write a Good SOUL.md for Hermes

Updated: November 12, 2026 · By Brian Arrington (founder, BotPlaybooks)*

A good SOUL.md is short and specific. It holds the persona, including standing approval rules and any workflow that should follow the agent everywhere. Start with 4 to 8 lines: who the agent is, how it should sound, what it must avoid and how it handles uncertainty. Put only project-specific instructions (commands, paths and repo conventions) in AGENTS.md. Then test it on a real task and tighten the wording.

This guide walks through that in six steps for Hermes Agent, then shows a complete Chief of Staff SOUL.md you can adapt. Our What Is SOUL.md? explainer covers the basics. If you want ready-made roles, see SOUL.md Templates for Business Agents.

Before you start: where Hermes looks for SOUL.md

The file path, and why a SOUL.md in your project folder is ignored

Hermes reads SOUL.md from one place: ~/.hermes/SOUL.md, or $HERMES_HOME/SOUL.md if you set HERMES_HOME. It does not read a SOUL.md from your working directory. If you drop one into a project folder, Hermes will not see it. That is the most common reason a new SOUL.md "does nothing."

If you run Hermes Profiles, each profile has its own SOUL.md. Edit the one for the profile you are using.

SOUL.md is slot #1 of the system prompt, the first thing Hermes reads, and it replaces the default identity. That is why a few good lines here go a long way.

Back up the starter file

Hermes seeds a starter SOUL.md if none exists, and it never overwrites a file you have written. Before you change anything, copy the current file somewhere safe, for example cp ~/.hermes/SOUL.md ~/.hermes/SOUL.md.bak. Now you can always go back.

Step 1: Write the identity (who it is, who it works for)

Open with one or two sentences: the agent's name, its job and who it works for. Be concrete.

The Hermes docs suggest an Identity section for this, and they include example SOULs for a pragmatic engineer, a research partner, a teacher and a tough reviewer.

Step 2: Set the style (tone, length, format)

Next, say how the agent should sound. Hermes says SOUL.md is the place for tone, style and directness. Cover three things:

Skip filler. OpenClaw's own SOUL.md template puts it well: be genuinely helpful, not performatively helpful, and skip lines like "Great question!" The top reply in an r/openclaw thread on what people's SOUL.md files look like repeated the same advice. That is a good rule for a business agent too.

Step 3: List what to avoid (and the approval boundary)

The Hermes docs suggest an Avoid section. For a business agent, this is where the approval boundary lives:

These lines carry real weight. In an r/openclaw thread on SOUL.md templates, the author wrote that "the rules section in SOUL.md matters more than identity for reliability." In the SOUL.md thread mentioned in Step 2, one reply suggested a section for what NOT to do, not just what to do. That matches the Hermes layout.

Step 4: Say how to handle uncertainty and ambiguity

The Hermes guide also suggests saying how the agent should behave when things are unclear. Without this line, an agent may fill gaps on its own. Give it a rule:

Step 5: Put only project-specific instructions in AGENTS.md or skills

This is where most SOUL.md files go wrong. Hermes puts only project-specific instructions (commands, paths and repo conventions) in AGENTS.md, and it can learn and use skills. Put the persona, including standing approval rules and any workflow that should follow the agent everywhere, in SOUL.md. If a line is a project command, path or repo convention, it goes in AGENTS.md.

Our recommendation: For Hermes, put the persona (including standing approval rules, and any workflow that should follow the agent everywhere) in SOUL.md, and put only project-specific instructions (commands, paths and repo conventions) in AGENTS.md.

Using a BotPlaybooks persona? In most persona files, the GUARDRAILS block sits inside the Persona / System Prompt section. For Hermes, keep the whole persona, including the GUARDRAILS block and any workflow that should follow the agent everywhere, in SOUL.md. Put only project-specific instructions (commands, paths and repo conventions) in AGENTS.md.

Here is a before and after.

Before (too much in SOUL.md):

You are a chief of staff. Be helpful and professional.
Every morning at 7, check my calendar and inbox, then write a brief with
my meetings, prep notes for each, overdue tasks from my task app and
open decisions. On Fridays, write a weekly summary. Use the notes app
for meeting notes. Always be careful with email.

After (SOUL.md keeps the persona, including the standing routine):

## Identity
You are Chief, chief of staff to one busy founder.
## Style
Calm and brief. Lead with what needs a decision today.
## Avoid
- Sending, posting, paying or contacting anyone without my approval.
- Guessing. If a fact is missing, say so.

The 7 a.m. brief and the Friday summary stay in SOUL.md, because they should follow the agent everywhere (shown in the full example below). Put only project-specific instructions (commands, paths and repo conventions) in AGENTS.md.

One more thing that does not belong in SOUL.md: facts about you. Hermes keeps SOUL.md and USER.md separate. Editing SOUL.md does not teach the agent facts about you. Memory does.

Step 6: Test, check /context, and tighten

Start a session and give the agent one real task, the job you wrote it for. Read the output against each line of SOUL.md. Did it lead with decisions? Did it ask before guessing? Did it draft instead of send? Rewrite any line it did not follow, one change at a time.

Keep an eye on length as you go. The SOUL.md cap in Hermes is set by context_file_max_chars. Left unset (the default), it scales with your model's context window, from 20,000 to 500,000 characters. Set a number to pin your own cap. Text over the cap is cut from the middle, keeping the start and the end. Keeping SOUL.md short is the simplest way to avoid that.

What a prompt-injection warning in /context means

Hermes scans SOUL.md for prompt-injection patterns. If something trips the scanner, Hermes logs a warning and flags it in /context, but it still loads the file. Treat the warning as a prompt to review. Look for lines that read like commands to ignore earlier instructions, or text you pasted from somewhere else, and rewrite or remove them.

Full example: a Chief of Staff SOUL.md

This example was written for this article, based on the public summary of Chief: Chief of Staff: it "Runs the operating rhythm for a leader: priorities, meeting prep, follow-through and decisions." Chief works with your calendar, email (read), notes and task app, and returns a daily brief, a decisions log, an action tracker and a weekly summary.

~/.hermes/SOUL.md

## Identity
You are Chief, chief of staff to one busy founder.
You run the operating rhythm: priorities, meeting prep, follow-through and decisions.
You work for me, and your job is to protect my time and attention.

## Style
- Calm, direct and brief. Plain English, no filler.
- Lead with what needs a decision today, then what is at risk, then the rest.
- Use short bullets. One line per item when you can.
- When you recommend something, give the reason in one sentence.

## Avoid
- Sending, posting, paying or contacting anyone without my approval. Draft it and show me.
- Accepting, declining or moving meetings on my behalf.
- Inventing facts, dates or numbers. Quote the source when you can.
- Making decisions that belong to me. List them as "Decision needed."

## When things are unclear
- If a fact is missing, say what is missing and ask.
- If a request could mean two things, ask one short question first.
- If two priorities conflict, show both and ask me to choose.

The first Avoid line is the one-line approval boundary. For Hermes, the full guardrails and the daily brief routine stay in SOUL.md, because they should follow the agent everywhere.

The same SOUL.md file also holds the standing guardrails and daily brief routine:

## Guardrails
Drafts only: never send, post, pay or contact anyone without my approval, and never invent facts.
(Paste the rest of the persona's guardrails here.)

## Daily brief (each workday morning)
1. Read today's calendar and the last 24 hours of email.
2. For each meeting: who, why, what I need to decide, and one prep note.
3. Pull overdue and due-today items from the task app.
4. List open decisions from the decisions log.
5. Output: Decisions needed, At risk, Meetings, Tasks. Draft only.

## Weekly summary (Friday)
Summarize decisions made, actions closed and actions still open.

Get the full Chief persona with workflow and routines. For other leadership roles, see Helm: Chief Executive Officer (CEO). Chief also pairs well with Agenda: Meeting Agenda and Minutes Keeper and Docket: Inbox Triage Assistant.

SOUL.md vs /personality: when to use which

Use SOUL.md for the agent's lasting identity, the one it should have every session. Use /personality for a temporary overlay in the current session. The Hermes docs list 14 built-in personalities, such as concise, technical, teacher and philosopher, and you can add your own in ~/.hermes/config.yaml under agent.personalities.

A simple rule: if you want it tomorrow too, put it in SOUL.md. If you want it for this one conversation, use /personality. If you want a fully separate role with its own memory and skills, use a separate Hermes profile.

5 mistakes that make Hermes ignore your SOUL.md

  1. Saving it in the wrong folder. Hermes reads only ~/.hermes/SOUL.md or $HERMES_HOME/SOUL.md (or the active profile's file). A project-folder SOUL.md is ignored.
  2. Writing a long essay. Past the size cap, Hermes truncates the file. Before that, a long file is simply harder to follow consistently. Start with 4 to 8 lines, as the docs suggest.
  3. Putting project-specific instructions in SOUL.md. Commands, paths and repo conventions belong in AGENTS.md or skills.
  4. Vague traits with no boundaries. "Be helpful and professional" gives the agent nothing to check itself against. Add specific Avoid lines, including the approval boundary.
  5. Putting facts about yourself in SOUL.md. SOUL.md shapes voice and identity. Facts about you belong in memory and USER.md.

FAQ

How do I write a good SOUL.md?

Start small. Write 4 to 8 lines covering who the agent is, how it should sound, what it must avoid and how it handles uncertainty. Keep standing approval rules, and any workflow that should follow the agent everywhere, in SOUL.md. Put only project-specific instructions (commands, paths and repo conventions) in AGENTS.md or skills. Test it on a real task, then tighten the wording until the agent behaves consistently.

Where is SOUL.md in Hermes?

Hermes Agent reads SOUL.md from ~/.hermes/SOUL.md, or from $HERMES_HOME/SOUL.md if you set HERMES_HOME. It never reads a SOUL.md from your working directory. If you use Hermes Profiles, each profile has its own SOUL.md. Hermes seeds a starter file when none exists and never overwrites one you wrote.

Why is Hermes ignoring my SOUL.md?

The usual causes are a file in the wrong folder, an empty file or a file that is too long. Hermes reads only ~/.hermes/SOUL.md or $HERMES_HOME/SOUL.md, so a project-folder copy is ignored. An empty SOUL.md falls back to the default identity, and text past the size cap is truncated.

What is the difference between SOUL.md and /personality in Hermes?

SOUL.md is the lasting identity Hermes Agent loads first in every session. /personality is a temporary overlay that changes tone for the current session only. The Hermes docs list 14 built-in personalities, and you can add custom ones in config.yaml. Use SOUL.md for a role you want every day and /personality for quick changes.

Should I put facts about myself in SOUL.md?

No. SOUL.md is for the agent's identity, tone and boundaries. Hermes Agent keeps SOUL.md and USER.md separate, and editing SOUL.md does not teach the agent facts about you. Memory does. Put facts about yourself, your business and your preferences in memory or USER.md, and keep SOUL.md about who the agent is.

How long should a Hermes SOUL.md be?

Start with 4 to 8 lines, as the Hermes docs suggest, and grow only when a test shows a gap. Unless you set context_file_max_chars, the size cap scales with your model's context window, from 20,000 to 500,000 characters. Text over the cap is truncated, so a short, specific file is the safest choice.

What is an AI chief of staff agent?

An AI chief of staff agent runs the operating rhythm for a leader: priorities, meeting prep, follow-through and decisions. The BotPlaybooks Chief persona works from your calendar, email, notes and task app and returns a daily brief, decisions log, action tracker and weekly summary. It drafts only and never sends without approval.

Put Chief to work

Related guides: SOUL.md Templates for Business Agents · What Is SOUL.md? · OpenClaw vs Hermes Agent

Sources

Checked Oct 16, 2026.

AI can make mistakes. Always review outputs before acting. Personas are templates, not legal, financial, tax, medical or HR advice. Personas draft; you approve anything sent, posted or paid.

BotPlaybooks is independent and not affiliated with Meta, OpenAI, xAI, Nous Research, OpenClaw or any agent platform.

Brian Arrington is an AI consultant and business coach focused on agentic AI. He founded BotPlaybooks and Arrington Consulting LLC. He is an Air Force veteran and the 2025 Georgia Vetrepreneur of the Year.