Keep SOUL.md out of the agent junk drawer

The bad SOUL.md starts innocently:

You are a senior engineer.
Use a concise tone.
The frontend lives in apps/web.
Run npm test before commits.
Never deploy without approval.
For content tasks, follow this 14-step editorial workflow.
Use the staging API unless NODE_ENV is production.
When the user is stressed, be warmer.
Prefer Postgres for durable state.
The sales agent should qualify leads with MEDDICC.

Nothing in that list is absurd by itself. The problem is that it mixes identity, repo instructions, safety rules, workflows, tool configuration, and role specialization into one file that is supposed to define who the agent is.

That is how SOUL.md becomes a junk drawer. The agent receives more text, but less signal.

For Hermes, SOUL.md has a specific job. The Hermes docs describe it as the durable persona file in HERMES_HOME, used as the agent’s primary identity in the prompt stack. The same page distinguishes that from project instructions in AGENTS.md, temporary /personality overlays, and named custom personalities in config.yaml Hermes Agent docs.

That separation is the useful idea. A strong SOUL.md does not try to control every future action. It gives the agent a stable center of gravity.

The test is whether the instruction should follow the agent everywhere

Use a simple review question:

Should this instruction still be true when the agent moves to a different project, role, repo, user request, and tool set?

If yes, it may belong in SOUL.md.

If no, put it somewhere narrower.

Instruction	Better home	Reason
“Be direct, but do not be careless.”	SOUL.md	Durable communication posture
“Ask before irreversible financial, legal, or deploy actions.”	SOUL.md or system policy	Durable boundary, though platform policy should enforce it
“Run npm run build before opening a PR.”	AGENTS.md	Project-specific workflow
“For customer escalation summaries, use this five-step process.”	Skill	Repeatable workflow with its own procedure
“Use the production profile for this tool.”	config.yaml	Configuration, not identity
“Be extra playful for this brainstorming session.”	/personality	Temporary mode switch

The distinction is not aesthetic. It changes how predictable the agent is.

Hermes documents SOUL.md as identity-level context: tone, communication style, directness, default interaction style, and how the agent handles uncertainty or disagreement. It also says one-off project instructions, file paths, repo conventions, and temporary workflow details belong in AGENTS.md, not SOUL.md Hermes Agent docs.

That maps well to a broader agent operating model. Identity should be stable. Project instructions should be local. Workflows should be packaged. Configuration should be explicit.

What a good SOUL.md should actually carry

Keep it short enough that a human can audit it line by line.

The useful contents usually fit into four groups:

Section	Job
Soul	The agent’s role and relationship with the user
Voice	How it communicates under normal conditions
Operations	How it makes routine decisions when the user has not specified every detail
Restrictions	Hard behavioral boundaries that should not drift by project

Here is the shape:

# Soul

You are a pragmatic senior technical operator. You work with the user as a
clear-eyed collaborator: useful, candid, and careful with uncertainty.

## Voice

- Lead with the concrete answer.
- Be concise unless the decision needs depth.
- Push back when the user's framing hides risk.
- Do not flatter, hype, or pad.

## Operations

- Identify irreversible actions before taking them.
- Rank safety, correctness, and user intent before speed.
- Prefer boring, inspectable systems over clever hidden behavior.
- When facts may have changed, verify before advising.

## Restrictions

- Do not invent evidence, credentials, or operational access.
- Do not make legal, medical, financial, security, or deployment decisions without clear limits and approval.
- Do not hide uncertainty behind confident language.
- Do not treat temporary user mood as a permanent personality change.

This is not enough to run a repository. It is not supposed to be.

It is enough to keep the agent from changing character every time it sees a different issue, tool, or folder.

What to move out

Most bloated SOUL.md files are trying to solve real problems in the wrong layer.

Project rules belong in AGENTS.md

AGENTS.md exists to give coding agents project-specific instructions. The AGENTS.md site frames it as a dedicated place for agent context such as setup commands, tests, code style, and security considerations AGENTS.md.

That is where repo layout, local commands, branch naming, review expectations, ports, package manager choices, and test policy should live.

This matters because project instructions should change when the project changes. A frontend repo, infrastructure repo, content repo, and data pipeline should not all inherit the same build commands just because the agent has one global personality file.

Repeatable workflows belong in skills

If the instruction is a procedure, it probably wants a skill.

OpenAI’s Codex Skills documentation describes a skill as a directory with a required SKILL.md plus optional scripts, references, and assets. Skills are loaded through progressive disclosure: Codex starts with name, description, and path, then reads the full skill when the task matches OpenAI Codex Skills.

That is a better place for workflows such as:

• reviewing an airoweb article
• preparing a release note
• triaging a production incident
• writing a customer escalation brief
• auditing a Terraform change

Those are not personality. They are operating procedures. They need triggers, inputs, steps, checks, and sometimes supporting files. If they sit in SOUL.md, they become always-on context even when irrelevant.

Temporary modes belong in /personality

Hermes distinguishes the durable SOUL.md baseline from /personality, which acts as a session-level overlay. The docs give examples such as keeping a pragmatic default while switching temporarily to a teacher or creative mode Hermes Agent docs.

That is the right boundary.

Do not edit the permanent identity file because you want one unusually patient tutoring session or one more expansive brainstorming session. Use the temporary mode and let it expire with the session.

Named personas and tool settings belong in config

Hermes also supports named custom personalities under agent.personalities in ~/.hermes/config.yaml Hermes Agent docs. That is useful when a user wants reusable modes without mutating the default identity.

Configuration should remain configuration. The same applies to model choices, tool profiles, provider settings, environment-specific behavior, and other settings that should be parsed by software rather than interpreted as prose personality.

When one SOUL.md is the wrong model

The supplied notes point to an advanced pattern: separate specialized profiles instead of forcing every role into one SOUL.md.

That is the right instinct, with one constraint. Do not turn specialization into role soup.

A broker, senior engineer, operations manager, and salesperson may need different voices, defaults, and risk boundaries. The broker may need stricter language around financial advice and approval. The engineer may need stronger defaults around tests and reversibility. The operations manager may need a bias toward escalation clarity and audit trails. The salesperson may need limits around claims, commitments, and customer data.

Trying to combine all of that into one global identity gives the agent contradictions:

• be brief, but also deeply consultative
• optimize for closing, but never persuade beyond evidence
• act autonomously, but wait for approval
• be technical, but avoid detail
• be warm, but be blunt

Some tension is normal. But if the same file tries to make one agent excellent at every role, it usually makes the agent mushy.

Use a stable default SOUL.md for baseline character. Use named personalities, skills, project instructions, or separate agent profiles for specialized work.

What can go wrong

The main risk is not that the agent ignores a long SOUL.md. The worse failure is selective obedience.

Large instruction files create more places for conflict. The agent may follow a workflow rule while missing a safety boundary. It may inherit an old project convention in a new repo. It may treat a temporary preference as permanent. It may burn context on personality lore when the actual task needs source files, error logs, or review notes.

There is also a security angle. Hermes says SOUL.md content is injected after security scanning and truncation, and advises keeping it focused rather than using it for strange meta-instructions Hermes Agent docs. That does not make SOUL.md a security boundary. It is still an instruction file. Platform policy, tool permissions, approvals, tests, and review gates have to carry the real control.

A good SOUL.md can make safer behavior more likely. It cannot prove safety.

A practical review pass

Take an existing SOUL.md and mark each line:

I = identity, voice, values, durable boundary
P = project or repo instruction
W = repeatable workflow
C = configuration
T = temporary mode or mood
U = unsupported claim or vague aspiration

Then move everything except I.

For the remaining lines, ask:

• Is this stable across projects?
• Is it specific enough to change behavior?
• Does it conflict with another line?
• Would a user understand what the agent will do differently?
• Is this better enforced by a tool permission, approval gate, or test?

The last question matters. “Never deploy without approval” is a good behavioral boundary, but it should not live only as prose in a personality file. The deployment tool should require approval too.

The useful size is small

The Persian source notes suggested roughly 50 to 80 smart lines. That is a reasonable ceiling, not a quota.

Many teams can do better with 25 lines.

The point is not minimalism for its own sake. The point is auditability. A SOUL.md should be short enough that the owner can notice drift, contradiction, and filler. After a few weeks of real work, revise the lines that did not hold up. Add a boundary where the agent repeatedly drifted. Delete instructions that never mattered.

Treat SOUL.md like a durable identity contract, not a memory dump.

The best version tells the agent who it is, how it should speak, what it values, and where it must not cross the line. Everything else deserves a narrower home.