Self-Improving Agent (OpenClaw)

Scope

• In-scope: capture durable lessons from incidents, corrections, and recurring patterns; choose the correct destination; promote concise reusable rules when evidence is strong enough.
• Out-of-scope: copying incident diaries into governance docs, promoting weak/untested hunches, or turning routine file edits into bureaucracy.

Indexed Reference Map

• @[SKILL.md#L1-L179] Frontmatter + complete skill definition.
• @[SKILL.md#L12-L179] Scope, destination model, and lane selection.
• @[SKILL.md#L31-L122] Logging, promotion, and quality-gate SOP.
• @[SKILL.md#L124-L179] Guardrails, trigger rules, error handling, and output contract.

Supporting files

• @[references/INDEX.md#L1-L5] Reading order and document purpose.
• @[references/openclaw-integration.md#L1-L47] Destination matrix + OpenClaw workspace integration.
• @[references/hooks-setup.md#L1-L29] Compact setup hook for Claude/Codex/OpenClaw.
• @[references/examples.md#L1-L52] Minimal and full entry examples.
• @[scripts/activator.sh#L1-L9] Light hook reminder.
• @[scripts/error-detector.sh#L1-L13] Error detector minimalist.
• @[scripts/extract-skill.sh#L1-L53] Scaffold utility safe path.
• @[hooks/openclaw/HOOK.md#L1-L10] Hook metadata for OpenClaw.
• @[hooks/openclaw/handler.ts#L1-L19] Bootstrap injection handler.

KB Mode Notes

• Reading order:
  1. references/INDEX.md
  2. references/openclaw-integration.md
  3. references/hooks-setup.md
  4. references/examples.md
• Coverage Matrix:
  • destination model + workspace integration -> openclaw-integration.md
  • hook bootstrap/setup -> hooks-setup.md
  • minimal/full logging examples -> examples.md
• Portability note:
  • This skill manages learnings in the OpenClaw workspace. Promotion rules must stay evidence-backed and must not log secrets.

When to use

• A command/tool/runtime error should be remembered and not relearned next session.
• Boss correction changes previous understanding and the lesson may outlive the current task.
• A best practice repeats across tasks and should become a reusable rule.
• A verified incident needs to be promoted into the correct long-term destination.

Destination model

• .learnings/ERRORS.md -> command/tool/runtime error patterns still being tracked.
• .learnings/LEARNINGS.md -> corrections, knowledge gaps, reusable best practices still incubating.
• .learnings/FEATURE_REQUESTS.md -> capability the user wants but does not have yet.
• MEMORY.md -> durable cross-session rules, decisions, and preferences.
• AGENTS.md -> workflow/system behavior and workspace-level policy.
• TOOLS.md -> host/runtime/tool contract and operational gotchas.
• SOUL.md -> behavioral/communication policy.

Lane selection

Use one of two lanes:

Lane A — Direct Promote

Use when the lesson is already durable, verified, and broad enough to canonize now. Typical triggers:

• Boss explicitly asks to turn it into a rule.
• The lesson is foundational, host-wide, or high-cost to forget.
• Evidence is already strong enough that waiting for more recurrence adds no value.

Lane B — Learning Queue

Use when the lesson is plausible and useful, but still provisional or too incident-local for immediate canonization. Typical triggers:

• first occurrence with incomplete confidence
• uncertain reuse scope
• needs recurrence tracking before promotion

SOP

1. Determine whether the request is within scope.
2. Classify the lesson:
   • error
   • correction
   • recurring best practice
   • feature gap
3. Choose the lane:
   • Direct Promote
   • Learning Queue
4. Choose the destination using the destination model above.
5. Apply the quality gate before writing:
   • Is this durable, or just incident detail?
   • Is the evidence verified or only heuristic?
   • Does the destination match the lesson type?
   • Is the rule distilled, or am I copying the incident?
6. If using Learning Queue, log the entry in minimal mode by default; use full mode only when extra structure genuinely helps.
7. If using Direct Promote, write a short actionable rule into the correct target and keep the original incident compressed.
8. If a pattern is recurring, update recurrence metadata instead of creating duplicate entries.
9. Verify the edited destination and report what was logged/promoted.

Logging modes

Minimal mode (default)

Use unless the task truly needs more ceremony. Required fields:

• ID (ERR/LRN/FEAT-YYYYMMDD-XXX)
• Summary
• Source incident/task
• Pattern-Key
• Candidate destination
• Status

Full mode (optional)

Use when the task needs richer tracking or human follow-up. Additional fields may include:

• timestamp
• priority
• area
• details/context
• suggested action
• related files
• recurrence count

Promotion quality gate

Promote only when at least one of these is true:

• Boss explicitly wants canonization now.
• The lesson is foundational, host-wide, or expensive to relearn.
• The lesson has repeated enough times to show broad reuse.

Recommended recurrence heuristic, not a hard gate:

• Recurrence-Count >= 3
• appears in >= 2 tasks
• within a 30-day window

Rules when promoting:

1. Distill into a short, actionable rule.
2. Do not copy the entire long incident.
3. Keep only the evidence needed to justify the rule.
4. Link back to the learning ID when traceability matters.

OpenClaw integration

• Use workspace .learnings/ to keep state across sessions.
• Learning can be sent between sessions using sessions_send when needed.
• Hook agent:bootstrap only injects light reminders, not spam.
• Prefer updating an existing entry when the root cause is the same.

Guardrails

• Do not write secrets/tokens into learning files.
• Do not log sensitive user data beyond minimal debugging needs.
• Do not create duplicate entries for the same root cause.
• Do not promote incident-specific chatter into MEMORY.md, AGENTS.md, TOOLS.md, or SOUL.md.
• Keep confidence subordinate to evidence; label provisional conclusions clearly.

Output Contract

When using this skill in a task, return summary:

self_improvement:
  lane: direct_promote|learning_queue
  logged:
    learnings: 0
    errors: 0
    feature_requests: 0
  promoted_to: []
  updated:
    recurrence_keys: []
  followup_required: false

Trigger Rules

• Positive: trigger when the request is to capture a lesson, convert an incident into a reusable rule, update .learnings/*, or promote a durable verified lesson into MEMORY.md, AGENTS.md, TOOLS.md, or SOUL.md.
• Negative: do not trigger for routine file edits, ordinary memory notes, or changes with no durable learning value.
• Escalation: if the action includes external/network write or sensitive operations, add an approval checkpoint before executing.

Error Handling

• If input/permissions are missing: state what is missing and request it clearly.
• If there is a runtime/tool error: return a concise error + likely cause + suggested fix.
• If the lesson is too weak for promotion: keep it in Learning Queue or say why no write should happen yet.
• If there is policy/safety risk: stop and escalate via approval checkpoint.