# openclaw-guidelines

Adopt this skill: https://proskills.md/skills/other/hadikusumawahab-openclaw-maintenance-skill-skills-openclaw-guidelines

Page: https://proskills.md/skills/other/hadikusumawahab-openclaw-maintenance-skill-skills-openclaw-guidelines
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: skills/openclaw-guidelines/SKILL.md
size: 6396
upstream: https://github.com/hadikusumawahab/openclaw-maintenance-skill/blob/main/skills/openclaw-guidelines/SKILL.md

```text
---
name: openclaw-guidelines
description: Best practices for maintaining multiple AI agents with OpenClaw — lean workspaces, skill-first architecture, memory continuity, config/docs verification, and agent coherence. Use when configuring agents, editing workspace files, managing memory, debugging OpenClaw issues, or making changes across multiple agents.
license: MIT
---

# OpenClaw Maintenance Guidelines

Five principles for keeping your OpenClaw agents lean, consistent, and reliable over time.

**Tradeoff:** These guidelines bias toward durability and consistency over speed. For quick one-off tasks, use judgment.

## 1. Lean Workspace

**Every line in a workspace file costs tokens every turn. Earn its place.**

- Agent behavior is driven by workspace markdown files (SOUL.md, AGENTS.md, TOOLS.md), not code. When the user wants to change how an agent behaves, edit its workspace files — not a config or script.
- OpenClaw enforces hard limits: 20,000 chars per file (`bootstrapMaxChars`) and 150,000 chars total across all workspace files (`bootstrapTotalMaxChars`). Files that hit the limit are silently truncated — rules at the bottom of the file disappear without warning.
- Check workspace health: run `wc -m <file>` to see character counts. Under 50% of limit = safe. Over 75% = migrate content to skills or memory files before you lose rules to truncation.
- Touch only what you must when editing — surgical edits over full rewrites; match existing style and structure.
- When a file is getting bloated, identify what can move: tool documentation → TOOLS.md, historical decisions → memory files, repeated workflows → skills.

Ask yourself: "Would the diff be clean and reviewable?" If not, you're changing too much.

## 2. Skills Over Bloat

**Extract repeating patterns into modular skills, not instruction sprawl.**

- When you notice the same instructions duplicated across multiple agents, extract them into a shared skill instead of maintaining copies in each workspace.
- Skills use progressive disclosure: only metadata (~100 tokens) is in context; full instructions load when the agent reads the skill file — massive token savings over putting everything in workspace files.
- One canonical location for shared skills; never duplicate across agent workspaces. When updating a workflow, update the skill once — it applies everywhere.
- If a user asks to add a workflow that already exists as a skill, point them to the existing skill instead of adding instructions to AGENTS.md or TOOLS.md.
- When building new workflows, suggest creating a skill if it's likely to be reused across agents or sessions.

Ask yourself: "Is this instruction reusable across agents or sessions?" If yes, it's a skill. If no, it belongs in agent instructions.

## 3. Design for Continuity

**Agents forget everything between sessions. If it's not in a file, it didn't happen.**

When agents keep forgetting things or repeating mistakes, the problem is almost always that important context lives in chat instead of files. Here's how to diagnose and fix it:

- If an agent "forgot" something — check if it was persisted to a file. Forgotten decisions go to MEMORY.md now; repeated corrections should become permanent rules in AGENTS.md, not chat instructions that die with the session.
- Keep MEMORY.md curated: prune completed tasks, archive old decisions to topic files. Layer the `memory/` directory by durability — working memory (curated) for current state, daily logs for temporal context, topic files for persistent domain knowledge. Promote useful daily entries to permanent files, then clean up.
- Rules and learnings belong in files loaded at session start (AGENTS.md, TOOLS.md) — not in files the agent never reads back. Write self-learning triggers into AGENTS.md so the agent updates its own docs when corrected. This isn't built-in — you architect it.
- Don't rely solely on auto-compaction. Write important state to files proactively before conversations get long. Add a "search memory before acting" rule to AGENTS.md — without this, agents guess instead of checking their own notes.
- If dreaming is enabled, it handles memory consolidation automatically. Focus on what dreaming doesn't cover: promoting corrections to instruction files, cleaning up stale memory, and diagnosing continuity gaps.

## 4. Trust but Verify

**Config changes, CLI commands, and docs evolve. Trust your setup, but always verify it still works.**

- When unsure about a config field, feature, or best practice — fetch the docs first at https://docs.openclaw.ai/. OpenClaw evolves fast; don't rely on stale assumptions or LLM training data.
- Run validation and diagnostics after every config change — catch drift before it causes silent failures.
- Watch for wizard and onboard tools silently modifying config — they may reset tool access profiles or drop custom keys after OAuth refresh.
- Check the running version and match solutions to it — features and flags change between releases.
- Before recommending a feature, flag, or config field: verify it still exists in the current version.
- Diagnostic sequence when things break: check status → check gateway → check logs → run doctor/validator.

## 5. Design for Agent Coherence

**Before changing one agent, understand the whole system.**

- Never share state directories across agents — each agent needs isolated auth, sessions, and workspace to avoid collisions.
- Before modifying an agent, read its scope boundary explicitly — don't assume from the agent's name what it does or doesn't handle.
- Before adding a skill to one agent, check if an equivalent skill already exists on another agent — avoid duplicates with different names doing the same thing.
- If instructions should be identical across multiple agents, treat them as shared content — not copy-pasted sections that will inevitably diverge when edited separately.
- When editing instruction files, keep agent-specific sections clearly separated from generic/shared sections so syncing across agents doesn't accidentally overwrite unique rules.
- Before making a system-wide change, list all affected agents first. Work through them sequentially and verify consistency after finishing.
- When in doubt about agent scope or shared resources, check the workspace directory structure and any existing sync tooling before proceeding.
```

## File: README.md
upstream: https://github.com/hadikusumawahab/openclaw-maintenance-skill/blob/main/README.md

````text
# OpenClaw Maintenance Skill

Best practices in a single `CLAUDE.md` file to maintain your OpenClaw agents with ease. Works for Codex CLI and Gemini CLI too.

## The Problem

Running multiple OpenClaw agents sounds simple until workspace files bloat, memory drifts, config changes silently break things, and agents forget what they learned last week.

Proper maintenance is the difference between agents that degrade over time and agents that stay sharp.

Common issues after a few weeks of running OpenClaw:

- AGENTS.md hits the 20K character limit — rules at the bottom get silently truncated
- Multiple agents have the same instructions copy-pasted, each slightly different
- Agent makes the same mistake you corrected last Tuesday
- After OpenClaw updates, config fields may behave differently — unverified setups risk silent failures

## The Solution

Five principles that directly address these issues:

| Principle | Addresses |
|-----------|-----------|
| **Lean Workspace** | Bloated files, silent truncation, noisy context |
| **Skills Over Bloat** | Duplicated instructions across agents, workspace sprawl |
| **Design for Continuity** | Forgotten decisions, repeated mistakes, lessons that never stick |
| **Trust but Verify** | Silent config drift, stale docs, version mismatches |
| **Design for Agent Coherence** | Cross-agent inconsistencies, scope overlap, diverged shared instructions |

## The Five Principles

### 1. Lean Workspace

Every line in a workspace file costs tokens every turn. OpenClaw enforces hard limits (20K chars per file, 150K total) — files that exceed the limit are silently truncated. Keep files focused, separate agent-specific from shared sections, and prune regularly.

### 2. Skills Over Bloat

When you notice the same instructions duplicated across agents, extract them into a shared skill. Skills use progressive disclosure — only metadata in context, full instructions load on demand. One canonical location, never duplicate.

### 3. Design for Continuity

Agents forget everything between sessions. When they keep forgetting or repeating mistakes, the problem is usually that important context lives in chat instead of files. Diagnose by checking if decisions are persisted, prune bloated memory, and design self-learning triggers so corrections become permanent rules.

### 4. Trust but Verify

OpenClaw ships frequent updates — config fields get renamed, CLI flags change, features behave differently between versions. Trust your setup, but verify after every change. Fetch current docs before assuming. Run diagnostics after config edits.

### 5. Design for Agent Coherence

Before changing one agent, understand the whole system. When maintaining multiple agents, changes to one can create inconsistencies across others. Read scope boundaries, check for duplicate skills, and treat shared instructions as shared content — not copy-pasted sections that diverge over time.

## Install

### Claude Code (Plugin)

From within Claude Code, add the marketplace and install:

```
/plugin marketplace add hadikusumawahab/openclaw-maintenance-skill
/plugin install openclaw-maintenance-skill@openclaw-maintenance-skill
```

### Claude Code (Per-Project)

New project:

```bash
curl -o CLAUDE.md https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/CLAUDE.md
```

Existing project (append):

```bash
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/CLAUDE.md >> CLAUDE.md
```

### Codex CLI

```bash
curl -o AGENTS.md https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/AGENTS.md
```

### Gemini CLI

```bash
curl -o GEMINI.md https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/GEMINI.md
```

## How to Know It's Working

- Workspace files stay lean across months, not growing unbounded
- Agent corrections get promoted to permanent rules, not repeated weekly
- Config changes don't cause mystery failures
- New sessions pick up where the last one left off
- You check docs before assuming, not after breaking

## Customization

These guidelines are designed to merge with project-specific instructions. Add them to your existing `CLAUDE.md` / `AGENTS.md` / `GEMINI.md` or use them standalone.

For project-specific rules, add sections like:

```markdown
## Project-Specific

- All agents use Indonesian by default
- Finance agent handles budgeting only — no cross-domain tasks
- Cron jobs route through the orchestrator for cross-channel delivery
```

## Tradeoff Note

These guidelines bias toward **durability and consistency over speed**. For quick one-off tasks, use judgment — not every change needs the full rigor.

The goal is preventing drift and degradation on systems you run for months, not slowing down simple tasks.

## Credits

Inspired by [andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) by forrestchang.

## License

MIT
````
