Self-Improvement Skill

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.

Quick Reference

Situation	Action
Command/operation fails	Log to INLINECODE0
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 | | Knowledge was outdated | Log to .learnings/LEARNINGS.md with category knowledge_gap | | Found better approach | Log to .learnings/LEARNINGS.md with category best_practice | | 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 | | Workflow improvements | Promote to AGENTS.md (OpenClaw workspace) | | Tool gotchas | Promote to TOOLS.md (OpenClaw workspace) | | Behavioral patterns | Promote to SOUL.md (OpenClaw workspace) |

OpenClaw Setup (Recommended)

OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.

Installation

Via ClawdHub (recommended):
CODEBLOCK0

Manual:
CODEBLOCK1

Workspace Structure

OpenClaw injects these files into every session:

CODEBLOCK2

Create Learning Files

CODEBLOCK3

Then create the log files (or copy from assets/):

• - LEARNINGS.md — corrections, knowledge gaps, best practices
• INLINECODE18 — command failures, exceptions
• INLINECODE19 — user-requested capabilities

Promotion Targets

When learnings prove broadly applicable, promote them to workspace files:

Learning Type	Promote To	Example
Behavioral patterns	INLINECODE20	"Be concise, avoid disclaimers"
Workflow improvements

AGENTS.md | "Spawn sub-agents for long tasks" |
| Tool gotchas | TOOLS.md | "Git push needs auth configured first" |

Inter-Session Communication

OpenClaw provides tools to share learnings across sessions:

• - sessionslist — View active/recent sessions
• sessionshistory — Read another session's transcript
• sessionssend — Send a learning to another session
• sessionsspawn — Spawn a sub-agent for background work

Optional: Enable Hook

For automatic reminders at session start:

CODEBLOCK4

See references/openclaw-integration.md for complete details.

---

Generic Setup (Other Agents)

For Claude Code, Codex, Copilot, or other agents, create .learnings/ in your project:

CODEBLOCK5

Copy templates from assets/ or create files with headers.

Logging Format

Learning Entry

Append to .learnings/LEARNINGS.md:

CODEBLOCK6

Error Entry

Append to .learnings/ERRORS.md:

CODEBLOCK7
Actual error message or output
CODEBLOCK8

Feature Request Entry

Append to .learnings/FEATURE_REQUESTS.md:

CODEBLOCK9

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, INLINECODE37

Resolving Entries

When an issue is fixed, update the entry:

1. 1. Change **Status**: pending → INLINECODE39
2. Add resolution block after Metadata:

CODEBLOCK10

Other status values:

• - in_progress - Actively being worked on
• INLINECODE41 - Decided not to address (add reason in Resolution notes)
• INLINECODE42 - Elevated to CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md

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
INLINECODE43	Project facts, conventions, gotchas for all Claude interactions
INLINECODE44

Agent-specific workflows, tool usage patterns, automation rules | | .github/copilot-instructions.md | Project context and conventions for GitHub Copilot | | SOUL.md | Behavioral guidelines, communication style, principles (OpenClaw workspace) | | TOOLS.md | Tool capabilities, usage patterns, integration gotchas (OpenClaw workspace) |

How to Promote

1. 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 INLINECODE52

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):
CODEBLOCK11

Learning (verbose):

When modifying API endpoints, must regenerate TypeScript client.

Forgetting this causes type mismatches at runtime.

In AGENTS.md (actionable):
CODEBLOCK12

Recurring Pattern Detection

If logging something similar to an existing entry:

1. 1. Search first: INLINECODE56
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)

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

CODEBLOCK13

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
INLINECODE61	Blocks core functionality, data loss risk, security issue
INLINECODE62

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
INLINECODE65	UI, components, client-side code
INLINECODE66

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. 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):
CODEBLOCK14

Track learnings in repo (team-wide):
Don't add to .gitignore - learnings become shared knowledge.

Hybrid (track templates, ignore entries):
CODEBLOCK15

Hook Integration

Enable automatic reminders through agent hooks. This is opt-in - you must explicitly configure hooks.

Quick Setup (Claude Code / Codex)

Create .claude/settings.json in your project:

CODEBLOCK16

This injects a learning evaluation reminder after each prompt (~50-100 tokens overhead).

Full Setup (With Error Detection)

CODEBLOCK17

Available Hook Scripts

Script	Hook Type	Purpose
INLINECODE72	UserPromptSubmit	Reminds to evaluate learnings after tasks
INLINECODE73

PostToolUse (Bash) | Triggers on command errors |

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. 1. Identify candidate: Learning meets extraction criteria
2. Run helper (or create manually):

   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
   ./skills/self-improvement/scripts/extract-skill.sh skill-name
   

1. 3. Customize SKILL.md: Fill in template with learning content
2. Update learning: Set status to promoted_to_skill, add INLINECODE78
3. Verify: Read skill in fresh session to ensure it's self-contained

Manual Extraction

If you prefer manual creation:

1. 1. Create INLINECODE79
2. Use template from INLINECODE80
3. Follow Agent Skills spec:

- YAML frontmatter with name and description - Name must match folder name - No README.md inside skill folder

Extraction Detection Triggers

Watch for these signals that a learning should become a skill:

In conversation:

• - "Save this as a skill"
• "I keep running into this"
• "This would be useful for other projects"
• "Remember this pattern"

In learning entries:

• - Multiple See Also links (recurring issue)
• High priority + resolved status
• Category: best_practice with broad applicability
• User feedback praising the solution

Skill Quality Gates

Before extraction, verify:

• - [ ] Solution is tested and working
• [ ] Description is clear without original context
• [ ] Code examples are self-contained
• [ ] No project-specific hardcoded values
• [ ] Follows skill naming conventions (lowercase, hyphens)

Multi-Agent Support

This skill works across different AI coding agents with agent-specific activation.

Claude Code

Activation: Hooks (UserPromptSubmit, PostToolUse)
Setup: .claude/settings.json with hook configuration
Detection: Automatic via hook scripts

Codex CLI

Activation: Hooks (same pattern as Claude Code)
Setup: .codex/settings.json with hook configuration
Detection: Automatic via hook scripts

GitHub Copilot

Activation: Manual (no hook support)
Setup: Add to .github/copilot-instructions.md:

CODEBLOCK19

Detection: Manual review at session end

OpenClaw

Activation: Workspace injection + inter-agent messaging
Setup: See "OpenClaw Setup" section above
Detection: Via session tools and workspace files

Agent-Agnostic Guidance

Regardless of agent, apply self-improvement when you:

1. 1. Discover something non-obvious - solution wasn't immediate
2. Correct yourself - initial approach was wrong
3. Learn project conventions - discovered undocumented patterns
4. Hit unexpected errors - especially if diagnosis was difficult
5. Find better approaches - improved on your original solution

Copilot Chat Integration

For Copilot users, add this to your prompts when relevant:

After completing this task, evaluate if any learnings should be logged to .learnings/ using the self-improvement skill format.

Or use quick prompts:

• - "Log this to learnings"
• "Create a skill from this solution"
• "Check .learnings/ for related issues"