--- name: self-improvement description: Capture durable lessons from debugging, user corrections, missing capabilities, and repeated workflow friction so future sessions avoid the same mistakes. Use this skill when a non-obvious failure is diagnosed, the user corrects or updates the agent, a workaround or project convention is discovered, a capability is missing, a solved issue should be promoted into shared memory, or you should review prior learnings before changing a known-problem area. Do not use for trivial typos, expected failures, straightforward retries, or one-off noise with no reusable lesson. compatibility: Portable Agent Skills format. Core workflow is agent-agnostic. Bundled helpers require Python 3.11+; hook helpers require bash. No network access is required. Hook snippets are examples for Claude Code-style configs and OpenClaw; manual use works everywhere. metadata: version: "4.0.0" original_slug: "self-improving-agent" category: "workflow" author: "OpenAI adaptation from user-provided skill" ---

Self-Improvement

Capture, review, promote, and extract durable lessons so future sessions avoid repeating the same mistakes.

Core idea

Use this skill for reusable learning, not for every bump in the road.

A good entry usually has at least one of these properties:

• It corrected a wrong assumption.
• It revealed a project-specific convention.
• It required real debugging or investigation.
• It is likely to recur.
• It should change future workflow, memory, or tooling.

Do not log routine noise such as obvious typos, expected validation failures, or errors that were solved immediately with no transferable lesson.

Important path model

There are two different roots in this skill:

1. Skill root — where bundled resources live:

- scripts/... - references/... - assets/...

1. Workspace root — where the project or active workspace lives:

- .learnings/LEARNINGS.md - .learnings/ERRORS.md - .learnings/FEATURE_REQUESTS.md - CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, SOUL.md, TOOLS.md

Never write learnings into the installed skill directory. Always target the workspace root.

Quick decision table

| Situation | What to do | |---|---| | User corrects you or updates a fact | Log a learning | | Non-obvious command / API / tool failure | Log an error | | User asks for a missing capability | Log a feature request | | You discover a reusable workaround or convention | Log a learning | | A pattern keeps recurring | Search related entries, link with See Also, and consider promotion | | A lesson is broadly applicable or repeated | Promote it into project memory | | A resolved, general pattern could help other projects | Extract a new skill |

Standard workflow

1) Find the workspace root first

Before reading or writing .learnings/, determine WORKSPACE_ROOT.

Good defaults:

• the repository root for the current codebase
• the OpenClaw workspace root
• the directory containing the files being edited

If unsure, prefer the directory containing .git, AGENTS.md, CLAUDE.md, or the user's active project files.

2) Initialise .learnings/ if needed

Use the helper instead of creating files manually:

python3 scripts/learnings.py init --root /absolute/path/to/workspace

This creates:

• .learnings/LEARNINGS.md
• .learnings/ERRORS.md
• .learnings/FEATURE_REQUESTS.md

3) Review existing learnings before risky or familiar work

Review first when:

• you are returning to an area with prior failures
• the task touches infra, CI, deployment, auth, data migration, or generated code
• the user explicitly says “remember this”, “we hit this before”, or similar

Use the helper:

python3 scripts/learnings.py status --root /absolute/path/to/workspace
python3 scripts/learnings.py search --root /absolute/path/to/workspace --query "pnpm" --limit 5

4) Search before logging to avoid duplicates

Always search for related entries before creating a new one.

python3 scripts/learnings.py search --root /absolute/path/to/workspace --query "keyword or pattern" --limit 10

If a similar entry already exists:

• prefer linking with See Also
• reuse or add a stable Pattern-Key for recurring issues
• bump priority only when recurrence justifies it
• prefer updating the existing pattern story over spraying near-duplicate entries

5) Log the right kind of entry

Learning

Use for corrections, knowledge gaps, best practices, and durable conventions.

python3 scripts/learnings.py log-learning \
  --root /absolute/path/to/workspace \
  --category correction \
  --priority high \
  --area backend \
  --summary "Project uses pnpm workspaces, not npm" \
  --details "Attempted npm install. Lockfile and workspace config showed pnpm." \
  --suggested-action "Check for pnpm-lock.yaml before assuming npm." \
  --source error \
  --related-files pnpm-lock.yaml pnpm-workspace.yaml \
  --tags package-manager,pnpm

Error

Use for non-obvious failures, exceptions, or tool/API issues worth remembering.

python3 scripts/learnings.py log-error \
  --root /absolute/path/to/workspace \
  --name docker-build \
  --priority high \
  --area infra \
  --summary "Docker build failed on Apple Silicon due to platform mismatch" \
  --error-text "error: failed to solve: no match for platform linux/arm64" \
  --context "docker build -t myapp . on Apple Silicon" \
  --suggested-fix "Retry with --platform linux/amd64 or update base image" \
  --reproducible yes \
  --related-files Dockerfile

Feature request

Use when the user wants a missing capability or a recurring friction point should become a feature.

python3 scripts/learnings.py log-feature \
  --root /absolute/path/to/workspace \
  --capability export-to-csv \
  --priority medium \
  --area backend \
  --summary "User needs report export to CSV" \
  --user-context "Needed for sharing weekly reports with non-technical stakeholders" \
  --complexity-estimate simple \
  --suggested-implementation "Add --output csv alongside existing JSON output" \
  --frequency recurring \
  --related-features analyze-command,json-output

6) Promote proven lessons into memory

Promote when the learning is broad, repeated, or something any future contributor should know.

Common targets:

• CLAUDE.md — durable project facts and conventions
• AGENTS.md — workflow rules and automation guidance
• .github/copilot-instructions.md — shared Copilot context
• SOUL.md — behavioural principles in OpenClaw workspaces
• TOOLS.md — tool-specific gotchas in OpenClaw workspaces

Write promotions as short prevention rules, not long incident write-ups.

Example:

• Bad promotion: “On 2026-03-12 npm failed because…”
• Good promotion: “Use pnpm install in this repo; it is a pnpm workspace.”

When a learning is promoted, update the original entry’s status to promoted or promoted_to_skill and record the destination.

7) Extract a reusable skill when the pattern is real

Extract a new skill when the solution is:

• resolved and working
• broadly useful beyond one file or repo
• non-obvious enough that future agents would benefit
• recurring enough to justify its own instructions

Use the helper:

python3 scripts/extract_skill.py \
  --root /absolute/path/to/workspace \
  docker-build-fixes \
  --description "Fix recurring Docker build and platform mismatch issues. Use when Docker builds fail due to architecture, base image, or runtime packaging problems." \
  --from-learning-id LRN-20260313-001 \
  --scaffold-evals

Or keep the old entry point if existing automation already calls it:

bash scripts/extract-skill.sh docker-build-fixes --root /absolute/path/to/workspace --dry-run

Logging rules that matter most

...