Markdown-File Agent Definition is the design pattern of expressing an AI agent's complete configuration — identity, personality, capabilities, memory, and schedule — as a set of human-readable Markdown files rather than YAML configs, JSON manifests, or compiled code. Pioneered by 📝OpenClaw and echoed by 📝Claude Code, the pattern treats the agent's specification the way a new employee reads a runbook: as prose to be reasoned over, edited in place, and version-controlled like any other text file.
Why Markdown, Not YAML or Code
The conventional approach buries agent behavior in schemas, function definitions, or system-prompt strings hidden inside application code. That makes the agent opaque — operators cannot inspect it without reading source, and small behavioral changes require a release. Markdown inverts the pattern. Personality lives in 📝SOUL.md. Role and boundaries live in 📝IDENTITY.md. Capabilities live in 📝TOOLS.md and 📝SKILLS.md. The model reads them the same way it reads any other context — as instructions, not as compiled artifacts. Editing an agent is editing prose, which means operators rather than engineers own the surface where the agent's behavior is actually defined.
The Eight-File Anatomy
OpenClaw's canonical agent definition uses eight markdown files, each holding exactly one structural concern:
- 📝BOOTSTRAP.md — initialization logic and module load order
- SOUL.md — temperament, values, and conversational voice
- IDENTITY.md — name, role, organizational affiliation, operational boundaries
- TOOLS.md — inventory of APIs and external capabilities the agent may call
- SKILLS.md — installable capability modules with their own SKILL.md interfaces
- 📝MEMORY.md — curated long-term context loaded every session
- 📝USER.md — long-term dossier on the human user
- 📝HEARTBEAT.md — autonomous pulse, scheduled tasks, and self-reflection loops
For multi-agent workspaces, 📝AGENTS.md joins the set as a registry of specialized sub-agents the primary can delegate to. The same vocabulary appears in Claude Code under filenames like CLAUDE.md and MEMORY.md — the pattern travels because the abstraction is sound.
What This Enables
Three properties fall out of the design that proprietary agent frameworks struggle to match:
- Auditability — an operator can read the agent's entire definition without source-diving. If it isn't in the files, the agent doesn't do it.
- Forkability — copying an agent means copying a directory. Templating new specialists means duplicating files and editing the parts that differ. No re-implementation.
- Version-controllability — every behavioral change is a Git diff. Reverting to last week's personality is
git checkout. Reviewing changes is a pull request.
A fourth property emerges in practice: legibility for the model itself. Large language models read natural language better than they read schemas, which is why 📝Token Optimization discipline starts with trimming these files rather than rewriting wrappers.
When the Pattern Fits — and When It Doesn't
Markdown-file definition shines for long-lived, evolving agents that operators want to inspect, edit, and template. It is less compelling for ephemeral one-shot agents, deterministic toolchains, or workloads where strict schema validation matters more than human readability. The pattern's strength is also its limit: it relies on the model's interpretation of prose rather than the certainty of a parsed manifest. For systems where that tradeoff is acceptable, the legibility gains compound — and for agents intended to evolve alongside the humans they collaborate with, no other pattern comes close.
Related
- 📝OpenClaw — the open-source platform that canonized the pattern
- 📝Claude Code — Anthropic's coding agent built around the same file conventions
- 📝The Augmentation Stack — Memory → Mind → Mouth architecture the files implement
- 📝Collaborative Augmentation — the broader framework for agent-human collaboration
- 📝OpenClaw Glossary — terms used across the OpenClaw cluster
The markdown-file pattern was the moment agent architecture stopped feeling like configuration and started feeling like collaboration. When I can read SOUL.md and recognize an agent's voice, edit IDENTITY.md and watch the role tighten, or rewrite a paragraph in TOOLS.md to change how a capability gets used, the system stops being a black box and becomes a partner whose self-conception I can see. That legibility is what makes augmentation feel possible rather than abstract.