Claw Self-Improvement

Capture errors, corrections, knowledge gaps, better practices, and feature requests in `.learnings/`, then distill proven recurring patterns into `.learnings...

Security Scan

The skill's code, instructions, and requested actions are coherent with its stated purpose (local capture of learnings and injecting a bootstrap reminder); it does not request credentials, network installs, or unexplained privileges.

Purpose & Capability

Name/description (capture and promote learnings) match the included files and hook: the skill provides templates, a hook that injects a reminder on agent bootstrap, and instructions to initialise local .learnings files. There are no unrelated requirements (no cloud creds or unrelated binaries).

Instruction Scope

SKILL.md and hook only instruct creating/copying local template files, enabling/disabling a hook, and adding a virtual bootstrap reminder. The runtime hook only injects a reminder into bootstrapFiles and does not read arbitrary workspace files or transmit data externally. It will cause the agent to log to local .learnings files when the model follows the workflow (this is explicit).

Install Mechanism

No install spec (instruction-only) and asset copying is done via user-run shell commands; no downloads from external URLs or package installs are requested. Hook code is included in the package and is local.

Credentials

No environment variables, credentials, or config paths beyond writing into ~/.openclaw/workspace/.learnings and ~/.openclaw/hooks. Requested access is proportional to purpose (local file templates and a hook).

Persistence & Privilege

always is false and the skill does not request permanent platform-level privileges. It adds a hook under ~/.openclaw/hooks (user-visible) and creates local .learnings files; removal steps are documented. The skill does not modify other skills or global agent configs by itself.

Assessment

This skill appears consistent and local-only: it will create/seed ~/.openclaw/workspace/.learnings/ and install a hook that injects a reminder during agent bootstrap. There are no network calls or credential requests. Before enabling: (1) review the hook source (hooks/handler.{js,ts}) to confirm behavior (it only appends a virtual bootstrap file), (2) back up any existing ~/.openclaw/workspace/.learnings files you care about (the install copies templates only when files are missing), and (3) be aware that the agent may write user-provided or error content into the .learnings files — avoid enabling it in workspaces that contain sensitive data you do not want logged locally. If you change your mind, follow the documented removal steps (disable hook, rm -rf ~/.openclaw/hooks/claw-self-improvement, remove .learnings entries).

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

Situation	Action
Command/operation fails	Log to .learnings/ERRORS.md
API/external tool fails	Log to .learnings/ERRORS.md with integration details
User corrects you	Log to .learnings/LEARNINGS.md
Knowledge was outdated	Log to .learnings/LEARNINGS.md
Found a better approach	Log to .learnings/LEARNINGS.md
User wants missing capability	Log to .learnings/FEATURE_REQUESTS.md
Similar to an existing entry	Link with See Also; update recurrence notes if useful
Proven recurring pattern	Distill into .learnings/PROMOTED.md
Behavioral / workflow / tool rule	Store in .learnings/PROMOTED.md under the right category

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

Learning Type	Promotion Category
Behavioral patterns	Behavioral Patterns
Workflow improvements	Workflow Improvements
Tool gotchas	Tool Gotchas
Durable facts/rules	Durable Rules

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 - <<'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) + '\n')
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.