Skip to content
Back to search

openclaw-workspace

Claude Code skill for maintaining and optimizing OpenClaw workspace files (AGENTS.md, SOUL.md, TOOLS.md, MEMORY.md, checklists)

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/win4r--openclaw-workspace/badge.svg)](/listings/win4r--openclaw-workspace)

HTML

<a href="/listings/win4r--openclaw-workspace"><img src="/api/listings/win4r--openclaw-workspace/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Creates workspace files in the correct order (SOUL → AGENTS → IDENTITY → USER → TOOLS → MEMORY → optional files). Ensures the boot sequence, security gates, and checklist table are all properly wired up.

**Minimal viable workspace:** `AGENTS.md` + `SOUL.md` + `TOOLS.md`. Everything else is optional.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 199 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: openclaw-workspace
  3. description: Use when maintaining or optimizing OpenClaw workspace files — AGENTS.md, TOOLS.md, SOUL.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md, and related checklists and memory files. Covers workspace auditing, token budget analysis, new agent workspace setup from scratch, memory distillation, and cross-file consistency reviews.
  4. ---
  5. # OpenClaw Workspace Skill
  6. ## Overview
  7. OpenClaw workspace files form the agent's "soul and memory" — they are injected into the system prompt on every turn (or on relevant turns), giving the agent its identity, behavioral rules, environmental knowledge, and long-term memory. Managing these files well is critical: bloat wastes tokens, redundancy creates confusion, and stale content leads to bad decisions.
  8. **Token budget:** 20,000 chars per file, ~150,000 chars total across all bootstrap files.
  9. ## File Inventory
  10. | File | Purpose | Loaded When | Sub-agents? |
  11. |------|---------|-------------|-------------|
  12. | `AGENTS.md` | Boot sequence, checklists, behavioral rules | Every turn (all agents) | Yes |
  13. | `SOUL.md` | Persona, tone, values, continuity philosophy | Every turn (all agents) | Yes |
  14. | `TOOLS.md` | Env-specific notes (SSH, TTS, cameras, devices) | On-demand reference (part of bootstrap set) | Yes |
  15. | `USER.md` | Human profile, preferences, relationship context | Every turn (all agents) | Yes |
  16. | `IDENTITY.md` | Name, emoji, avatar, self-description | Every turn | Yes |
  17. | `HEARTBEAT.md` | Periodic check tasks and health routines | Every heartbeat turn | Depends |
  18. | `BOOT.md` | Startup actions (requires `hooks.internal.enabled`) | On gateway startup | No |
  19. | `BOOTSTRAP.md` | First-time onboarding script — delete after use | New workspaces only | No |
  20. | `MEMORY.md` | Long-term curated facts and iron-law rules | Main sessions only | No |
  21. | `memory/YYYY-MM-DD.md` | Daily session logs | Loaded per AGENTS.md boot sequence | No |
  22. | `checklists/*.md` | Step-by-step ops guides | Referenced in AGENTS.md, loaded on demand | No |
  23. **Security rule:** MEMORY.md must NEVER be loaded in group chats or sub-agent sessions — it contains private context that should not leak.
  24. For full details on each file's design, anti-patterns, and section structure, see [references/workspace-files.md](references/workspace-files.md).
  25. ## Workspace Paths
  26. | Path | Purpose |
  27. |------|---------|
  28. | `~/.openclaw/workspace/` | Default workspace for main agent |
  29. | `~/.openclaw/workspace-<profile>/` | Per-profile workspace (multiple agents) |
  30. | `~/.openclaw/workspace/vendor/OpenClaw-Memory/` | Vendor-managed base files (synced from upstream) |
  31. | `~/.openclaw/workspace/checklists/` | Checklist files referenced from AGENTS.md |
  32. | `~/.openclaw/workspace/memory/` | Daily session logs |
  33. | `~/.openclaw/workspace/docs/` | On-demand documentation (NOT auto-loaded) |
  34. Config key: `agents.defaults.workspace` or per-agent `agents.list[].workspace`.
  35. ## Workflow: Audit Existing Workspace
  36. Use when workspace files may be bloated, stale, or redundant.
  37. 1. **Read all active files** — AGENTS.md, SOUL.md, TOOLS.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md
  38. 2. **Check character counts:**
  39. ```bash
  40. wc -c ~/.openclaw/workspace/AGENTS.md
  41. wc -c ~/.openclaw/workspace/SOUL.md
  42. wc -c ~/.openclaw/workspace/TOOLS.md
  43. wc -c ~/.openclaw/workspace/USER.md
  44. wc -c ~/.openclaw/workspace/IDENTITY.md
  45. wc -c ~/.openclaw/workspace/MEMORY.md
  46. # Or all at once:
  47. wc -c ~/.openclaw/workspace/*.md
  48. ```
  49. 3. **Flag files over 10,000 chars** — prime candidates for trimming or offloading to `docs/`
  50. 4. **Check for redundancy** — same fact in SOUL.md and AGENTS.md? Same tool note in TOOLS.md and MEMORY.md?
  51. 5. **Check for staleness** — outdated SSH hosts, old tool names, deprecated rules, historical context that's no longer needed
  52. 6. **Check MEMORY.md discipline** — should contain curated facts, lessons learned, decisions, and critical rules — not raw session summaries or task-specific notes
  53. 7. **Propose targeted edits** — trim, move to docs/, or restructure
  54. See [references/optimization-guide.md](references/optimization-guide.md) for specific optimization strategies.
  55. ## Workflow: Set Up New Workspace
  56. Use when creating a workspace for a new agent from scratch.
  57. **File creation order** (matters for boot sequence to work):
  58. 1. `SOUL.md` — persona and values first; everything else follows from identity
  59. 2. `AGENTS.md` — boot sequence, safety rules, checklist table
  60. 3. `IDENTITY.md` — name, emoji, avatar
  61. 4. `USER.md` — human profile and preferences (main agent only)
  62. 5. `TOOLS.md` — environment-specific notes (add as you discover env details)
  63. 6. `MEMORY.md` — start minimal; only truly universal iron laws
  64. 7. `HEARTBEAT.md` — periodic health checks (optional, add when needed)
  65. 8. `BOOT.md` — startup hooks (optional, only if `hooks.internal.enabled = true`)
  66. 9. `BOOTSTRAP.md` — first-run onboarding (optional; delete after first successful startup)
  67. **Minimal viable workspace:** AGENTS.md + SOUL.md + TOOLS.md. Everything else is optional.
  68. **BOOTSTRAP.md note:** If creating a BOOTSTRAP.md, include a self-deletion instruction at the end:
  69. ```
  70. ## Final Step
  71. Delete this file: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`
  72. ```
  73. ## Workflow: Memory Distillation
  74. Use periodically (weekly or monthly) to keep MEMORY.md lean.
  75. 1. **Read all recent daily logs:** `memory/YYYY-MM-DD.md` files from the past period
  76. 2. **Identify candidates for promotion to MEMORY.md:**
  77. - Rules violated more than once (recurring mistakes)
  78. - Hard-won discoveries that aren't in skills docs
  79. - Env-specific facts that should always be in context (not left to memory_search recall)
  80. 3. **Check what's already in MEMORY.md** — avoid duplicates
  81. 4. **Draft additions** — use iron-law format: concise, action-oriented, unambiguous
  82. 5. **Archive old daily logs** — move files older than 30 days to `memory/archive/` or delete
  83. 6. **Check MEMORY.md total size** — keep under 10,000 chars; if larger, review for rules that are now stable enough to move to a skill's SKILL.md instead
  84. **Do NOT put in MEMORY.md:**
  85. - Long narratives or session summaries
  86. - Things already covered in skill docs
  87. - Anything specific to a single past task
  88. - Episodic or task-specific memories (store those via memory_search/SQLite instead)
  89. ## Workflow: Add or Update a Checklist
  90. Use when adding a new high-risk operation type or updating an existing checklist.
  91. 1. **Create or edit** `checklists/<operation-name>.md`
  92. 2. **Structure:**
  93. ```markdown
  94. # Checklist: <Operation Name>
  95. ## Pre-flight
  96. - [ ] Step 1
  97. - [ ] Step 2
  98. ## Execution
  99. - [ ] Step 3
  100. ## Verification
  101. - [ ] Confirm outcome
  102. - [ ] Log result in memory
  103. ```
  104. 3. **Register in AGENTS.md** — add a row to the checklists table:
  105. ```markdown
  106. | <Operation description> | `checklists/<filename>.md` |
  107. ```
  108. 4. **Keep checklists short** — if a checklist exceeds ~50 lines, it's probably trying to be documentation; move narrative content to `docs/` and keep only the actionable steps
  109. ## Workflow: Update TOOLS.md
  110. Use when adding a new tool, device, or environment capability.
  111. **TOOLS.md = environment-specific cheat sheet.** It should contain:
  112. - SSH hosts and common commands for this specific machine
  113. - TTS provider, voice IDs, and any quirks
  114. - Camera IDs or device names for this setup
  115. - Node device IDs or names
  116. - Any local aliases or shortcuts that aren't obvious
  117. **Do NOT put in TOOLS.md:**
  118. - General skill documentation (use skill SKILL.md files)
  119. - Things that are the same across all environments
  120. - Installation instructions (use docs/)
  121. **Format conventions:**
  122. ```markdown
  123. # TOOLS.md - Local Notes
  124. ## SSH
  125. - Main server: `ssh user@hostname`
  126. ## TTS
  127. - Provider: Edge
  128. - Voice: zh-CN-XiaoxiaoNeural
  129. ## Cameras
  130. - Living room: node-id `abc123`, device `camera-0`
  131. ```
  132. ## Common Issues
  133. ### File exceeds token limit
  134. **Symptom:** File is over 20,000 chars; OpenClaw may truncate it.
  135. **Fix:** Audit for content that belongs in `docs/` (loaded on demand) instead of the bootstrap file. Move detailed references, historical context, and long examples out. Keep only what needs to be on every turn.
  136. ### MEMORY.md leaking to groups
  137. **Symptom:** Agent shares private context in group chats or Discord.
  138. **Fix:** Ensure MEMORY.md boot step in AGENTS.md is gated: "Main session only: Read MEMORY.md". Verify the agent's boot sequence explicitly checks session type before loading.
  139. ### Boot sequence not loading files
  140. **Symptom:** Agent doesn't know about content in SOUL.md, USER.md, or MEMORY.md at session start.
  141. **Fix:** Check that AGENTS.md boot sequence explicitly names each file to read. The agent won't auto-load files — it follows the boot sequence instructions in AGENTS.md. Verify `hooks.internal.enabled = true` in config if using BOOT.md.
  142. ### MEMORY.md growing too large
  143. **Symptom:** File approaches or exceeds 10,000 chars; reading it on every turn wastes significant context.
  144. **Fix:** Run memory distillation workflow. Move stable rules that have been incident-free for months into relevant skill SKILL.md files. Delete rules that are no longer relevant.
  145. ### Workspace changes not taking effect
  146. **Symptom:** Agent still uses old content after editing a workspace file.
  147. **Fix:** Workspace files are read at session start per the boot sequence. Restart the gateway or start a new session for changes to take effect.
  148. ## Reference Files
  149. | Reference | Coverage |
  150. |-----------|---------|
  151. | [workspace-files.md](references/workspace-files.md) | Deep-dive on each file: purpose, design principles, anti-patterns, section structure |
  152. | [optimization-guide.md](references/optimization-guide.md) | Token efficiency strategies, audit commands, distillation process |
README.md · README · 203 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # [🚀观看我的哔哩哔哩视频](https://space.bilibili.com/3493277319825652)
  2. # openclaw-workspace
  3. A [Claude Code](https://claude.ai/claude-code) skill for maintaining and optimizing [OpenClaw](https://openclaw.ai) workspace files — the markdown files that form an AI agent's soul, memory, and operating procedures.
  4. [中文文档 →](README_CN.md)
  5. ---
  6. ## What is this?
  7. OpenClaw is a self-hosted, multi-channel AI agent gateway (WhatsApp, Telegram, Discord, Slack, and more). Every OpenClaw agent has a **workspace** — a directory of markdown files that are injected into the system prompt on each turn, giving the agent its identity, behavioral rules, environmental knowledge, and long-term memory.
  8. These workspace files are powerful but require careful management:
  9. - **Too much content** wastes tokens on every single turn
  10. - **Redundancy** between files creates confusion and contradictions
  11. - **Stale content** (old SSH hosts, deprecated rules, finished tasks) silently degrades agent quality
  12. - **Missing security gates** can leak private memory into group chats
  13. This skill gives Claude Code the knowledge to audit, optimize, and build OpenClaw workspace files correctly.
  14. ---
  15. ## Workspace Files Overview
  16. | File | Purpose | Loaded When | Visible to Sub-agents? |
  17. |------|---------|-------------|----------------------|
  18. | `AGENTS.md` | Boot sequence, checklists, behavioral rules | Every turn (all agents) | Yes |
  19. | `SOUL.md` | Persona, tone, values, continuity philosophy | Every turn (all agents) | Yes |
  20. | `TOOLS.md` | Env-specific notes (SSH, TTS, cameras, devices) | Every turn (main + sub-agents) | Yes |
  21. | `USER.md` | Human profile, preferences, relationship context | Every turn (main sessions only) | No |
  22. | `IDENTITY.md` | Name, emoji, avatar, self-description | Every turn | Yes |
  23. | `HEARTBEAT.md` | Periodic check tasks and health routines | Every heartbeat turn | Depends |
  24. | `BOOT.md` | Startup actions (`hooks.internal.enabled` required) | On gateway startup | No |
  25. | `BOOTSTRAP.md` | First-time onboarding script — delete after use | New workspaces only | No |
  26. | `MEMORY.md` | Long-term curated facts and iron-law rules | Main sessions only | **Never** |
  27. | `memory/YYYY-MM-DD.md` | Daily session logs | Per AGENTS.md boot sequence | No |
  28. | `checklists/*.md` | Step-by-step ops guides | On demand (referenced from AGENTS.md) | No |
  29. ### Token Budget
  30. | Constraint | Limit |
  31. |-----------|-------|
  32. | Per file hard cap | 20,000 chars (truncated if exceeded) |
  33. | Total across all bootstrap files | ~150,000 chars |
  34. | Recommended target per file | 10,000–15,000 chars |
  35. ### Security Rule
  36. > **`MEMORY.md` must NEVER be loaded in group chats or sub-agent sessions.** It contains private user context that must not leak. The boot sequence in `AGENTS.md` must gate its loading explicitly: `"Main session only: Read MEMORY.md"`.
  37. ---
  38. ## Workspace Directory Structure
  39. ```
  40. ~/.openclaw/workspace/
  41. ├── AGENTS.md # Operating manual — boot sequence, rules, checklists table
  42. ├── SOUL.md # Persona, tone, values
  43. ├── TOOLS.md # Env-specific: SSH hosts, TTS voices, camera IDs
  44. ├── USER.md # Human profile (main sessions only)
  45. ├── IDENTITY.md # Name, emoji, avatar
  46. ├── HEARTBEAT.md # Periodic task instructions
  47. ├── BOOT.md # Startup hook actions
  48. ├── BOOTSTRAP.md # First-run onboarding (delete after use)
  49. ├── MEMORY.md # Iron-law rules (main sessions only)
  50. ├── memory/
  51. │ ├── 2026-03-10.md # Daily session logs
  52. │ └── archive/ # Old logs (> 30 days)
  53. ├── checklists/
  54. │ ├── deploy-agent.md
  55. │ ├── gateway-restart.md
  56. │ └── config-patch.md
  57. └── docs/ # On-demand docs (NOT auto-loaded every turn)
  58. ├── agent-rules-detail.md
  59. └── ssh-reference.md
  60. ```
  61. ---
  62. ## What This Skill Does
  63. When invoked, this skill guides Claude Code through five main workflows:
  64. ### 1. Audit Existing Workspace
  65. Reads all workspace files, checks character counts, identifies bloat, spots redundancy between files, finds stale content, and proposes targeted edits.
  66. ```bash
  67. # Quick size audit
  68. wc -c ~/.openclaw/workspace/*.md
  69. ```
  70. Files over 10,000 chars are prime candidates for trimming or moving content to `docs/` (loaded on demand).
  71. ### 2. Set Up a New Workspace from Scratch
  72. Creates workspace files in the correct order (SOUL → AGENTS → IDENTITY → USER → TOOLS → MEMORY → optional files). Ensures the boot sequence, security gates, and checklist table are all properly wired up.
  73. **Minimal viable workspace:** `AGENTS.md` + `SOUL.md` + `TOOLS.md`. Everything else is optional.
  74. ### 3. Memory Distillation
  75. Processes `memory/YYYY-MM-DD.md` daily logs into `MEMORY.md`. Promotes recurring mistakes and hard-won rules to iron-law format, archives old logs, and checks for rules that have matured enough to move to a skill's `SKILL.md` instead.
  76. ### 4. Add or Update Checklists
  77. Creates `checklists/<operation>.md` files for high-risk operations (deploys, config changes, gateway restarts) and registers them in the `AGENTS.md` checklists routing table.
  78. ### 5. Update TOOLS.md
  79. Adds new environment-specific entries (SSH hosts, TTS voices, camera/device IDs) and cleans out stale entries.
  80. ---
  81. ## How to Install
  82. This is a [Claude Code skill](https://docs.openclaw.ai/skills). Place it in your skills directory:
  83. ```bash
  84. # Clone into your Claude Code skills directory
  85. git clone https://github.com/win4r/openclaw-workspace ~/.claude/skills/openclaw-workspace
  86. ```
  87. Claude Code will automatically detect and register the skill. It will appear in the skill list as:
  88. > **openclaw-workspace** — Use when maintaining or optimizing OpenClaw workspace files...
  89. ### Manual Installation
  90. Copy the skill directory anywhere Claude Code looks for skills:
  91. - `~/.claude/skills/openclaw-workspace/` (recommended)
  92. - Per-project: `.claude/skills/openclaw-workspace/`
  93. ---
  94. ## How to Use
  95. Once installed, Claude Code will automatically invoke this skill when you:
  96. - "Review my AGENTS.md for token efficiency"
  97. - "Help me set up a new OpenClaw workspace"
  98. - "Distill my memory logs into MEMORY.md"
  99. - "Add a checklist for gateway restarts"
  100. - "Audit my workspace files for redundancy"
  101. - "My MEMORY.md is getting too large, help me clean it up"
  102. You can also explicitly ask: *"Use the openclaw-workspace skill to..."*
  103. ---
  104. ## Common Issues
  105. ### File exceeds token limit (> 20,000 chars)
  106. Move content to `docs/` (loaded on demand, not every turn). Keep only what needs to be in context on every single turn.
  107. ### MEMORY.md leaking to group chats
  108. Add explicit gating in AGENTS.md boot sequence: `"2. Main session only: Read MEMORY.md"`. Without this gate, the agent may load it in any context.
  109. ### Boot sequence not loading files
  110. The agent follows AGENTS.md boot sequence instructions — it won't auto-discover files. Make sure each file is explicitly named in the boot sequence.
  111. ### Workspace changes not taking effect
  112. Workspace files are read at session start. Start a new session or restart the gateway for changes to apply.
  113. ### MEMORY.md growing unbounded
  114. Run memory distillation monthly. Promote mature rules to skill `SKILL.md` files (more appropriate home for stable, tool-specific rules). Delete rules about completed tasks.
  115. ---
  116. ## File Reference
  117. | File | Description |
  118. |------|-------------|
  119. | [`SKILL.md`](SKILL.md) | Main skill — all workflows, common issues, workspace paths |
  120. | [`references/workspace-files.md`](references/workspace-files.md) | Deep-dive on every workspace file: purpose, design principles, anti-patterns, section structure |
  121. | [`references/optimization-guide.md`](references/optimization-guide.md) | Token efficiency strategies, audit commands, memory distillation process, redundancy audit table |
  122. ---
  123. ## Related
  124. - [OpenClaw](https://openclaw.ai) — the gateway this skill supports
  125. - [openclaw skill](https://github.com/win4r/openclaw) — gateway operations, channel setup, multi-agent routing (separate skill)
  126. ---
  127. ## License
  128. MIT
  129. ## Buy Me a Coffee
  130. [!["Buy Me A Coffee"](https://storage.ko-fi.com/cdn/kofi2.png?v=3)](https://ko-fi.com/aila)
  131. ## My WeChat Group and My WeChat QR Code
  132. <img src="https://github.com/win4r/AISuperDomain/assets/42172631/d6dcfd1a-60fa-4b6f-9d5e-1482150a7d95" width="186" height="300">
  133. <img src="https://github.com/win4r/AISuperDomain/assets/42172631/7568cf78-c8ba-4182-aa96-d524d903f2bc" width="214.8" height="291">
  134. <img src="https://github.com/win4r/AISuperDomain/assets/42172631/fefe535c-8153-4046-bfb4-e65eacbf7a33" width="207" height="281">

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.