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.
Badge for your README
Markdown
[](/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
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.
- ---
- name: openclaw-workspace
- 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.
- ---
- # OpenClaw Workspace Skill
- ## Overview
- 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.
- **Token budget:** 20,000 chars per file, ~150,000 chars total across all bootstrap files.
- ## File Inventory
- | File | Purpose | Loaded When | Sub-agents? |
- |------|---------|-------------|-------------|
- | `AGENTS.md` | Boot sequence, checklists, behavioral rules | Every turn (all agents) | Yes |
- | `SOUL.md` | Persona, tone, values, continuity philosophy | Every turn (all agents) | Yes |
- | `TOOLS.md` | Env-specific notes (SSH, TTS, cameras, devices) | On-demand reference (part of bootstrap set) | Yes |
- | `USER.md` | Human profile, preferences, relationship context | Every turn (all agents) | Yes |
- | `IDENTITY.md` | Name, emoji, avatar, self-description | Every turn | Yes |
- | `HEARTBEAT.md` | Periodic check tasks and health routines | Every heartbeat turn | Depends |
- | `BOOT.md` | Startup actions (requires `hooks.internal.enabled`) | On gateway startup | No |
- | `BOOTSTRAP.md` | First-time onboarding script — delete after use | New workspaces only | No |
- | `MEMORY.md` | Long-term curated facts and iron-law rules | Main sessions only | No |
- | `memory/YYYY-MM-DD.md` | Daily session logs | Loaded per AGENTS.md boot sequence | No |
- | `checklists/*.md` | Step-by-step ops guides | Referenced in AGENTS.md, loaded on demand | No |
- **Security rule:** MEMORY.md must NEVER be loaded in group chats or sub-agent sessions — it contains private context that should not leak.
- For full details on each file's design, anti-patterns, and section structure, see [references/workspace-files.md](references/workspace-files.md).
- ## Workspace Paths
- | Path | Purpose |
- |------|---------|
- | `~/.openclaw/workspace/` | Default workspace for main agent |
- | `~/.openclaw/workspace-<profile>/` | Per-profile workspace (multiple agents) |
- | `~/.openclaw/workspace/vendor/OpenClaw-Memory/` | Vendor-managed base files (synced from upstream) |
- | `~/.openclaw/workspace/checklists/` | Checklist files referenced from AGENTS.md |
- | `~/.openclaw/workspace/memory/` | Daily session logs |
- | `~/.openclaw/workspace/docs/` | On-demand documentation (NOT auto-loaded) |
- Config key: `agents.defaults.workspace` or per-agent `agents.list[].workspace`.
- ## Workflow: Audit Existing Workspace
- Use when workspace files may be bloated, stale, or redundant.
- 1. **Read all active files** — AGENTS.md, SOUL.md, TOOLS.md, USER.md, IDENTITY.md, HEARTBEAT.md, BOOT.md, MEMORY.md
- 2. **Check character counts:**
- ```bash
- wc -c ~/.openclaw/workspace/AGENTS.md
- wc -c ~/.openclaw/workspace/SOUL.md
- wc -c ~/.openclaw/workspace/TOOLS.md
- wc -c ~/.openclaw/workspace/USER.md
- wc -c ~/.openclaw/workspace/IDENTITY.md
- wc -c ~/.openclaw/workspace/MEMORY.md
- # Or all at once:
- wc -c ~/.openclaw/workspace/*.md
- ```
- 3. **Flag files over 10,000 chars** — prime candidates for trimming or offloading to `docs/`
- 4. **Check for redundancy** — same fact in SOUL.md and AGENTS.md? Same tool note in TOOLS.md and MEMORY.md?
- 5. **Check for staleness** — outdated SSH hosts, old tool names, deprecated rules, historical context that's no longer needed
- 6. **Check MEMORY.md discipline** — should contain curated facts, lessons learned, decisions, and critical rules — not raw session summaries or task-specific notes
- 7. **Propose targeted edits** — trim, move to docs/, or restructure
- See [references/optimization-guide.md](references/optimization-guide.md) for specific optimization strategies.
- ## Workflow: Set Up New Workspace
- Use when creating a workspace for a new agent from scratch.
- **File creation order** (matters for boot sequence to work):
- 1. `SOUL.md` — persona and values first; everything else follows from identity
- 2. `AGENTS.md` — boot sequence, safety rules, checklist table
- 3. `IDENTITY.md` — name, emoji, avatar
- 4. `USER.md` — human profile and preferences (main agent only)
- 5. `TOOLS.md` — environment-specific notes (add as you discover env details)
- 6. `MEMORY.md` — start minimal; only truly universal iron laws
- 7. `HEARTBEAT.md` — periodic health checks (optional, add when needed)
- 8. `BOOT.md` — startup hooks (optional, only if `hooks.internal.enabled = true`)
- 9. `BOOTSTRAP.md` — first-run onboarding (optional; delete after first successful startup)
- **Minimal viable workspace:** AGENTS.md + SOUL.md + TOOLS.md. Everything else is optional.
- **BOOTSTRAP.md note:** If creating a BOOTSTRAP.md, include a self-deletion instruction at the end:
- ```
- ## Final Step
- Delete this file: exec `rm ~/.openclaw/workspace/BOOTSTRAP.md`
- ```
- ## Workflow: Memory Distillation
- Use periodically (weekly or monthly) to keep MEMORY.md lean.
- 1. **Read all recent daily logs:** `memory/YYYY-MM-DD.md` files from the past period
- 2. **Identify candidates for promotion to MEMORY.md:**
- - Rules violated more than once (recurring mistakes)
- - Hard-won discoveries that aren't in skills docs
- - Env-specific facts that should always be in context (not left to memory_search recall)
- 3. **Check what's already in MEMORY.md** — avoid duplicates
- 4. **Draft additions** — use iron-law format: concise, action-oriented, unambiguous
- 5. **Archive old daily logs** — move files older than 30 days to `memory/archive/` or delete
- 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
- **Do NOT put in MEMORY.md:**
- - Long narratives or session summaries
- - Things already covered in skill docs
- - Anything specific to a single past task
- - Episodic or task-specific memories (store those via memory_search/SQLite instead)
- ## Workflow: Add or Update a Checklist
- Use when adding a new high-risk operation type or updating an existing checklist.
- 1. **Create or edit** `checklists/<operation-name>.md`
- 2. **Structure:**
- ```markdown
- # Checklist: <Operation Name>
- ## Pre-flight
- - [ ] Step 1
- - [ ] Step 2
- ## Execution
- - [ ] Step 3
- ## Verification
- - [ ] Confirm outcome
- - [ ] Log result in memory
- ```
- 3. **Register in AGENTS.md** — add a row to the checklists table:
- ```markdown
- | <Operation description> | `checklists/<filename>.md` |
- ```
- 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
- ## Workflow: Update TOOLS.md
- Use when adding a new tool, device, or environment capability.
- **TOOLS.md = environment-specific cheat sheet.** It should contain:
- - SSH hosts and common commands for this specific machine
- - TTS provider, voice IDs, and any quirks
- - Camera IDs or device names for this setup
- - Node device IDs or names
- - Any local aliases or shortcuts that aren't obvious
- **Do NOT put in TOOLS.md:**
- - General skill documentation (use skill SKILL.md files)
- - Things that are the same across all environments
- - Installation instructions (use docs/)
- **Format conventions:**
- ```markdown
- # TOOLS.md - Local Notes
- ## SSH
- - Main server: `ssh user@hostname`
- ## TTS
- - Provider: Edge
- - Voice: zh-CN-XiaoxiaoNeural
- ## Cameras
- - Living room: node-id `abc123`, device `camera-0`
- ```
- ## Common Issues
- ### File exceeds token limit
- **Symptom:** File is over 20,000 chars; OpenClaw may truncate it.
- **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.
- ### MEMORY.md leaking to groups
- **Symptom:** Agent shares private context in group chats or Discord.
- **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.
- ### Boot sequence not loading files
- **Symptom:** Agent doesn't know about content in SOUL.md, USER.md, or MEMORY.md at session start.
- **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.
- ### MEMORY.md growing too large
- **Symptom:** File approaches or exceeds 10,000 chars; reading it on every turn wastes significant context.
- **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.
- ### Workspace changes not taking effect
- **Symptom:** Agent still uses old content after editing a workspace file.
- **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.
- ## Reference Files
- | Reference | Coverage |
- |-----------|---------|
- | [workspace-files.md](references/workspace-files.md) | Deep-dive on each file: purpose, design principles, anti-patterns, section structure |
- | [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.
- # [🚀观看我的哔哩哔哩视频](https://space.bilibili.com/3493277319825652)
- # openclaw-workspace
- 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.
- [中文文档 →](README_CN.md)
- ---
- ## What is this?
- 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.
- These workspace files are powerful but require careful management:
- - **Too much content** wastes tokens on every single turn
- - **Redundancy** between files creates confusion and contradictions
- - **Stale content** (old SSH hosts, deprecated rules, finished tasks) silently degrades agent quality
- - **Missing security gates** can leak private memory into group chats
- This skill gives Claude Code the knowledge to audit, optimize, and build OpenClaw workspace files correctly.
- ---
- ## Workspace Files Overview
- | File | Purpose | Loaded When | Visible to Sub-agents? |
- |------|---------|-------------|----------------------|
- | `AGENTS.md` | Boot sequence, checklists, behavioral rules | Every turn (all agents) | Yes |
- | `SOUL.md` | Persona, tone, values, continuity philosophy | Every turn (all agents) | Yes |
- | `TOOLS.md` | Env-specific notes (SSH, TTS, cameras, devices) | Every turn (main + sub-agents) | Yes |
- | `USER.md` | Human profile, preferences, relationship context | Every turn (main sessions only) | No |
- | `IDENTITY.md` | Name, emoji, avatar, self-description | Every turn | Yes |
- | `HEARTBEAT.md` | Periodic check tasks and health routines | Every heartbeat turn | Depends |
- | `BOOT.md` | Startup actions (`hooks.internal.enabled` required) | On gateway startup | No |
- | `BOOTSTRAP.md` | First-time onboarding script — delete after use | New workspaces only | No |
- | `MEMORY.md` | Long-term curated facts and iron-law rules | Main sessions only | **Never** |
- | `memory/YYYY-MM-DD.md` | Daily session logs | Per AGENTS.md boot sequence | No |
- | `checklists/*.md` | Step-by-step ops guides | On demand (referenced from AGENTS.md) | No |
- ### Token Budget
- | Constraint | Limit |
- |-----------|-------|
- | Per file hard cap | 20,000 chars (truncated if exceeded) |
- | Total across all bootstrap files | ~150,000 chars |
- | Recommended target per file | 10,000–15,000 chars |
- ### Security Rule
- > **`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"`.
- ---
- ## Workspace Directory Structure
- ```
- ~/.openclaw/workspace/
- ├── AGENTS.md # Operating manual — boot sequence, rules, checklists table
- ├── SOUL.md # Persona, tone, values
- ├── TOOLS.md # Env-specific: SSH hosts, TTS voices, camera IDs
- ├── USER.md # Human profile (main sessions only)
- ├── IDENTITY.md # Name, emoji, avatar
- ├── HEARTBEAT.md # Periodic task instructions
- ├── BOOT.md # Startup hook actions
- ├── BOOTSTRAP.md # First-run onboarding (delete after use)
- ├── MEMORY.md # Iron-law rules (main sessions only)
- ├── memory/
- │ ├── 2026-03-10.md # Daily session logs
- │ └── archive/ # Old logs (> 30 days)
- ├── checklists/
- │ ├── deploy-agent.md
- │ ├── gateway-restart.md
- │ └── config-patch.md
- └── docs/ # On-demand docs (NOT auto-loaded every turn)
- ├── agent-rules-detail.md
- └── ssh-reference.md
- ```
- ---
- ## What This Skill Does
- When invoked, this skill guides Claude Code through five main workflows:
- ### 1. Audit Existing Workspace
- Reads all workspace files, checks character counts, identifies bloat, spots redundancy between files, finds stale content, and proposes targeted edits.
- ```bash
- # Quick size audit
- wc -c ~/.openclaw/workspace/*.md
- ```
- Files over 10,000 chars are prime candidates for trimming or moving content to `docs/` (loaded on demand).
- ### 2. Set Up a New Workspace from Scratch
- 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.
- ### 3. Memory Distillation
- 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.
- ### 4. Add or Update Checklists
- Creates `checklists/<operation>.md` files for high-risk operations (deploys, config changes, gateway restarts) and registers them in the `AGENTS.md` checklists routing table.
- ### 5. Update TOOLS.md
- Adds new environment-specific entries (SSH hosts, TTS voices, camera/device IDs) and cleans out stale entries.
- ---
- ## How to Install
- This is a [Claude Code skill](https://docs.openclaw.ai/skills). Place it in your skills directory:
- ```bash
- # Clone into your Claude Code skills directory
- git clone https://github.com/win4r/openclaw-workspace ~/.claude/skills/openclaw-workspace
- ```
- Claude Code will automatically detect and register the skill. It will appear in the skill list as:
- > **openclaw-workspace** — Use when maintaining or optimizing OpenClaw workspace files...
- ### Manual Installation
- Copy the skill directory anywhere Claude Code looks for skills:
- - `~/.claude/skills/openclaw-workspace/` (recommended)
- - Per-project: `.claude/skills/openclaw-workspace/`
- ---
- ## How to Use
- Once installed, Claude Code will automatically invoke this skill when you:
- - "Review my AGENTS.md for token efficiency"
- - "Help me set up a new OpenClaw workspace"
- - "Distill my memory logs into MEMORY.md"
- - "Add a checklist for gateway restarts"
- - "Audit my workspace files for redundancy"
- - "My MEMORY.md is getting too large, help me clean it up"
- You can also explicitly ask: *"Use the openclaw-workspace skill to..."*
- ---
- ## Common Issues
- ### File exceeds token limit (> 20,000 chars)
- Move content to `docs/` (loaded on demand, not every turn). Keep only what needs to be in context on every single turn.
- ### MEMORY.md leaking to group chats
- 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.
- ### Boot sequence not loading files
- 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.
- ### Workspace changes not taking effect
- Workspace files are read at session start. Start a new session or restart the gateway for changes to apply.
- ### MEMORY.md growing unbounded
- 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.
- ---
- ## File Reference
- | File | Description |
- |------|-------------|
- | [`SKILL.md`](SKILL.md) | Main skill — all workflows, common issues, workspace paths |
- | [`references/workspace-files.md`](references/workspace-files.md) | Deep-dive on every workspace file: purpose, design principles, anti-patterns, section structure |
- | [`references/optimization-guide.md`](references/optimization-guide.md) | Token efficiency strategies, audit commands, memory distillation process, redundancy audit table |
- ---
- ## Related
- - [OpenClaw](https://openclaw.ai) — the gateway this skill supports
- - [openclaw skill](https://github.com/win4r/openclaw) — gateway operations, channel setup, multi-agent routing (separate skill)
- ---
- ## License
- MIT
- ## Buy Me a Coffee
- [](https://ko-fi.com/aila)
- ## My WeChat Group and My WeChat QR Code
- <img src="https://github.com/win4r/AISuperDomain/assets/42172631/d6dcfd1a-60fa-4b6f-9d5e-1482150a7d95" width="186" height="300">
- <img src="https://github.com/win4r/AISuperDomain/assets/42172631/7568cf78-c8ba-4182-aa96-d524d903f2bc" width="214.8" height="291">
- <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 inFree to use. If it’s helped, pass it on.