The 3-File Framework: How SOUL.md + AGENTS.md + USER.md Actually Works

Three text files. No code. No complex setup. Just the system that powers our 4 production AI agents every single day.

I've been running AI agents in production for over a year. Not chatbots — actual agents that do real work: research, content, operations, monitoring. Every day. Autonomously.

The secret isn't a fancy framework, an expensive platform, or some proprietary tool. It's three Markdown files.

That's it. Let me break down each one.

File 1: SOUL.md — Identity

Why does identity matter? Because without it, your agent is a different entity every conversation. Sometimes formal, sometimes casual. Sometimes helpful, sometimes adding disclaimers to everything. You can't trust an agent that doesn't know who it is.

A SOUL.md includes:

• Name and nature — Is it Scout? Atlas? Bolt? What kind of entity is it?
• Core personality — Direct? Casual? Creative? This sets the tone for every interaction.
• Communication rules — Bullet points over paragraphs? Lead with answers? No disclaimers?
• Boundaries — What it should never do, regardless of context.

# SOUL.md — Scout

*Scout is a research specialist. Fast, thorough, and direct.*

## Core
Research-first assistant. Finds information, validates claims,
and delivers concise reports. Hates fluff. Loves data.

## Communication
- Lead with the answer, then explain
- Use bullet points
- Cite sources
- If unsure, say "I'm not confident about this"

## Boundaries
- Never fabricate data or sources
- Never send external communications without approval

The magic: every session, your agent reads this file first. It doesn't "remember" — it re-establishes its identity. Consistently. Every time.

File 2: AGENTS.md — Operating Manual

This is where chatbots and agents truly diverge. A chatbot waits for instructions. An agent with a good AGENTS.md knows what to do without being told.

Key sections:

• Autonomy rules — What it can do freely (whitelist), what needs approval (greylist), what it must never do (blacklist)
• Retry logic — How many times to try before asking for help (we use 5 attempts minimum)
• Memory protocol — How to log work, update daily notes, maintain long-term memory
• Error handling — What to do when tools fail, APIs break, or data is missing
• Collaboration rules — How to work with other agents (if you have multiple)

# Autonomy Rules

**Do freely:** Read files, web search, calculations, internal optimization
**Ask first:** External emails, public posts, spending money
**Never do:** Delete data, share secrets, bypass security

The result: an agent that can work independently for hours, making smart decisions about what to do and what to escalate.

File 3: USER.md — Context

This is the most underrated file. Most people focus on prompt engineering — making the AI smarter. But the biggest unlock is making the AI understand you.

• Personal info — Name, pronouns, timezone, how you want to be addressed
• Business context — What you do, who your clients are, what matters to your business
• Work style — Do you want detailed explanations or bullet points? Proactive suggestions or wait for instructions?
• Tools & accounts — What systems the agent has access to

When your agent reads USER.md every session, it doesn't just know you — it knows how to serve you. The right tone. The right level of detail. The right balance of autonomy.

How it works together

No memory issues. No personality drift. No re-explaining your preferences. Just a reliable agent that knows exactly who it is, how it works, and who it serves.

Why text files?

People ask: "Why not a database? Why not a config file? Why not a platform?"

Three reasons:

1. Portable. Text files work with any AI model. ChatGPT, Claude, Gemini, local models. No vendor lock-in.
2. Readable. You can open them, read them, edit them. No abstraction layers hiding your agent's behavior.
3. Version-controlled. Put them in Git. Track changes. Roll back when something breaks. Your agent's identity has a commit history.

The best systems are the ones humans can understand and modify. Three Markdown files is about as simple as it gets.

Getting started

You don't need to be technical. You don't need to write code. Here's the process:

1. Generate a SOUL.md — Use our free generator to create your first one in 2 minutes.
2. Write a USER.md — Start with your name, timezone, and "what I want from my agent."
3. Draft an AGENTS.md — Begin with simple autonomy rules: what's free, what needs approval.
4. Iterate. — Run it for a week. See what works. Adjust. The files are living documents.