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.

First-Use Initialisation#

Before logging anything, ensure the .learnings/ directory and files exist in the project or workspace root. If any are missing, create them:

bash

mkdir -p .learnings
[ -f .learnings/LEARNINGS.md ] || printf "# Learnings\n\nCorrections, insights, and knowledge gaps captured during development.\n\n**Categories**: correction | insight | knowledge_gap | best_practice\n\n---\n" > .learnings/LEARNINGS.md
[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md

Never overwrite existing files. This is a no-op if .learnings/ is already initialised.

Do not log secrets, tokens, private keys, environment variables, or full source/config files unless the user explicitly asks for that level of detail. Prefer short summaries or redacted excerpts over raw command output or full transcripts.

If you want automatic reminders or setup assistance, use the opt-in hook workflow described in Hook Integration.

Quick Reference#

SituationActionCommand/operation failsLog to .learnings/ERRORS.mdUser corrects youLog to .learnings/LEARNINGS.md with category correctionUser wants missing featureLog to .learnings/FEATURE_REQUESTS.mdAPI/external tool failsLog to .learnings/ERRORS.md with integration detailsKnowledge was outdatedLog to .learnings/LEARNINGS.md with category knowledge_gapFound better approachLog to .learnings/LEARNINGS.md with category best_practiceSimplify/Harden recurring patternsLog/update .learnings/LEARNINGS.md with Source: simplify-and-harden and a stable Pattern-KeySimilar to existing entryLink with **See Also**, consider priority bumpBroadly applicable learningPromote to CLAUDE.md, AGENTS.md, and/or .github/copilot-instructions.mdWorkflow improvementsPromote to AGENTS.md (OpenClaw workspace)Tool gotchasPromote to TOOLS.md (OpenClaw workspace)Behavioral patternsPromote 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):

bash

clawdhub install self-improving-agent

Manual:

bash

git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent

Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement

Workspace Structure#

OpenClaw injects these files into every session:

text

~/.openclaw/workspace/
├── AGENTS.md          # Multi-agent workflows, delegation patterns
├── SOUL.md            # Behavioral guidelines, personality, principles
├── TOOLS.md           # Tool capabilities, integration gotchas
├── MEMORY.md          # Long-term memory (main session only)
├── memory/            # Daily memory files
│   └── YYYY-MM-DD.md
└── .learnings/        # This skill's log files
    ├── LEARNINGS.md
    ├── ERRORS.md
    └── FEATURE_REQUESTS.md

Create Learning Files#

bash

mkdir -p ~/.openclaw/workspace/.learnings

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

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

Promotion Targets#

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

Learning TypePromote ToExampleBehavioral patternsSOUL.md"Be concise, avoid disclaimers"Workflow improvementsAGENTS.md"Spawn sub-agents for long tasks"Tool gotchasTOOLS.md"Git push needs auth configured first"

Inter-Session Communication#

OpenClaw provides tools to share learnings across sessions:

• sessions_list — View active/recent sessions
• sessions_history — Read another session's transcript
• sessions_send — Send a learning to another session
• sessions_spawn — Spawn a sub-agent for background work

Use these only in trusted environments and only when the user explicitly wants cross-session sharing. Prefer sending a short sanitized summary and relevant file paths, not raw transcripts, secrets, or full command output.

Optional: Enable Hook#

For automatic reminders at session start:

bash

# Copy hook to OpenClaw hooks directory
cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement

# Enable it
openclaw hooks enable self-improvement

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

---

Generic Setup (Other Agents)#

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

bash

mkdir -p .learnings

Create the files inline using the headers shown above. Avoid reading templates from the current repo or workspace unless you explicitly trust that path.

Add reference to agent files AGENTS.md, CLAUDE.md, or .github/copilot-instructions.md to remind yourself to log learnings. (this is an alternative to hook-based reminders)#

Self-Improvement Workflow

When errors or corrections occur:

1. Log to .learnings/ERRORS.md, LEARNINGS.md, or FEATURE_REQUESTS.md
2. Review and promote broadly applicable learnings to:
   • CLAUDE.md - project facts and conventions
   • AGENTS.md - workflows and automation
   • .github/copilot-instructions.md - Copilot context

Logging Format#

Learning Entry#

Append to .learnings/LEARNINGS.md:

markdown

## [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:

markdown

## [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

text

### Context
- Command/operation attempted
- Input or parameters used
- Environment details if relevant
- Summary or redacted excerpt of relevant output (avoid full transcripts and secret-bearing data by default)

### 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:

markdown

## [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:

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

markdown

### 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

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#

TargetWhat Belongs ThereCLAUDE.mdProject facts, conventions, gotchas for all Claude interactionsAGENTS.mdAgent-specific workflows, tool usage patterns, automation rules.github/copilot-instructions.mdProject context and conventions for GitHub CopilotSOUL.mdBehavioral guidelines, communication style, principles (OpenClaw workspace)TOOLS.mdTool capabilities, usage patterns, integration gotchas (OpenClaw workspace)

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

markdown

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

markdown

## 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:

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
• SOUL.md / TOOLS.md for OpenClaw workspace-level guidance when applicable

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#

bash

# 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#

PriorityWhen to UsecriticalBlocks core functionality, data loss risk, security issuehighSignificant impact, affects common workflows, recurring issuemediumModerate impact, workaround existslowMinor inconvenience, edge case, nice-to-have

Area Tags#

Use to filter learnings by codebase region:

AreaScopefrontendUI, components, client-side codebackendAPI, services, server-side codeinfraCI/CD, deployment, Docker, cloudtestsTest files, testing utilities, coveragedocsDocumentation, comments, READMEsconfigConfiguration 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):

gitignore

.learnings/

This repo uses that default to avoid committing sensitive or noisy local logs by accident.

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

Hybrid (track templates, ignore entries):

gitignore

.learnings/*.md
!.learnings/.gitkeep

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:

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }]
  }
}

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

Advanced Setup (With Error Detection)#

json

{
  "hooks": {
    "UserPromptSubmit": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/activator.sh"
      }]
    }],
    "PostToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "./skills/self-improvement/scripts/error-detector.sh"
      }]
    }]
  }
}

This is optional. The recommended default is activator-only setup; enable PostToolUse only if you are comfortable with hook scripts inspecting command output for error patterns.

Available Hook Scripts#

ScriptHook TypePurposescripts/activator.shUserPromptSubmitReminds to evaluate learnings after tasksscripts/error-detector.shPostToolUse (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:

CriterionDescriptionRecurringHas See Also links to 2+ similar issuesVerifiedStatus is resolved with working fixNon-obviousRequired actual debugging/investigation to discoverBroadly applicableNot project-specific; useful across codebasesUser-flaggedUser says "save this as a skill" or similar

Extraction Workflow#

1. Identify candidate: Learning meets extraction criteria

2. Run helper (or create manually): bash

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

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:

   • 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:

markdown

## Self-Improvement

After solving non-obvious issues, consider logging to `.learnings/`:
1. Use format from self-improvement skill
2. Link related entries with See Also
3. Promote high-value learnings to skills

Ask in chat: "Should I log this as a learning?"

Detection: Manual review at session end