Captures learnings, errors, corrections, and feature requests to enable continuous improvement. Use when: (1) User corrects Claude ('No, that's wrong...', 'Actually...'), (2) User requests a capability that doesn't exist, (3) Claude realizes its knowledge is outdated or incorrect, (4) A better appro

Self Improvement Skill Install For CI only execution, use: Fallback using the Agent Skills CLI: Log learnings and errors to markdown files for continuous improvement. Coding agents can later process these into fixes, and important learnings get promoted to project memory. Pair with [ self healing ](../self healing/SKILL.md): self healing is the active runtime recovery primitive — it diagnoses, patches, verifies, and files HEAL entries to .learnings/HEALS.md when something breaks mid task. Self improvement (this skill) is the passive accumulation and promotion layer — it logs corrections, knowledge gaps, and feature requests, and promotes recurring heal handoffs to permanent memory. They share .learnings/ but write to different files; verify discipline lives in self healing, promotion logic lives here. Quick Reference Situation Action Active failure mid task — agent needs to fix it now Use self healing instead (files verified HEAL to .learnings/HEALS.md ) Command/operation failed in the past (not actively healing) Log to .learnings/ERRORS.md User corrects you Log to .learnings/LEARNINGS.md with category correction User wants missing feature Log to .learnings/FEATURE REQUESTS.md API/external tool fails Log to .learnings/ERRORS.md with integration details Self healing Handoff block meets promotion rule (see Promotion Rule below) Promote the Distilled Rule to CLAUDE.md / AGENTS.md / new skill Knowledge was outdated Log to .learnings/LEARNINGS.md with category knowledge gap Found better approach Log to .learnings/LEARNINGS.md with category best practice Simplify/Harden recurring patterns Log/update .learnings/LEARNINGS.md with Source: simplify and harden and a stable Pattern Key Similar to existing entry Link with See Also , consider priority bump Broadly applicable learning Promote to CLAUDE.md , AGENTS.md , and/or .github/copilot instructions.md OpenClaw workspace targets (SOUL.md, TOOLS.md) See references/openclaw integration.md Setup Create .learnings/ directory in project root if it doesn't exist: Copy the file templates from assets/ ( LEARNINGS.md , ERRORS.md , FEATURE REQUESTS.md ) or create files with headers. Logging Format Learning Entry Append to .learnings/LEARNINGS.md : Error Entry Append to .learnings/ERRORS.md : Actual error message or output Feature Request Entry Append to .learnings/FEATURE REQUESTS.md : ID Generation Format: TYPE YYYYMMDD XXX TYPE: LRN (learning), ERR (error), FEAT (feature) YYYYMMDD: Current date XXX: Sequential number or random 3 chars (e.g., 001 , A7B ) Examples: LRN 20250115 001 , ERR 20250115 A3F , FEAT 20250115 002 Resolving Entries When an issue is fixed, update the entry: 1. Change Status : pending → Status : resolved 2. Add resolution block after Metadata: Other status values: in progress Actively being worked on wont fix Decided not to address (add reason in Resolution notes) promoted Elevated to CLAUDE.md, AGENTS.md, or .github/copilot instructions.md promoted to skill Extracted as a reusable skill (see Automatic Skill Extraction) Promoting to Project Memory When a learning is broadly applicable (not a one off fix), promote it to permanent project memory. When to Promote Learning applies across multiple files/features Knowledge any contributor (human or AI) should know Prevents recurring mistakes Documents project specific conventions Promotion Targets Target What Belongs There CLAUDE.md Project facts, conventions, gotchas for all Claude interactions AGENTS.md Agent specific workflows, tool usage patterns, automation rules .github/copilot instructions.md Project context and conventions for GitHub Copilot OpenClaw workspace targets ( SOUL.md , TOOLS.md ) are covered in references/openclaw integration.md . How to Promote 1. Distill the learning into a concise rule or fact 2. Add to appropriate section in target file (create file if needed) 3. Update original entry: Change Status : pending → Status : promoted Add Promoted : CLAUDE.md , AGENTS.md , or .github/copilot instructions.md Promotion Examples Learning (verbose): Project uses pnpm workspaces. Attempted npm install but failed. Lock file is pnpm lock.yaml . Must use pnpm install . In CLAUDE.md (concise): Learning (verbose): When modifying API endpoints, must regenerate TypeScript client. Forgetting this causes type mismatches at runtime. In AGENTS.md (actionable): Recurring Pattern Detection If logging something similar to an existing entry: 1. Search first : grep r "keyword" .learnings/ 2. Link entries : Add See Also : ERR 20250110 001 in Metadata 3. Bump priority if issue keeps recurring 4. Consider systemic fix : Recurring issues often indicate: Missing documentation (→ promote to CLAUDE.md or .github/copilot instructions.md) Missing automation (→ add to AGENTS.md) Architectural problem (→ create tech debt ticket) Simplify & Harden Feed Use this workflow to ingest recurring patterns from the simplify and harden skill and turn them into durable prompt guidance. Ingestion Workflow 1. Read simplify and harden.learning loop.candidates from the task summary. 2. For each candidate, use pattern key as the stable dedupe key. 3. Search .learnings/LEARNINGS.md for an existing entry with that key: grep n "Pattern Key: <pattern key " .learnings/LEARNINGS.md 4. If found: Increment Recurrence Count Update Last Seen Add See Also links to related entries/tasks 5. If not found: Create a new LRN ... entry Set Source: simplify and harden Set Pattern Key , Recurrence Count: 1 , and First Seen / Last Seen Promotion Rule (System Prompt Feedback) Promote recurring patterns into agent context/system prompt files when all are true: Recurrence Count = 3 Seen across at least 2 distinct tasks Occurred within a 30 day window Promotion targets: CLAUDE.md AGENTS.md .github/copilot instructions.md OpenClaw workspace files when applicable — see references/openclaw integration.md This three condition rule is the single promotion threshold for this skill. The Quick Reference row for self healing Handoff blocks and the aggregator skills ( learning aggregator , learning aggregator ci ) all use this same rule. Write promoted rules as short prevention rules (what to do before/while coding), not long incident write ups. Periodic Review Review .learnings/ at natural breakpoints: When to Review Before starting a new major task After completing a feature When working in an area with past learnings Weekly during active development Quick Status Check Review Actions Resolve fixed items Promote applicable learnings Link related entries Escalate recurring issues Detection Triggers Automatically log when you notice: Corrections (→ learning with correction category): "No, that's not right..." "Actually, it should be..." "You're wrong about..." "That's outdated..." Feature Requests (→ feature request): "Can you also..." "I wish you could..." "Is there a way to..." "Why can't you..." Knowledge Gaps (→ learning with knowledge gap category): User provides information you didn't know Documentation you referenced is outdated API behavior differs from your understanding Errors (→ error entry): Command returns non zero exit code Exception or stack trace Unexpected output or behavior Timeout or connection failure Priority Guidelines Priority When to Use critical Blocks core functionality, data loss risk, security issue high Significant impact, affects common workflows, recurring issue medium Moderate impact, workaround exists low Minor inconvenience, edge case, nice to have Area Tags Use to filter learnings by codebase region: Area Scope frontend UI, components, client side code backend API, services, server side code infra CI/CD, deployment, Docker, cloud tests Test files, testing utilities, coverage docs Documentation, comments, READMEs config Configuration files, environment, settings Best Practices 1. Log immediately context is freshest right after the issue 2. Be specific future agents need to understand quickly 3. Include reproduction steps especially for errors 4. Link related files makes fixes easier 5. Suggest concrete fixes not just "investigate" 6. Use consistent categories enables filtering 7. Promote aggressively if in doubt, add to CLAUDE.md or .github/copilot instructions.md 8. Review regularly stale learnings lose value Gitignore Options Keep learnings local (per developer): Track learnings in repo (team wide): Don't add to .gitignore learnings become shared knowledge. Hybrid (track templates, ignore entries): Hook Integration Enable automatic reminders through agent hooks. This is opt in you must explicitly configure hooks. The same two scripts work across Claude Code and Codex CLI (both deliver JSON on stdin and accept the same additionalContext output shape); Copilot hooks can log but not inject context, so Copilot uses the instructions file channel. Full per agent setup including Codex and Copilot: references/hooks setup.md . Quick Setup (Claude Code) Create .claude/settings.json in your project. The command path must point to where the skill is actually installed: .claude/skills/self improvement/ for gh skill install / npx skills add , or skills/self improvement/ if this repo is vendored into the project. Relative paths resolve from the project root. This injects a learning evaluation reminder after each prompt (~50 100 tokens overhead). Full Setup (With Error Detection) Hooks receive the event payload as JSON on stdin. The error detector parses tool response from that JSON and returns its reminder as additionalContext JSON output, which is required for PostToolUse output to reach the model. Available Hook Scripts Script Hook Type Purpose scripts/activator.sh UserPromptSubmit (Claude Code, Codex) Reminds to evaluate learnings after tasks (plain stdout is added to context for this event on both agents) scripts/error detector.sh PostToolUse (Claude Code, Codex), postToolUse (Copilot, logging only) Parses the stdin JSON payload for error patterns across all three agents' payload shapes; emits an additionalContext reminder See references/hooks setup.md for detailed configuration and troubleshooting. Automatic Skill Extraction When a learning is valuable enough to become a reusable skill, extract it using the provided helper. Skill Extraction Criteria A learning qualifies for skill extraction when ANY of these apply: Criterion Description Recurring Has See Also links to 2+ similar issues Verified Status is resolved with working fix Non obvious Required actual debugging/investigation to discover Broadly applicable Not project specific; useful across codebases User flagged User says "save this as a skill" or similar Extraction Workflow 1. Identify candidate : Learning meets extraction criteria 2. Run helper (or create manually): 3. Customize SKILL.md : Fill in template with learning content 4. Update learning : Set status to promoted to skill , add Skill Path 5. Verify : Read skill in fresh session to ensure it's self contained Manual Extraction If you prefer manual creation: 1. Create skills/<skill name /SKILL.md 2. Use template from assets/SKILL TEMPLATE.md 3. Follow [Agent Skills spec](https://agentskills.io/specification

self-improvement