This is the canonical reference for what content belongs in each OpenClaw agent workspace file. Use it when creating a new agent, auditing an existing agent's workspace, or resolving questions about where a piece of content should live.
The spec establishes clear boundaries so that content is never duplicated, misplaced, or ambiguous across files.
An OpenClaw agent workspace contains 9 definition files and 2 directories:
| # | File / Directory | Purpose | Required |
|---|---|---|---|
| 1 | IDENTITY.md | Name, creature, emoji, vibe — the "business card" | ✅ |
| 2 | SOUL.md | Personality, values, role, boundaries — who you are | ✅ |
| 3 | AGENTS.md | Working conventions, session startup, safety rules, processes | ✅ |
| 4 | USER.md | About the human: name, timezone, contact, preferences | ✅ |
| 5 | TOOLS.md | Environment config: paths, hosts, API keys, device names | ✅ |
| 6 | HEARTBEAT.md | Periodic check checklist (runs every heartbeat interval) | Optional |
| 7 | MEMORY.md | Curated long-term memory (lessons, decisions, context) | Optional |
| 8 | BOOT.md | Gateway startup checklist (runs once per gateway restart) | Optional |
| 9 | BOOTSTRAP.md | One-time first-run ritual (delete after execution) | Ephemeral |
| 10 | skills/ | Portable capability modules (SKILL.md + references/scripts) | Optional |
| 11 | memory/ | Raw daily logs (YYYY-MM-DD.md) | Optional |
Any other
.mdfile with an ALL-CAPS stem in the workspace root is not part of the spec and should be moved elsewhere or added to this spec if it belongs.
Agent definition files = WHO the agent is (identity, personality, unique — not transferable between agents). Skills = WHAT the agent knows how to do (portable, installable, assignable to any agent).
An agent's workspace files define a unique individual. Skills are interchangeable capabilities that can be installed on any agent via ClawHub or local assignment.
Declares the agent's name, form, and surface-level attributes — the "business card."
- Name — the agent's given name (e.g., Claudia, Devdas, Archibald)
- Creature — what the agent is (e.g., "AI agent — software developer")
- How to address me — pronoun hint for third-person references (e.g., "How is she doing?")
- Emoji — single emoji used as the agent's visual shorthand
- Vibe — 1–3 adjectives summarizing the agent's surface personality
- Avatar — path to an avatar image
- Role Title — formal role name if distinct from creature (e.g., "Operations Director")
- Team(s) — team membership (though canonical source is the team-genetics block in AGENTS.md)
| Does NOT belong here | Goes in |
|---|---|
| Personality, values, behavioral principles | SOUL.md |
| What the agent does (responsibilities, mission) | SOUL.md |
| Working conventions, processes | AGENTS.md |
| Operational context about the human | USER.md |
- Vibe drift into SOUL territory. A vibe entry like "Methodical, thorough, quiet" is fine as adjective labels. But if those same traits are re-described as behavioral personality in SOUL.md, the boundary blurs. The rule: IDENTITY.md vibe is a label (adjectives); SOUL.md is the explanation (behavioral description of what those adjectives mean in practice).
- Missing Role Title. If an agent has a formal role (e.g., Operations Director), it should appear in IDENTITY.md — not only in SOUL.md.
Defines the agent's personality, values, mission, role, and behavioral boundaries — the "character sheet."
- Core Truths / Traits — behavioral principles that define how the agent operates (not what it does, but how it approaches everything)
- Role — the agent's mission and key responsibilities, stated as outcomes
- Boundaries — what the agent will NOT do, failure modes to avoid, scope limits
- Continuity — reminder to read memory files and maintain context across sessions
- Vibe — expanded personality description (beyond the label in IDENTITY.md)
- Default Behavior — base operating mode (e.g., "Do It All" — parallelize, don't ask permission)
- CMMI / Process Gates — hard gates and soft gates the agent must follow (for agents with process discipline requirements)
- Batch Execution Mode — orchestration model (relevant for orchestrator agents)
- Working Style — how the agent approaches work at a high level (e.g., "read existing code before changing it")
- Anti-Patterns — what "bad" looks like for this agent
| Does NOT belong here | Goes in |
|---|---|
| Name, emoji, avatar, creature type | IDENTITY.md |
| Session startup procedures, memory protocols | AGENTS.md |
| Environment config (paths, repos, SSH) | TOOLS.md |
| Who the human is, their preferences | USER.md |
| Tool methodology (how to use specific tools) | skills/ |
| Heartbeat schedule, periodic checks | HEARTBEAT.md |
- SOUL.md as an employee handbook. SOUL.md should contain the principle ("You manage projects with structure — every project has a plan, every project ends with a review"); the detailed gate definitions belong in AGENTS.md or a referenced process document.
- Operational rules masquerading as soul. Process rules like "No Work Without a Task" or "No Unmonitored Delegations" are process rules, not personality. They describe what the agent must do, not who the agent is.
- Missing anti-patterns section. An explicit "What Bad Looks Like" section helps agents self-correct. "Critical Rules" or prohibitions are useful but not the same as behavioral anti-patterns.
- Environment paths in SOUL.md. Vault paths, directory paths, or any environment config belongs in TOOLS.md, not SOUL.md.
Defines the agent's working conventions, operational processes, memory management, and safety rules — the "employee handbook."
- Workspace Hygiene — where files go, what belongs in the workspace vs. work directories
- Session Startup — what to read and in what order every session
- Memory Protocol — how daily notes and long-term memory work
- Safety Rules — data exfiltration, destructive commands, external actions
- External vs Internal — what's safe to do freely vs. what requires permission
- Group Chat Behavior — how to behave in shared channels (when to speak, when to stay silent)
- Reaction Guidelines — emoji reaction conventions per platform
- Platform Formatting — markdown rules per platform (Discord, WhatsApp, etc.)
- Tool Pointers — brief pointer to TOOLS.md and skills/ for tool configuration
- Heartbeat Guidelines — general heartbeat philosophy (detailed schedule goes in HEARTBEAT.md)
- Edit Hygiene — read-before-edit rule to prevent stale-context failures
- Teams — team-genetics managed block listing team memberships
- Process Gates — detailed operational gates (CMMI hard/soft gates, if applicable)
- Forward Motion Rules — project momentum conventions (idle detection, phase sequencing)
- Change Management — spec-driven change management procedures
| Does NOT belong here | Goes in |
|---|---|
| Personality, values, mission, vibe | SOUL.md |
| Name, emoji, avatar | IDENTITY.md |
| Human's personal details | USER.md |
| Environment paths, SSH, API keys | TOOLS.md |
| Periodic check schedule | HEARTBEAT.md |
| Tool methodology (how to use tools) | skills/ |
| Long-term curated memories | MEMORY.md |
- Massive AGENTS.md duplication across agents. If multiple agents have nearly identical AGENTS.md files, the shared content should live in a common template or team-genetics shared file, with AGENTS.md containing only agent-specific overrides.
- Org-wide policy scattered in AGENTS.md. Organizational policies should live in shared process documents or be injected via team-genetics — not in individual AGENTS.md files.
- AGENTS.md as TOOLS.md overflow. Environment-specific content (repo paths, network config) should not appear in AGENTS.md — that content belongs in TOOLS.md.
Describes who the agent serves — the human principal's identity, context, and preferences.
- Name — the human's name
- What to call them — how the agent should address them
- Timezone — for scheduling context
- Contact details — Telegram, email, etc. (as relevant)
- Pronouns — the human's pronouns
- Notes — standing preferences (e.g., "repos must be private," "use this email for commits")
- Context — evolving notes about what the human cares about, their projects, preferences, personality
- Escalation paths — who else the agent can contact if the human is unavailable
| Does NOT belong here | Goes in |
|---|---|
| Agent's own personality or values | SOUL.md |
| Agent's own name or identity | IDENTITY.md |
| Working conventions for the agent | AGENTS.md |
| Environment config (paths, repos) | TOOLS.md |
- Identical USER.md across all agents. The Context section should diverge per agent — each agent has a different relationship with the human. A developer agent should know coding preferences; an archivist should know archiving preferences; an orchestrator should know strategic priorities.
- Missing context that exists elsewhere. USER.md should have the preference ("Rupert wants repos private"); TOOLS.md should have the implementation ("git config user.email rupert.barrow@lilo.org"). Don't duplicate both in both files.
- Empty Context section. The Context section should be actively populated over time as the agent learns about the human.
Records the agent's local environment configuration — paths, hosts, API notes, and tool-specific setup details.
- Work Directories — canonical paths for repos, projects, temp files
- Network — local hostnames, SSH aliases, port mappings
- Git — commit email, branch conventions, repo defaults
- Repos — paths to agent-specific and shared repositories
- Tool-Specific Notes — camera names, TTS voices, speaker names, vault paths
- Platform-Specific Workarounds — known limitations and workarounds (e.g., media tool path restrictions)
- Document Management — conventions for publishing, reviewing, and indexing documents
- Browser Policy — headless vs. headed browser rules
- Web Scraping — fallback strategies for anti-scraping sites
| Does NOT belong here | Goes in |
|---|---|
| How to USE a tool (methodology) | skills/ SKILL.md |
| Agent personality or values | SOUL.md |
| Working conventions, safety rules | AGENTS.md |
| Human's preferences | USER.md |
| Periodic check schedules | HEARTBEAT.md |
- TOOLS.md as second AGENTS.md. Operational rules ("NEVER restart the gateway yourself," workspace hygiene rules) are working conventions → AGENTS.md. TOOLS.md should only contain the config facts (paths, hostnames, tool settings).
- Duplicated workspace hygiene. Workspace hygiene rules should have one canonical location (AGENTS.md) with no duplication in TOOLS.md.
- Methodology in TOOLS.md. Full step-by-step procedures (e.g., document management protocol) are methodology → should be a skill. TOOLS.md should only note the relevant IDs and paths.
- Process rules in team-injected content. Team-genetics content in TOOLS.md is fine if it's purely config (tool names, CI systems). Process rules ("PRs require at least one approval") belong in AGENTS.md team blocks.
Defines what the agent should check periodically during heartbeat polls — the "monitoring schedule."
- None strictly required — an empty file (or comments-only) means "no periodic checks needed"
- Lightweight Checks — quick checks to run every heartbeat (deliverable status, idle detection, follow-ups)
- What NOT to Do — explicit exclusions to prevent heartbeat bloat (heavy scans, dashboard updates that have their own crons)
- Reference Data — IDs, paths, or constants needed by heartbeat checks (Gist IDs, project plan paths)
- Reminders — time-sensitive reminders the agent should surface
| Does NOT belong here | Goes in |
|---|---|
| Heartbeat philosophy/guidelines (when to reach out, when to stay quiet) | AGENTS.md |
| General monitoring strategy | AGENTS.md or SOUL.md |
| Cron definitions | OpenClaw cron config (not a workspace file) |
| Daily operational logs | memory/ |
| Long-term project tracking | Project plan files |
- Empty heartbeat files with no guidance. An empty HEARTBEAT.md is valid but should be a conscious choice, not neglect. Consider whether the agent would benefit from periodic checks (e.g., CI status for a developer, new content for an archivist).
- Heartbeat guidelines in AGENTS.md instead of HEARTBEAT.md. AGENTS.md holds the guidelines (philosophy), HEARTBEAT.md holds the specific checklist. Keep the boundary clean.
Stores the agent's long-term curated memories — distilled insights, lessons learned, and significant events that survive across sessions.
- No fixed structure required — the format should emerge organically from the agent's experience
- Lessons Learned — insights from mistakes, successes, and observations
- Key Decisions — significant decisions made and their rationale
- People & Relationships — context about collaborators, stakeholders, recurring contacts
- Project Context — high-level notes on active and past projects
- Preferences & Conventions — things the agent has learned about how its human likes things done
| Does NOT belong here | Goes in |
|---|---|
| Raw daily logs | memory/YYYY-MM-DD.md |
| Agent personality or values | SOUL.md |
| Working conventions | AGENTS.md |
| Human's standing preferences (static) | USER.md |
| Environment config | TOOLS.md |
- Treating MEMORY.md as a daily log. MEMORY.md is curated long-term memory, not a chronological dump. Daily events go in memory/YYYY-MM-DD.md; only the distilled insight from those events goes into MEMORY.md.
- Loading MEMORY.md in shared contexts. MEMORY.md may contain personal context about the human. It should only be loaded in direct (main session) conversations, never in group chats or shared channels. This is a security boundary.
- Never pruning. MEMORY.md should be periodically reviewed and outdated entries removed. It's a living document, not an append-only log.
- Duplicating USER.md content. Learned preferences about the human that are stable should migrate to USER.md. MEMORY.md is for evolving context, not permanent facts.
Optional gateway startup checklist — executed once when the OpenClaw gateway starts (not on every session). Handled by the built-in boot-md hook, which fires on the gateway:startup event. Requires hooks.internal.enabled to be active; without that hook enabled, the file is simply ignored.
- No fixed structure required — keep it short and actionable
- A brief checklist of startup tasks (health checks, notifications, status reports)
- Use the
messagetool for any outbound sends
| Does NOT belong here | Goes in |
|---|---|
| Agent personality or identity | SOUL.md / IDENTITY.md |
| Session-level periodic tasks | HEARTBEAT.md |
| One-time first-run setup | BOOTSTRAP.md |
| Operational procedures | AGENTS.md |
| Environment config | TOOLS.md |
- Long startup scripts. BOOT.md runs on gateway restart. Keep it short — a few quick checks, not a full workflow. Heavy work should be triggered as background tasks or crons.
- Confusing BOOT.md with HEARTBEAT.md. BOOT.md runs once at gateway startup. HEARTBEAT.md runs periodically during the session. Don't put recurring checks in BOOT.md.
- Confusing BOOT.md with BOOTSTRAP.md. BOOT.md runs on every gateway restart. BOOTSTRAP.md is a one-time first-run ritual that gets deleted after execution.
One-time first-run ritual for a brand-new agent. Only created when bootstrapping a new workspace. The agent reads it on first session, executes the setup instructions, then deletes the file. It is the agent's "birth certificate."
- No fixed structure required — typically contains first-run setup instructions
- Identity setup instructions (fill in IDENTITY.md, SOUL.md)
- Initial configuration tasks
- "Delete this file when done" instruction at the end
| Does NOT belong here | Goes in |
|---|---|
| Recurring startup tasks | BOOT.md |
| Periodic checks | HEARTBEAT.md |
| Permanent operating instructions | AGENTS.md |
| Agent personality | SOUL.md |
- Not deleting after first run. BOOTSTRAP.md is meant to be ephemeral. If it persists after the agent's first session, it will be re-executed on every session, causing duplicate setup work.
- Putting permanent instructions here. Anything that should persist goes in AGENTS.md, SOUL.md, or the appropriate file. BOOTSTRAP.md is strictly one-time.
- Created during agent workspace scaffolding
- Read and executed on the agent's first session
- Deleted by the agent after execution
- Should NOT exist in a running agent's workspace — its presence after first run is a lint warning
Houses portable, installable capability modules — each skill defines methodology for a specific task domain.
skills/
skill-name/
SKILL.md # Required: instructions, methodology, triggers
references/ # Optional: reference material, examples
scripts/ # Optional: automation scripts
templates/ # Optional: output templates
- Methodology — step-by-step procedures for a task type
- Triggers — when this skill should be activated (keywords, patterns)
- Reference Material — specifications, examples, templates
- Scripts — automation for the skill's domain
| Does NOT belong here | Goes in |
|---|---|
| Agent identity or personality | SOUL.md / IDENTITY.md |
| Agent-specific environment config | TOOLS.md |
| Working conventions or safety rules | AGENTS.md |
| Human preferences | USER.md |
| Long-term memory | MEMORY.md |
- Skills that encode identity. A skill should work for ANY agent it's installed on. If a skill references "you are Claudia" or "your role is Operations Director," it's leaking identity into a portable module.
- Environment paths in skills. Skills should not hardcode paths like
/Volumes/OPENCLAW/CLAUDIA/.... Environment-specific config belongs in TOOLS.md; the skill should reference environment variables or conventions. - Methodology in TOOLS.md instead of skills. Full procedural protocols are methodology → should be a skill (e.g.,
document-management/SKILL.md). TOOLS.md should only note the relevant IDs and paths. - Process rules in skills. Skills define how to do X. Organizational process rules (gates, approval requirements) belong in AGENTS.md. A skill can reference a gate ("check with AGENTS.md before deploying") but shouldn't define it.
Stores raw daily operational logs — what happened each day, unfiltered and chronological.
memory/
YYYY-MM-DD.md # Daily log for that date
heartbeat-state.json # Heartbeat tracking state (optional)
| Does NOT belong here | Goes in |
|---|---|
| Curated long-term insights | MEMORY.md |
| Agent personality or config | SOUL.md / AGENTS.md |
| Standing human preferences | USER.md |
- Never writing daily logs. Some agents skip daily logging, losing operational context between sessions.
- Over-logging. Recording every tool call and minor action. Focus on decisions, events, and context that future sessions will need.
| Content Type | Canonical File | NOT in |
|---|---|---|
| Agent name, emoji, creature | IDENTITY.md | SOUL.md, AGENTS.md |
| Personality, values, mission | SOUL.md | IDENTITY.md, AGENTS.md |
| Key responsibilities (outcomes) | SOUL.md | AGENTS.md, skills/ |
| Behavioral anti-patterns | SOUL.md | AGENTS.md |
| Session startup procedure | AGENTS.md | SOUL.md |
| Memory protocol | AGENTS.md | SOUL.md, MEMORY.md |
| Safety rules | AGENTS.md | SOUL.md |
| Process gates (detailed) | AGENTS.md | SOUL.md |
| Group chat behavior | AGENTS.md | SOUL.md |
| Team membership | AGENTS.md (team-genetics) | IDENTITY.md |
| Human's name, contact, timezone | USER.md | SOUL.md, AGENTS.md |
| Human's preferences (stable) | USER.md | MEMORY.md |
| Environment paths, hosts | TOOLS.md | AGENTS.md, SOUL.md |
| Tool-specific config | TOOLS.md | skills/ |
| Tool methodology | skills/ | TOOLS.md |
| Periodic check items | HEARTBEAT.md | AGENTS.md |
| Heartbeat philosophy | AGENTS.md | HEARTBEAT.md |
| Curated long-term memory | MEMORY.md | memory/ |
| Daily operational logs | memory/ | MEMORY.md |
| Portable capabilities | skills/ | SOUL.md, AGENTS.md |
SOUL.md, IDENTITY.md, AGENTS.md, USER.md, TOOLS.md, HEARTBEAT.md, MEMORY.md, skills/
- Vibe drift from IDENTITY.md into SOUL.md (all agents)
- Missing Role Title in IDENTITY.md
- SOUL.md as employee handbook — process gates in soul
- Operational rules in SOUL.md instead of AGENTS.md
- Missing anti-patterns section in SOUL.md (all agents)
- Environment paths in SOUL.md instead of TOOLS.md
- Massive AGENTS.md duplication across agents (all agents)
- Org-wide policy scattered in individual AGENTS.md files
- AGENTS.md as TOOLS.md overflow with env config
- Identical USER.md with empty Context sections (all agents)
- Duplicated preferences in USER.md and TOOLS.md
- TOOLS.md as second AGENTS.md with operational rules
- Methodology in TOOLS.md instead of skills/
- Process rules in team-injected TOOLS.md blocks
- Empty HEARTBEAT.md with no rationale for emptiness
- Skills that could encode identity or hardcode paths (structural risk)
- IDENTITY.md vibe = adjective labels; SOUL.md = behavioral explanations
- Role title belongs in IDENTITY.md (pointer), full description in SOUL.md
- SOUL.md = who you are (principles); AGENTS.md = how you work (procedures)
- Process gate principles in SOUL.md; gate definitions in AGENTS.md
- Anti-patterns = SOUL.md; prohibitions/rules = AGENTS.md
- Shared AGENTS.md content → team-genetics templates
- Org-wide policy → shared process documents, not individual AGENTS.md
- Human preferences (stable facts) → USER.md; learned context (evolving) → MEMORY.md
- Environment paths → TOOLS.md only (never AGENTS.md or SOUL.md)
- Tool methodology → skills/; tool config → TOOLS.md
- Methodology protocols → skill; config IDs/paths → TOOLS.md
- Process rules in TOOLS.md team blocks → AGENTS.md team blocks
- Heartbeat philosophy → AGENTS.md; heartbeat checklist → HEARTBEAT.md
- MEMORY.md = curated insights; memory/ = raw daily logs
- Skills must be identity-agnostic and path-agnostic
- USER.md Context should be agent-specific (different per agent)
- MEMORY.md only loaded in main sessions (security boundary)
- Empty HEARTBEAT.md is valid but should be a conscious choice, not neglect