Claw Self-Improvement Skill

Lightweight, reversible self-improvement for agent sessions.

Use it to:

• capture raw learnings in .learnings/
• preserve detail in incident-style logs
• distill only proven patterns into .learnings/PROMOTED.md
• keep broader workspace prompt files untouched by default

After installation, follow the Setup section to initialize .learnings/, enable the hook, and restart the gateway.

Once active, the model is guided to use the learning workflow in future runs.

The learning process remains model-mediated, so results depend on model capability, instruction-following quality, and task relevance.

Quick Reference

Expected Files

This skill expects these files under ~/.openclaw/workspace/.learnings/:

• LEARNINGS.md — raw learnings, corrections, knowledge gaps, best practices
• ERRORS.md — failures, exceptions, unexpected tool behavior
• FEATURE_REQUESTS.md — missing capabilities requested by the user
• PROMOTED.md — distilled, durable rules promoted out of raw learnings

Setup

1. Install the Skill

clawhub install claw-self-improvement

2. Initialize .learnings/

Create missing starter files without overwriting existing .learnings/ history:

SKILL_DIR=~/.openclaw/workspace/skills/claw-self-improvement
mkdir -p ~/.openclaw/workspace/.learnings

[ -e ~/.openclaw/workspace/.learnings/LEARNINGS.md ] || cp "$SKILL_DIR"/assets/LEARNINGS.md ~/.openclaw/workspace/.learnings/LEARNINGS.md
[ -e ~/.openclaw/workspace/.learnings/ERRORS.md ] || cp "$SKILL_DIR"/assets/ERRORS.md ~/.openclaw/workspace/.learnings/ERRORS.md
[ -e ~/.openclaw/workspace/.learnings/FEATURE_REQUESTS.md ] || cp "$SKILL_DIR"/assets/FEATURE_REQUESTS.md ~/.openclaw/workspace/.learnings/FEATURE_REQUESTS.md
[ -e ~/.openclaw/workspace/.learnings/PROMOTED.md ] || cp "$SKILL_DIR"/assets/PROMOTED.md ~/.openclaw/workspace/.learnings/PROMOTED.md

3. Enable the Hook

To inject the reminder during agent:bootstrap, install or refresh the hook files:

SKILL_DIR=~/.openclaw/workspace/skills/claw-self-improvement
mkdir -p ~/.openclaw/hooks/claw-self-improvement
cp -R "$SKILL_DIR"/hooks/. ~/.openclaw/hooks/claw-self-improvement/
openclaw hooks enable claw-self-improvement

4. Verify

ls ~/.openclaw/workspace/.learnings
openclaw hooks list

5. (Optional) Enable Visible Learning Notices

Use the OpenClaw config gate below if you want the hook to inject a stronger instruction for visible learning notices:

{
  "skills": {
    "entries": {
      "claw-self-improvement": {
        "config": {
          "message": true
        }
      }
    }
  }
}

If you also want phrasing guidance, add the following preference block to TOOLS.md:

### claw-self-improvement
- UX preference: when you add a new entry to `.learnings/` during a user-facing reply, append one short confirmation line.
- For raw logs, say: `Noted — logged to .learnings/LEARNINGS.md.`, `Noted — logged to .learnings/ERRORS.md.` or `Noted — logged to .learnings/FEATURE_REQUESTS.md.`
- For promotions, say: `Promoted — new rule to .learnings/PROMOTED.md.`
- Keep the notice brief and only include it once per reply.
- Skip the notice when there is no user-visible reply, or when replying `NO_REPLY`.

6. Restart Gateway

openclaw gateway restart

Default Workflow

1. Capture the raw event in the appropriate .learnings/ file.
2. Keep the source entry detailed enough to understand later.
3. If the idea becomes durable, recurring, or broadly useful, distill it into a short entry in .learnings/PROMOTED.md.
4. Mark the source entry as promoted:
   • **Status**: promoted
   • **Promoted**: .learnings/PROMOTED.md
   • optional: **Promotion-ID**: PRM-YYYYMMDD-XXX
   • optional: **Promotion-Category**: Behavioral Patterns | Workflow Improvements | Tool Gotchas | Durable Rules

When to Promote

Promote to .learnings/PROMOTED.md only when the pattern is mature enough to reuse:

• it has recurred, or clearly will recur
• the solution is resolved, tested, or otherwise trusted
• it can be expressed as a short actionable rule
• it is not just a one-off incident log
• it is safe to keep as durable context

When to Keep Raw

Keep the entry in the raw .learnings/ files when it is:

• still unresolved or uncertain
• highly task-specific
• mostly useful as historical context
• too noisy to distill into a stable rule yet

Format Reference

For exact field definitions, templates, and examples, read:

• references/FORMAT.md

The files in assets/ are minimal starter templates to copy into .learnings/.

Removal

1. Disable the Hook

openclaw hooks disable claw-self-improvement

2. Remove the Hook Files

rm -rf ~/.openclaw/hooks/claw-self-improvement

3. Remove the Skill Files

rm -rf ~/.openclaw/workspace/skills/claw-self-improvement

4. Remove the ClawHub Lockfile Entry

If the skill was installed via ClawHub, also remove its local install record from ~/.openclaw/workspace/.clawhub/lock.json.

python3 - \x3C\x3C'PY'
from pathlib import Path
import json

path = Path.home() / '.openclaw/workspace/.clawhub/lock.json'
if path.exists():
    data = json.loads(path.read_text())
    skills = data.get('skills')
    if isinstance(skills, dict):
        skills.pop('claw-self-improvement', None)
    path.write_text(json.dumps(data, indent=2) + '\
')
PY

5. Optional: Remove .learnings/ Files

The .learnings/ directory is your captured history, not the hook itself. You can keep it for reference, or remove the files if you no longer want the data.

Remove only the files created for this workflow:

rm -f ~/.openclaw/workspace/.learnings/LEARNINGS.md \
      ~/.openclaw/workspace/.learnings/ERRORS.md \
      ~/.openclaw/workspace/.learnings/FEATURE_REQUESTS.md \
      ~/.openclaw/workspace/.learnings/PROMOTED.md

If the directory is empty afterward, you can remove it too:

rmdir ~/.openclaw/workspace/.learnings 2>/dev/null || true

6. Disable Visible Learning Notices if Enabled

Remove the claw-self-improvement block from TOOLS.md if you added it during installation.

7. Restart Gateway

openclaw gateway restart

After restart, future runs will no longer receive the bootstrap reminder from this skill. Existing Markdown history remains unless you explicitly delete it.

Provenance

Adapted from peterskoett/self-improving-agent.