Self-Improvement

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

Quick decision table

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

1. Search first. Duplicate entries are worse than missing tags.
2. Prefer durable lessons. Only log what should change future behaviour.
3. Be specific. Name the assumption, failure, or convention clearly.
4. Include the fix or prevention rule. An entry without next action is weak.
5. Use stable pattern keys for recurring problems. This lets recurrence compound.
6. Promote aggressively once a rule is proven. The point is fewer repeat mistakes.
7. Do not interrupt the user with bookkeeping. Log silently unless the user asked to see it or you need missing details.

Recommended references

Use these only when needed:

• references/entry-formats.md — full field schemas and manual templates
• references/examples.md — concrete examples of good entries and promotions
• references/promotion-and-extraction.md — promotion rules and skill extraction criteria
• references/platform-setup.md — Claude Code, Codex, Copilot, and OpenClaw setup notes
• references/evaluation.md — trigger/output eval plan for this skill
• references/openclaw-integration.md — deeper OpenClaw workflow guidance

Hooks

Hook helpers are intentionally optional.

Available hook scripts:

• scripts/activator.sh — lightweight reminder at prompt start
• scripts/error-detector.sh — lightweight error reminder after failed Bash-like commands

Hook configuration examples live in references/platform-setup.md.

What “next-level” looks like for this skill

A mature use of this skill has a loop:

capture → dedupe → promote → extract → evaluate

That means:

• entries are created with deterministic IDs and consistent fields
• repeated issues link to each other instead of fragmenting
• proven rules move into persistent memory files
• broadly useful fixes become standalone skills
• the skill itself is tested with trigger and output evals in evals/