⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
openclaw-guidelines
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.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
Not yet listed on ClawHub or SkillsMP
// README
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:
curl -o CLAUDE.md https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/CLAUDE.md
Existing project (append):
echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/CLAUDE.md >> CLAUDE.md
Codex CLI
curl -o AGENTS.md https://raw.githubusercontent.com/hadikusumawahab/openclaw-maintenance-skill/main/AGENTS.md
Gemini CLI
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:
## 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 by forrestchang.
License
MIT
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
skills/openclaw-guidelines/SKILL.md6.2 KBupstream ↗
--- 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.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/hadikusumawahab-openclaw-maintenance-skill-skills-openclaw-guidelines.md