Trim an OpenClaw workspace prompt

OpenClaw assembles its system prompt fresh for every agent turn. Alongside the fixed sections it manages (Tooling, Safety, Skills, Workspace, …), it injects the workspace's own Markdown files in full, every turn: AGENTS.md, SOUL.md, IDENTITY.md, USER.md, BOOTSTRAP.md (new workspaces only, self-deletes after first run), and MEMORY.md when present. That injected block is the one part of the per-turn cost the workspace owner controls — and the usual "landslide of noise per turn" complaint is it growing unchecked. OpenClaw caps it at 20,000 chars per file and 60,000 total and truncates past that with a terse notice, which is a worse outcome than trimming on purpose: you don't choose what gets cut.

This skill is the remedy, the OpenClaw sibling of /clawness:claude-md. It is opt-in work: you invoking it is the consent, because a good trim is destructive and takes a while.

Say this before starting. This reorganises files the user may care about a great deal (SOUL.md is the agent's personality), and it takes most of a session. Tell them: nothing is deleted until its replacement is verified, and they can stop after any single file. Then get an explicit go-ahead.

Filenames and limits below are from OpenClaw's public docs, not a live install. Before you measure, confirm the workspace path and the file set actually present — see the same caution in openclaw/README.md ("Assumptions to verify"). The default workspace is ~/.openclaw/workspace/; the user may point elsewhere.

First: is this the right tool?

This skill earns its place only when Clawness is running under OpenClaw (the openclaw/ TypeScript adapter shelling out to the Python hooks), because the whole point is to move bulk out of always-injected files and into Clawness's ranked retrieval, which the adapter provides via the before_prompt_build hook. Without that adapter installed there is nowhere cheaper for the content to go, and you should stop and say so — trimming a workspace file with no ranked destination just loses information.

Check first: is the openclaw/ adapter installed and are .clawness/rules/ and .clawness/memory.md reachable in this workspace? If not, say what's missing and stop.

What actually reduces per-turn cost

Only these move the number. Get this right or the exercise is theatre:

Two OpenClaw-specific traps:

• OpenClaw's own MEMORY.md is injected whole, like the others. Do not "save cost" by shovelling material from SOUL.md into MEMORY.md — same per-turn tax, just relabelled. Durable conventions belong in .clawness/rules/ (ranked); one-line traps in .clawness/memory.md (ranked). Only genuinely-every-turn curated memory stays in OpenClaw's MEMORY.md.
• AGENTS.md is the file sub-agents inherit, alone. Every char there is paid by the main loop and every sub-agent spawn. It is the highest-leverage file to shrink and the one where "keep it operational, move the rest" matters most.

OpenClaw's own guidance echoes this: keep SOUL.md under ~500 words and AGENTS.md under ~300; adherence improves as they shrink, not worse.

Steps

1. Measure

Read each present workspace file (AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md; ignore BOOTSTRAP.md — it self-deletes). Report:

• per-file characters and a rough token estimate (chars ÷ 4; call it rough, it is), plus the total and how it sits against the 20k/file and 60k/total caps
• a per-section breakdown by top-level heading within each file, largest first

The breakdown is the point. "Your workspace is 8k tokens" invites a shrug; "your AGENTS.md Tooling section is 2.1k tokens re-describing tools OpenClaw already lists in its Tooling section, and every sub-agent pays for it too" does not.

If you can, measure the real assembled cost, not just the files. OpenClaw exposes the fully assembled prompt (all fixed sections + injected files) through the llm_input and before_agent_run hooks. A tiny observation-only plugin logging the assembled length once gives the true per-turn number, of which the workspace files are only a part. Offer this; mark it as docs-derived and unverified against a live host until you've run it.

2. Classify every section

Go heading by heading, per file, and assign one verdict. Default to STAY. The burden of proof is on moving something.

• STAY — persona, identity, values, behavioural guardrails, user profile, and core operating instructions. This is load-bearing every turn regardless of the prompt, which is exactly what retrieval cannot be trusted to surface on demand. SOUL.md's personality and USER.md's "call me X" must be present whether or not the prompt hints at them. Keep them — just tighten wording (see Don'ts: tighten is not reword-the-meaning).
• CUT — anything the tools, workspace, or codebase already answer: tool inventories (OpenClaw's Tooling section already lists them), restated OpenClaw docs, directory layouts, dependency lists, and history that reads as a changelog.
• → .clawness/rules/<domain>/<ID>.yml — a durable convention tied to a topic rather than the agent's identity (coding standards, a library's house style, error-handling rules). Full rule format: id, domain, severity, tags, triggers, when, rule, violation, correct. tags/triggers drive retrieval — put the words someone would actually type.
• → .clawness/memory.md — one-line traps only, under ## Lessons, ≤120 chars, naming the file or flag so it retrieves. If the rationale is the payload, it is not a memory entry; use .clawness/rules/ instead.

Present the whole classification as a table and get approval before moving anything. Include the projected per-turn token saving (and, if AGENTS.md shrinks, note the extra sub-agent saving separately).

3. Move one section at a time, verify, then delete

Never delete from a workspace file until its replacement is proven to surface. For each approved section, smallest first:

1. Write the new file (or add the rule / memory line).
2. Verify it:
   • .clawness/rules/ → confirm the new ID retrieves. The clawness CLI ships with the plugin but isn't on PATH; run it via the bundled launcher (or the bootstrap's wrapper on older Claude Code): CLAW="${CLAUDE_PLUGIN_ROOT}/scripts/clawness-cli.sh"; [ -f "$CLAW" ] || CLAW="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/clawness/clawness-cli.sh", then bash "$CLAW" query "<a prompt this should match>" and check the ID appears. (Editable/manual installs may use python -m clawness.cli query ....)
   • .clawness/memory.md → the entry is one line under ## Lessons.
3. Only then remove the section from the workspace file.
4. Say what moved and what the file is down to.

If verification fails, put the section back and mark it STAY. A rule that doesn't retrieve is strictly worse than a paragraph in SOUL.md.

4. Finish

• Re-measure and report the before/after per file and in total (and against the caps).
• If anything moved to .clawness/rules/, run bash "$CLAW" lint — it rejects missing fields and vague phrasing, and a rule that fails lint won't survive CI in projects that gate on it.
• Lock in the trade with an eval set. Moving content from an always-injected file into ranked retrieval swaps a guarantee for a probability. Run /clawness:eval-set to write a case for each thing the trimmed content used to guarantee and confirm hit-rate is 1.0 — that is the proof the move was safe, and it catches a later rule edit that stops surfacing.
• Remind the user that OpenClaw re-reads workspace files each session, so the smaller prompt takes effect on the next agent run.
• Suggest committing the workspace files as one reviewable change (the moves can then be read and reverted as a unit). Note that SOUL.md/AGENTS.md/MEMORY.md are usually committed, while USER.md is often personal — respect the project's existing gitignore.

Don't

• Don't run this without the OpenClaw adapter and .clawness/ retrieval in place — there is no cheap destination otherwise.
• Don't start from a passing mention or your own initiative. It is opt-in work.
• Don't move something because it is long. Move it because it is not identity — persona and user profile STAY however long, conventions and inventories move however short.
• Don't relocate bulk into OpenClaw's own MEMORY.md; that is the same per-turn cost.
• Don't rewrite a persona while relocating around it. Trim wording in a separate, visible pass if the user wants — a reorganisation that silently reworded SOUL.md is impossible to review, and SOUL.md is the one file where wording is the behaviour.
• Don't treat the docs-derived filenames, caps, or hook names as verified. Confirm the real workspace against a live OpenClaw before acting, and say which parts you couldn't check.