​

Self-Improvement Skill

​

Quick Reference

​

OpenClaw Setup (Recommended)

​

Installation

clawdhub install self-improving-agent

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

​

Workspace Structure

~/.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

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

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

​

Promotion Targets

​

Inter-Session Communication

• 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

​

Optional: Enable Hook

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

# Enable it
openclaw hooks enable self-improvement

​

Generic Setup (Other Agents)

mkdir -p .learnings

​

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

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

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

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

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

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

• TYPE: LRN (learning), ERR (error), FEAT (feature)
• YYYYMMDD: Current date
• XXX: Sequential number or random 3 chars (e.g., 001, A7B)

​

Resolving Entries

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

### Resolution
- **Resolved**: 2025-01-16T09:00:00Z
- **Commit/PR**: abc123 or #42
- **Notes**: Brief description of what was done

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

​

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

Project uses pnpm workspaces. Attempted npm install but failed. Lock file is pnpm-lock.yaml. Must use pnpm install.

## Build & Dependencies
- Package manager: pnpm (not npm) - use `pnpm install`

When modifying API endpoints, must regenerate TypeScript client. Forgetting this causes type mismatches at runtime.

## After API Changes
1. Regenerate client: `pnpm run generate:api`
2. Check for type errors: `pnpm tsc --noEmit`

​

Recurring Pattern Detection

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

​

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)

• Recurrence-Count >= 3
• Seen across at least 2 distinct tasks
• Occurred within a 30-day window

• CLAUDE.md
• AGENTS.md
• .github/copilot-instructions.md
• SOUL.md / TOOLS.md for OpenClaw workspace-level guidance when applicable

​

Periodic Review

​

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

• “No, that’s not right…”
• “Actually, it should be…”
• “You’re wrong about…”
• “That’s outdated…”

• “Can you also…”
• “I wish you could…”
• “Is there a way to…”
• “Why can’t you…”

• User provides information you didn’t know
• Documentation you referenced is outdated
• API behavior differs from your understanding

• Command returns non-zero exit code
• Exception or stack trace
• Unexpected output or behavior
• Timeout or connection failure

​

Priority Guidelines

​

Area Tags

​

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

.learnings/

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

​

Hook Integration

​

Quick Setup (Claude Code / Codex)

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

​

Full Setup (With Error Detection)

{
  "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"
      }]
    }]
  }
}

​

Available Hook Scripts

​

Automatic Skill Extraction

​

Skill Extraction Criteria

​

Extraction Workflow

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

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

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

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

​

Skill Quality Gates

• 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

​

Claude Code

​

Codex CLI

​

GitHub Copilot

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

​

OpenClaw

​

Agent-Agnostic Guidance

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

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

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