self-improvement

name self-improvement description 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 approach is discovered for a recurring task, (5) Receiving a Handoff block from self-healing (a recurring verified heal at Recurrence-Count >= 3) to distill into a memory file or new skill. For ACTIVE runtime failures where the agent needs to apply and verify a fix mid-task, use `self-healing` instead (it files HEAL- entries with proof; self-improvement promotes accumulated patterns). Also review learnings before major tasks. For CI-only/headless learning capture, use self-improvement-ci. Self-Improvement Skill Install gh skill install pskoett/pskoett-skills self-improvement For CI-only execution, use: gh skill install pskoett/pskoett-skills self-improvement-ci Fallback using the Agent Skills CLI: npx skills add pskoett/pskoett-skills/skills/self-improvement npx skills add pskoett/pskoett-skills/skills/self-improvement-ci 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 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: mkdir -p .learnings 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 : ## [LRN-YYYYMMDD-XXX] category **Logged** : ISO-8601 timestamp **Priority** : low | medium | high | critical **Status** : pending **Area** : frontend | backend | infra | tests | docs | config ### Summary One-line description of what was learned ### Details Full context: what happened, what was wrong, what's correct ### Suggested Action Specific fix or improvement to make ### Metadata - Source: conversation | error | user _feedback - Related Files: path/to/file.ext - Tags: tag1, tag2 - See Also: LRN-20250110-001 (if related to existing entry) - Pattern-Key: simplify.dead_ code | harden.input _validation (optional, for recurring-pattern tracking) - Recurrence-Count: 1 (optional) - First-Seen: 2025-01-15 (optional) - Last-Seen: 2025-01-15 (optional) --- Error Entry Append to .learnings/ERRORS.md : ## [ERR-YYYYMMDD-XXX] skill _or_ command _name **Logged** : ISO-8601 timestamp **Priority** : high **Status** : pending **Area** : frontend | backend | infra | tests | docs | config ### Summary Brief description of what failed ### Error Actual error message or output ### Context - Command/operation attempted - Input or parameters used - Environment details if relevant ### Suggested Fix If identifiable, what might resolve this ### Metadata - Reproducible: yes | no | unknown - Related Files: path/to/file.ext - See Also: ERR-20250110-001 (if recurring) --- Feature Request Entry Append to .learnings/FEATURE_REQUESTS.md : ## [FEAT-YYYYMMDD-XXX] capability _name **Logged** : ISO-8601 timestamp **Priority** : medium **Status** : pending **Area** : frontend | backend | infra | tests | docs | config ### Requested Capability What the user wanted to do ### User Context Why they needed it, what problem they're solving ### Complexity Estimate simple | medium | complex ### Suggested Implementation How this could be built, what it might extend ### Metadata - Frequency: first_ time | recurring - Related Features: existing _feature_ name --- 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: Change **Status**: pending → **Status**: resolved Add resolution block after Metadata: ### Resolution - **Resolved** : 2025-01-16T09:00:00Z - **Commit/PR** : abc123 or #42 - **Notes** : Brief description of what was done 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 Distill the learning into a concise rule or fact Add to appropriate section in target file (create file if needed) 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): ## Build & Dependencies - Package manager: pnpm (not npm) - use `pnpm install` Learning (verbose): When modifying API endpoints, must regenerate TypeScript client. Forgetting this causes type mismatches at runtime. In AGENTS.md (actionable): ## After API Changes 1. Regenerate client: `pnpm run generate:api` 2. Check for type errors: `pnpm tsc --noEmit` Recurring Pattern Detection If logging something similar to an existing entry: Search first : grep -r "keyword" .learnings/ Link entries : Add **See Also**: ERR-20250110-001 in Metadata Bump priority if issue keeps recurring 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 Read simplify_and_harden.learning_loop.candidates from the task summary. For each candidate, use pattern_key as the stable dedupe key. Search .learnings/LEARNINGS.md for an existing entry with that key: grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md If found: Increment Recurrence-Count Update Last-Seen Add See Also links to related entries/tasks 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 # Count pending items grep -h "Status\*\*: pending" .learnings/*.md | wc -l # List pending high-priority items grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \[" # Find learnings for a specific area grep -l "Area\*\*: backend" .learnings/*.md 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 Log immediately - context is freshest right after the issue Be specific - future agents need to understand quickly Include reproduction steps - especially for errors Link related files - makes fixes easier Suggest concrete fixes - not just "investigate" Use consistent categories - enables filtering Promote aggressively - if in doubt, add to CLAUDE.md or .github/copilot-instructions.md Review regularly - stale learnings lose value Gitignore Options Keep learnings local (per-developer): .learnings/ Track learnings in repo (team-wide): Don't add to .gitignore - learnings become shared knowledge. Hybrid (track templates, ignore entries): .learnings/*.md !.learnings/.gitkeep