Openclaw Md Improver

OpenClaw MD Improver

Audit, evaluate, and improve CLAUDE.md, SOUL.md, and openclaw.json files across the OpenClaw workspace to ensure all agents have optimal project context and personality configuration.

This skill can write to CLAUDE.md, SOUL.md, and openclaw.json files. After presenting a quality report and getting user approval, it updates files with targeted improvements.

Workflow

Phase 1: Discovery

Find all configuration and instruction files in the OpenClaw workspace:

# Find CLAUDE.md files (shared agent instructions)
find ~/.openclaw/workspace -name "CLAUDE.md" 2>/dev/null | head -50

# Find SOUL.md files (per-agent personality)
find ~/.openclaw/workspace -name "SOUL.md" 2>/dev/null | head -50

# Check openclaw.json config
ls -la ~/.openclaw/openclaw.json 2>/dev/null

File Types & Locations:

Agent Workspace IDs: Cooper (main), Pixel (debugger), Vault (cybersecurity), Sage (solution-architect), Oracle (predictive-analyst), Nova (nova), Mirror (metacognition), Vista (business-analyst), Forge (implementation), Vex (tester), Axon (devops), Vigil (quality-assurance), Anchor (content-specialist), Muse (creativity), Cipher (knowledge-curator), Lens (multimodal)

Phase 2: Quality Assessment

For each file type, evaluate against appropriate criteria. See references/quality-criteria.md for detailed rubrics.

CLAUDE.md Assessment Checklist

SOUL.md Assessment Checklist

openclaw.json Assessment Checklist

Quality Scores:

• A (90-100): Comprehensive, current, actionable
• B (70-89): Good coverage, minor gaps
• C (50-69): Basic info, missing key sections
• D (30-49): Sparse or outdated
• F (0-29): Missing or severely outdated

Phase 3: Quality Report Output

ALWAYS output the quality report BEFORE making any updates.

Format:

## OpenClaw Configuration Quality Report

### Summary
- CLAUDE.md files found: X
- SOUL.md files found: X
- openclaw.json status: [present/missing]
- Average score: X/100
- Files needing update: X

### File-by-File Assessment

#### 1. ~/.openclaw/workspace/CLAUDE.md (Shared Root)
**Score: XX/100 (Grade: X)**

| Criterion | Score | Notes |
|-----------|-------|-------|
| Agent routing rules | X/20 | ... |
| Process workflows | X/20 | ... |
| Comms patterns | X/15 | ... |
| Conciseness | X/15 | ... |
| Currency | X/15 | ... |
| Actionability | X/15 | ... |

**Issues:**
- [List specific problems]

**Recommended additions:**
- [List what should be added]

#### 2. ~/.openclaw/workspace/agents-workspaces/main/SOUL.md (Cooper)
...

#### 3. ~/.openclaw/openclaw.json (System Config)
...

Phase 4: Targeted Updates

After outputting the quality report, ask user for confirmation before updating.

Update Guidelines (Critical):

1. Propose targeted additions only - Focus on genuinely useful info:

   • Agent routing rules or dispatch patterns discovered during analysis
   • Gotchas or non-obvious patterns found in configuration
   • Agent relationships that weren't clear
   • Process workflows that work
   • Configuration quirks

2. Keep it minimal - Avoid:

   • Restating what's obvious from the config
   • Generic best practices already covered
   • One-off fixes unlikely to recur
   • Verbose explanations when a one-liner suffices

3. Show diffs - For each change, show:

   • Which file to update
   • The specific addition (as a diff or quoted block)
   • Brief explanation of why this helps future sessions

Diff Format:

### Update: ~/.openclaw/workspace/CLAUDE.md

**Why:** Agent routing rules were missing, causing confusion about dispatch.

```diff
+ ## Agent Routing
+
+ | Tag | Agent | When |
+ |-----|-------|------|
+ | security | Vault | Threat analysis, auth review |
+ | debug | Pixel | Root cause analysis |
+ | research | Nova | R&D tasks only |

### Phase 5: Apply Updates

After user approval, apply changes using the Edit tool. Preserve existing content structure.

## Templates

See [references/templates.md](references/templates.md) for CLAUDE.md and SOUL.md templates.

## Common Issues to Flag

1. **Stale agent roster**: CLAUDE.md references agents that have been removed or renamed
2. **Missing SOUL.md**: Agent workspace exists but SOUL.md is blank or missing
3. **Model mismatch**: openclaw.json model assignments don't match CLAUDE.md roster table
4. **Broken fallback chains**: Fallback models reference non-existent providers
5. **Cron schedule conflicts**: Multiple crons targeting same agent at same time
6. **Missing auth profiles**: Agent auth-profiles.json missing Google API key for Gemini embeddings
7. **Context window too small**: Models with contextWindow < 16000 will be blocked by gateway

## User Tips to Share

When presenting recommendations, remind users:

- **Keep CLAUDE.md concise**: It's read by ALL 16 agents — every line costs context across all sessions
- **SOUL.md is per-agent**: Put agent-specific personality and behavior here, not in shared CLAUDE.md
- **openclaw.json is the source of truth**: Model routing, cron jobs, and provider config all live here
- **Test after changes**: Run `openclaw doctor` to verify config health
- **Backup first**: Config is backed up nightly via restic, but manual backup before big changes is wise

## What Makes Great OpenClaw Configuration

**CLAUDE.md principles:**
- Concise and shared — only instructions ALL agents need
- Agent routing table current with all 16 agents
- Process references accurate (23 processes, L1-L4 maturity)
- Comms patterns clear (file-based inboxes/outboxes)

**SOUL.md principles:**
- Clear role and specialization
- Personality that matches the agent's purpose
- Standing orders for idle time
- Communication style defined

**openclaw.json principles:**
- All 16 agents with correct primary + fallback chains
- Provider auth configured and verified
- Cron schedules non-overlapping where possible
- Gateway rate limits appropriate