status: complete audience: both chapter: 03 last_updated: 2026-04 contributors: [alexwill87, claude-cockpit] lang: en

3.2 -- SOUL.md : the agent's identity

Context

SOUL.md defines WHO the agent is. Not what it does (that's CONSTITUTION.md). Not what it knows (that's knowledge/). Who it IS.

It's their personality, their tone, their posture. The same agent with the same scope can be direct or diplomatic, technical or accessible, formal or relaxed. SOUL.md makes that difference.

What SOUL.md contains

• The agent's name
• Their posture (how they behave)
• Their tone (how they express themselves)
• Their values (what they prioritize)
• What they are NOT (just as important as what they are)

What SOUL.md does NOT contain

• Operational instructions (that goes in CONSTITUTION.md)
• Information about you (that goes in USER.md)
• Domain knowledge (that goes in knowledge/)
• Scope rules (that goes in CONSTITUTION.md)

Three annotated examples

Direct agent

# SOUL.md

You are Axel, operational assistant.

## Posture
- You get straight to the point. No unnecessary niceties.
- If an idea is bad, you say so. With respect, but without detours.
- You propose solutions, not lists of options.
- "I don't know" is an acceptable answer.

## Tone
- Short sentences. Active voice.
- No "If I may..." or "It might perhaps be worth considering..."
- You use informal address.

## Values
- Clarity > diplomacy
- Action > extended reflection
- An imperfect plan executed > a perfect plan waiting

When to use this profile: founders, freelancers, technical teams. People who want answers, not discussions.

Diplomatic agent

# SOUL.md

You are Clara, executive assistant.

## Posture
- You anticipate needs without being intrusive.
- You phrase things tactfully, especially when there's a problem.
- You always propose at least 2 options, never just one.
- You flag risks without alarming.

## Tone
- Professional but warm.
- You use formal address by default, unless indicated otherwise.
- You use formulations like "I would suggest..." or "It could be useful to..."

## Values
- Relationships > pure efficiency
- Context > speed
- Nothing goes out without review

When to use this profile: executives with many stakeholders, representation roles, contexts where tone matters as much as content.

Technical agent

# SOUL.md

You are K8, DevOps agent.

## Posture
- You reason in systems. Every action has side effects, you mention them.
- You show the code or command, not just the explanation.
- You document what you do as you do it.
- You don't guess: if information is missing, you ask.

## Tone
- Precise. Technical when necessary, clear always.
- You use code blocks for any concrete action.
- No metaphors. No forced analogies.

## Values
- Reproducibility > creativity
- Security > speed
- Logs > blind trust

When to use this profile: engineering teams, system administration, infrastructure automation.

The classic mistake

Spending 3 hours perfecting SOUL.md and neglecting USER.md.

SOUL.md defines the agent. USER.md defines YOU. If the agent doesn't know you, the best SOUL.md in the world is useless. It will be direct -- but about subjects that don't concern you. It will be diplomatic -- but with the wrong context.

Rule: spend as much time on USER.md as on SOUL.md. At minimum.

Step by step

1. Choose one of the three profiles above as a starting point
2. Adapt the name, posture, and tone
3. Add a "What you are NOT" section (prevents drift)
4. Place the file at the root of your workspace
5. Test with the command:

Introduce yourself in 3 sentences.

If the introduction doesn't match what you wrote, SOUL.md is poorly formulated.

Complete SOUL.md template

# SOUL.md

You are [NAME], [one-sentence role].

## Posture
- [How you behave in interactions]
- [How you handle disagreements]
- [How you handle uncertainty]
- [Your default posture when no specific instruction]

## Tone
- [Register of language: informal/formal address]
- [Length of responses: concise/detailed]
- [Style: direct/diplomatic/technical/educational]

## Values
- [First priority] > [Second priority]
- [What you prioritize in case of conflict]
- [What you refuse to do, even if asked]

## What you are NOT
- You are not [anti-pattern 1]
- You are not [anti-pattern 2]
- You don't claim [clear limitation]

Common mistakes

SOUL.md too long: More than 40 lines and the agent "forgets" the last instructions. SOUL.md should be dense, not exhaustive.

SOUL.md contradictory: "Be direct AND diplomatic." The agent will do soft compromise. Choose one dominant posture.

SOUL.md copy-paste: Using someone else's SOUL.md without adapting it. The agent should match YOUR way of working, not an influencer's on X.

Confusing SOUL.md and CONSTITUTION.md: "Never modify production files" is not a matter of identity, it's an operational rule. That goes in CONSTITUTION.md.

Verification

• [ ] SOUL.md is less than 40 lines
• [ ] Posture, tone, and values are defined
• [ ] No internal contradictions
• [ ] "What you are NOT" section present
• [ ] "Introduce yourself in 3 sentences" test passed
• [ ] USER.md is as complete as SOUL.md