1---
2name: self-improvement
3description: "Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects Claude ('No, that's wrong...', 'Actually...'), (3) User requests a capability that doesn't exist, (4) An external API or tool fails, (5) Claude realizes its knowledge is outdated or incorrect, (6) A better approach is discovered for a recurring task. Also review learnings before major tasks."
4metadata:
5---
6 
7# Self-Improvement Skill
8 
9Log 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.
10 
11## First-Use Initialisation
12 
13Before logging anything, ensure the `.learnings/` directory and files exist in the project or workspace root. If any are missing, create them:
14 
15```bash
16mkdir -p .learnings
17[ -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
18[ -f .learnings/ERRORS.md ] || printf "# Errors\n\nCommand failures and integration errors.\n\n---\n" > .learnings/ERRORS.md
19[ -f .learnings/FEATURE_REQUESTS.md ] || printf "# Feature Requests\n\nCapabilities requested by the user.\n\n---\n" > .learnings/FEATURE_REQUESTS.md
20```
21 
22Never overwrite existing files. This is a no-op if `.learnings/` is already initialised.
23 
24Do 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.
25 
26If you want automatic reminders or setup assistance, use the opt-in hook workflow described in [Hook Integration](#hook-integration).
27 
28## Quick Reference
29 
30| Situation | Action |
31|-----------|--------|
32| Command/operation fails | Log to `.learnings/ERRORS.md` |
33| User corrects you | Log to `.learnings/LEARNINGS.md` with category `correction` |
34| User wants missing feature | Log to `.learnings/FEATURE_REQUESTS.md` |
35| API/external tool fails | Log to `.learnings/ERRORS.md` with integration details |
36| Knowledge was outdated | Log to `.learnings/LEARNINGS.md` with category `knowledge_gap` |
37| Found better approach | Log to `.learnings/LEARNINGS.md` with category `best_practice` |
38| Simplify/Harden recurring patterns | Log/update `.learnings/LEARNINGS.md` with `Source: simplify-and-harden` and a stable `Pattern-Key` |
39| Similar to existing entry | Link with `**See Also**`, consider priority bump |
40| Broadly applicable learning | Promote to `CLAUDE.md`, `AGENTS.md`, and/or `.github/copilot-instructions.md` |
41| Workflow improvements | Promote to `AGENTS.md` (OpenClaw workspace) |
42| Tool gotchas | Promote to `TOOLS.md` (OpenClaw workspace) |
43| Behavioral patterns | Promote to `SOUL.md` (OpenClaw workspace) |
44 
45## OpenClaw Setup (Recommended)
46 
47OpenClaw is the primary platform for this skill. It uses workspace-based prompt injection with automatic skill loading.
48 
49### Installation
50 
51**Via ClawdHub (recommended):**
52```bash
53clawdhub install self-improving-agent
54```
55 
56**Manual:**
57```bash
58git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agent
59```
60 
61Remade for openclaw from original repo : https://github.com/pskoett/pskoett-ai-skills - https://github.com/pskoett/pskoett-ai-skills/tree/main/skills/self-improvement
62 
63### Workspace Structure
64 
65OpenClaw injects these files into every session:
66 
67```
68~/.openclaw/workspace/
69├── AGENTS.md          # Multi-agent workflows, delegation patterns
70├── SOUL.md            # Behavioral guidelines, personality, principles
71├── TOOLS.md           # Tool capabilities, integration gotchas
72├── MEMORY.md          # Long-term memory (main session only)
73├── memory/            # Daily memory files
74│   └── YYYY-MM-DD.md
75└── .learnings/        # This skill's log files
76    ├── LEARNINGS.md
77    ├── ERRORS.md
78    └── FEATURE_REQUESTS.md
79```
80 
81### Create Learning Files
82 
83```bash
84mkdir -p ~/.openclaw/workspace/.learnings
85```
86 
87Then create the log files (or copy from `assets/`):
88- `LEARNINGS.md` — corrections, knowledge gaps, best practices
89- `ERRORS.md` — command failures, exceptions
90- `FEATURE_REQUESTS.md` — user-requested capabilities
91 
92### Promotion Targets
93 
94When learnings prove broadly applicable, promote them to workspace files:
95 
96| Learning Type | Promote To | Example |
97|---------------|------------|---------|
98| Behavioral patterns | `SOUL.md` | "Be concise, avoid disclaimers" |
99| Workflow improvements | `AGENTS.md` | "Spawn sub-agents for long tasks" |
100| Tool gotchas | `TOOLS.md` | "Git push needs auth configured first" |
101 
102### Inter-Session Communication
103 
104OpenClaw provides tools to share learnings across sessions:
105 
106- **sessions_list** — View active/recent sessions
107- **sessions_history** — Read another session's transcript  
108- **sessions_send** — Send a learning to another session
109- **sessions_spawn** — Spawn a sub-agent for background work
110 
111Use 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.
112 
113### Optional: Enable Hook
114 
115For automatic reminders at session start:
116 
117```bash
118# Copy hook to OpenClaw hooks directory
119cp -r hooks/openclaw ~/.openclaw/hooks/self-improvement
120 
121# Enable it
122openclaw hooks enable self-improvement
123```
124 
125See `references/openclaw-integration.md` for complete details.
126 
127---
128 
129## Generic Setup (Other Agents)
130 
131For Claude Code, Codex, Copilot, or other agents, create `.learnings/` in the project or workspace root:
132 
133```bash
134mkdir -p .learnings
135```
136 
137Create the files inline using the headers shown above. Avoid reading templates from the current repo or workspace unless you explicitly trust that path.
138 
139### 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)
140 
141#### Self-Improvement Workflow
142 
143When errors or corrections occur:
1441. Log to `.learnings/ERRORS.md`, `LEARNINGS.md`, or `FEATURE_REQUESTS.md`
1452. Review and promote broadly applicable learnings to:
146   - `CLAUDE.md` - project facts and conventions
147   - `AGENTS.md` - workflows and automation
148   - `.github/copilot-instructions.md` - Copilot context
149 
150## Logging Format
151 
152### Learning Entry
153 
154Append to `.learnings/LEARNINGS.md`:
155 
156```markdown
157## [LRN-YYYYMMDD-XXX] category
158 
159**Logged**: ISO-8601 timestamp
160**Priority**: low | medium | high | critical
161**Status**: pending
162**Area**: frontend | backend | infra | tests | docs | config
163 
164### Summary
165One-line description of what was learned
166 
167### Details
168Full context: what happened, what was wrong, what's correct
169 
170### Suggested Action
171Specific fix or improvement to make
172 
173### Metadata
174- Source: conversation | error | user_feedback
175- Related Files: path/to/file.ext
176- Tags: tag1, tag2
177- See Also: LRN-20250110-001 (if related to existing entry)
178- Pattern-Key: simplify.dead_code | harden.input_validation (optional, for recurring-pattern tracking)
179- Recurrence-Count: 1 (optional)
180- First-Seen: 2025-01-15 (optional)
181- Last-Seen: 2025-01-15 (optional)
182 
183---
184```
185 
186### Error Entry
187 
188Append to `.learnings/ERRORS.md`:
189 
190```markdown
191## [ERR-YYYYMMDD-XXX] skill_or_command_name
192 
193**Logged**: ISO-8601 timestamp
194**Priority**: high
195**Status**: pending
196**Area**: frontend | backend | infra | tests | docs | config
197 
198### Summary
199Brief description of what failed
200 
201### Error
202```
203Actual error message or output
204```
205 
206### Context
207- Command/operation attempted
208- Input or parameters used
209- Environment details if relevant
210- Summary or redacted excerpt of relevant output (avoid full transcripts and secret-bearing data by default)
211 
212### Suggested Fix
213If identifiable, what might resolve this
214 
215### Metadata
216- Reproducible: yes | no | unknown
217- Related Files: path/to/file.ext
218- See Also: ERR-20250110-001 (if recurring)
219 
220---
221```
222 
223### Feature Request Entry
224 
225Append to `.learnings/FEATURE_REQUESTS.md`:
226 
227```markdown
228## [FEAT-YYYYMMDD-XXX] capability_name
229 
230**Logged**: ISO-8601 timestamp
231**Priority**: medium
232**Status**: pending
233**Area**: frontend | backend | infra | tests | docs | config
234 
235### Requested Capability
236What the user wanted to do
237 
238### User Context
239Why they needed it, what problem they're solving
240 
241### Complexity Estimate
242simple | medium | complex
243 
244### Suggested Implementation
245How this could be built, what it might extend
246 
247### Metadata
248- Frequency: first_time | recurring
249- Related Features: existing_feature_name
250 
251---
252```
253 
254## ID Generation
255 
256Format: `TYPE-YYYYMMDD-XXX`
257- TYPE: `LRN` (learning), `ERR` (error), `FEAT` (feature)
258- YYYYMMDD: Current date
259- XXX: Sequential number or random 3 chars (e.g., `001`, `A7B`)
260 
261Examples: `LRN-20250115-001`, `ERR-20250115-A3F`, `FEAT-20250115-002`
262 
263## Resolving Entries
264 
265When an issue is fixed, update the entry:
266 
2671. Change `**Status**: pending` → `**Status**: resolved`
2682. Add resolution block after Metadata:
269 
270```markdown
271### Resolution
272- **Resolved**: 2025-01-16T09:00:00Z
273- **Commit/PR**: abc123 or #42
274- **Notes**: Brief description of what was done
275```
276 
277Other status values:
278- `in_progress` - Actively being worked on
279- `wont_fix` - Decided not to address (add reason in Resolution notes)
280- `promoted` - Elevated to CLAUDE.md, AGENTS.md, or .github/copilot-instructions.md
281 
282## Promoting to Project Memory
283 
284When a learning is broadly applicable (not a one-off fix), promote it to permanent project memory.
285 
286### When to Promote
287 
288- Learning applies across multiple files/features
289- Knowledge any contributor (human or AI) should know
290- Prevents recurring mistakes
291- Documents project-specific conventions
292 
293### Promotion Targets
294 
295| Target | What Belongs There |
296|--------|-------------------|
297| `CLAUDE.md` | Project facts, conventions, gotchas for all Claude interactions |
298| `AGENTS.md` | Agent-specific workflows, tool usage patterns, automation rules |
299| `.github/copilot-instructions.md` | Project context and conventions for GitHub Copilot |
300| `SOUL.md` | Behavioral guidelines, communication style, principles (OpenClaw workspace) |
301| `TOOLS.md` | Tool capabilities, usage patterns, integration gotchas (OpenClaw workspace) |
302 
303### How to Promote
304 
3051. **Distill** the learning into a concise rule or fact
3062. **Add** to appropriate section in target file (create file if needed)
3073. **Update** original entry:
308   - Change `**Status**: pending` → `**Status**: promoted`
309   - Add `**Promoted**: CLAUDE.md`, `AGENTS.md`, or `.github/copilot-instructions.md`
310 
311### Promotion Examples
312 
313**Learning** (verbose):
314> Project uses pnpm workspaces. Attempted `npm install` but failed. 
315> Lock file is `pnpm-lock.yaml`. Must use `pnpm install`.
316 
317**In CLAUDE.md** (concise):
318```markdown
319## Build & Dependencies
320- Package manager: pnpm (not npm) - use `pnpm install`
321```
322 
323**Learning** (verbose):
324> When modifying API endpoints, must regenerate TypeScript client.
325> Forgetting this causes type mismatches at runtime.
326 
327**In AGENTS.md** (actionable):
328```markdown
329## After API Changes
3301. Regenerate client: `pnpm run generate:api`
3312. Check for type errors: `pnpm tsc --noEmit`
332```
333 
334## Recurring Pattern Detection
335 
336If logging something similar to an existing entry:
337 
3381. **Search first**: `grep -r "keyword" .learnings/`
3392. **Link entries**: Add `**See Also**: ERR-20250110-001` in Metadata
3403. **Bump priority** if issue keeps recurring
3414. **Consider systemic fix**: Recurring issues often indicate:
342   - Missing documentation (→ promote to CLAUDE.md or .github/copilot-instructions.md)
343   - Missing automation (→ add to AGENTS.md)
344   - Architectural problem (→ create tech debt ticket)
345 
346## Simplify & Harden Feed
347 
348Use this workflow to ingest recurring patterns from the `simplify-and-harden`
349skill and turn them into durable prompt guidance.
350 
351### Ingestion Workflow
352 
3531. Read `simplify_and_harden.learning_loop.candidates` from the task summary.
3542. For each candidate, use `pattern_key` as the stable dedupe key.
3553. Search `.learnings/LEARNINGS.md` for an existing entry with that key:
356   - `grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md`
3574. If found:
358   - Increment `Recurrence-Count`
359   - Update `Last-Seen`
360   - Add `See Also` links to related entries/tasks
3615. If not found:
362   - Create a new `LRN-...` entry
363   - Set `Source: simplify-and-harden`
364   - Set `Pattern-Key`, `Recurrence-Count: 1`, and `First-Seen`/`Last-Seen`
365 
366### Promotion Rule (System Prompt Feedback)
367 
368Promote recurring patterns into agent context/system prompt files when all are true:
369 
370- `Recurrence-Count >= 3`
371- Seen across at least 2 distinct tasks
372- Occurred within a 30-day window
373 
374Promotion targets:
375- `CLAUDE.md`
376- `AGENTS.md`
377- `.github/copilot-instructions.md`
378- `SOUL.md` / `TOOLS.md` for OpenClaw workspace-level guidance when applicable
379 
380Write promoted rules as short prevention rules (what to do before/while coding),
381not long incident write-ups.
382 
383## Periodic Review
384 
385Review `.learnings/` at natural breakpoints:
386 
387### When to Review
388- Before starting a new major task
389- After completing a feature
390- When working in an area with past learnings
391- Weekly during active development
392 
393### Quick Status Check
394```bash
395# Count pending items
396grep -h "Status\*\*: pending" .learnings/*.md | wc -l
397 
398# List pending high-priority items
399grep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["
400 
401# Find learnings for a specific area
402grep -l "Area\*\*: backend" .learnings/*.md
403```
404 
405### Review Actions
406- Resolve fixed items
407- Promote applicable learnings
408- Link related entries
409- Escalate recurring issues
410 
411## Detection Triggers
412 
413Automatically log when you notice:
414 
415**Corrections** (→ learning with `correction` category):
416- "No, that's not right..."
417- "Actually, it should be..."
418- "You're wrong about..."
419- "That's outdated..."
420 
421**Feature Requests** (→ feature request):
422- "Can you also..."
423- "I wish you could..."
424- "Is there a way to..."
425- "Why can't you..."
426 
427**Knowledge Gaps** (→ learning with `knowledge_gap` category):
428- User provides information you didn't know
429- Documentation you referenced is outdated
430- API behavior differs from your understanding
431 
432**Errors** (→ error entry):
433- Command returns non-zero exit code
434- Exception or stack trace
435- Unexpected output or behavior
436- Timeout or connection failure
437 
438## Priority Guidelines
439 
440| Priority | When to Use |
441|----------|-------------|
442| `critical` | Blocks core functionality, data loss risk, security issue |
443| `high` | Significant impact, affects common workflows, recurring issue |
444| `medium` | Moderate impact, workaround exists |
445| `low` | Minor inconvenience, edge case, nice-to-have |
446 
447## Area Tags
448 
449Use to filter learnings by codebase region:
450 
451| Area | Scope |
452|------|-------|
453| `frontend` | UI, components, client-side code |
454| `backend` | API, services, server-side code |
455| `infra` | CI/CD, deployment, Docker, cloud |
456| `tests` | Test files, testing utilities, coverage |
457| `docs` | Documentation, comments, READMEs |
458| `config` | Configuration files, environment, settings |
459 
460## Best Practices
461 
4621. **Log immediately** - context is freshest right after the issue
4632. **Be specific** - future agents need to understand quickly
4643. **Include reproduction steps** - especially for errors
4654. **Link related files** - makes fixes easier
4665. **Suggest concrete fixes** - not just "investigate"
4676. **Use consistent categories** - enables filtering
4687. **Promote aggressively** - if in doubt, add to CLAUDE.md or .github/copilot-instructions.md
4698. **Review regularly** - stale learnings lose value
470 
471## Gitignore Options
472 
473**Keep learnings local** (per-developer):
474```gitignore
475.learnings/
476```
477 
478This repo uses that default to avoid committing sensitive or noisy local logs by accident.
479 
480**Track learnings in repo** (team-wide):
481Don't add to .gitignore - learnings become shared knowledge.
482 
483**Hybrid** (track templates, ignore entries):
484```gitignore
485.learnings/*.md
486!.learnings/.gitkeep
487```
488 
489## Hook Integration
490 
491Enable automatic reminders through agent hooks. This is **opt-in** - you must explicitly configure hooks.
492 
493### Quick Setup (Claude Code / Codex)
494 
495Create `.claude/settings.json` in your project:
496 
497```json
498{
499  "hooks": {
500    "UserPromptSubmit": [{
501      "matcher": "",
502      "hooks": [{
503        "type": "command",
504        "command": "./skills/self-improvement/scripts/activator.sh"
505      }]
506    }]
507  }
508}
509```
510 
511This injects a learning evaluation reminder after each prompt (~50-100 tokens overhead).
512 
513### Advanced Setup (With Error Detection)
514 
515```json
516{
517  "hooks": {
518    "UserPromptSubmit": [{
519      "matcher": "",
520      "hooks": [{
521        "type": "command",
522        "command": "./skills/self-improvement/scripts/activator.sh"
523      }]
524    }],
525    "PostToolUse": [{
526      "matcher": "Bash",
527      "hooks": [{
528        "type": "command",
529        "command": "./skills/self-improvement/scripts/error-detector.sh"
530      }]
531    }]
532  }
533}
534```
535 
536This 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.
537 
538### Available Hook Scripts
539 
540| Script | Hook Type | Purpose |
541|--------|-----------|---------|
542| `scripts/activator.sh` | UserPromptSubmit | Reminds to evaluate learnings after tasks |
543| `scripts/error-detector.sh` | PostToolUse (Bash) | Triggers on command errors |
544 
545See `references/hooks-setup.md` for detailed configuration and troubleshooting.
546 
547## Automatic Skill Extraction
548 
549When a learning is valuable enough to become a reusable skill, extract it using the provided helper.
550 
551### Skill Extraction Criteria
552 
553A learning qualifies for skill extraction when ANY of these apply:
554 
555| Criterion | Description |
556|-----------|-------------|
557| **Recurring** | Has `See Also` links to 2+ similar issues |
558| **Verified** | Status is `resolved` with working fix |
559| **Non-obvious** | Required actual debugging/investigation to discover |
560| **Broadly applicable** | Not project-specific; useful across codebases |
561| **User-flagged** | User says "save this as a skill" or similar |
562 
563### Extraction Workflow
564 
5651. **Identify candidate**: Learning meets extraction criteria
5662. **Run helper** (or create manually):
567   ```bash
568   ./skills/self-improvement/scripts/extract-skill.sh skill-name --dry-run
569   ./skills/self-improvement/scripts/extract-skill.sh skill-name
570   ```
5713. **Customize SKILL.md**: Fill in template with learning content
5724. **Update learning**: Set status to `promoted_to_skill`, add `Skill-Path`
5735. **Verify**: Read skill in fresh session to ensure it's self-contained
574 
575### Manual Extraction
576 
577If you prefer manual creation:
578 
5791. Create `skills/<skill-name>/SKILL.md`
5802. Use template from `assets/SKILL-TEMPLATE.md`
5813. Follow [Agent Skills spec](https://agentskills.io/specification):
582   - YAML frontmatter with `name` and `description`
583   - Name must match folder name
584   - No README.md inside skill folder
585 
586### Extraction Detection Triggers
587 
588Watch for these signals that a learning should become a skill:
589 
590**In conversation:**
591- "Save this as a skill"
592- "I keep running into this"
593- "This would be useful for other projects"
594- "Remember this pattern"
595 
596**In learning entries:**
597- Multiple `See Also` links (recurring issue)
598- High priority + resolved status
599- Category: `best_practice` with broad applicability
600- User feedback praising the solution
601 
602### Skill Quality Gates
603 
604Before extraction, verify:
605 
606- [ ] Solution is tested and working
607- [ ] Description is clear without original context
608- [ ] Code examples are self-contained
609- [ ] No project-specific hardcoded values
610- [ ] Follows skill naming conventions (lowercase, hyphens)
611 
612## Multi-Agent Support
613 
614This skill works across different AI coding agents with agent-specific activation.
615 
616### Claude Code
617 
618**Activation**: Hooks (UserPromptSubmit, PostToolUse)
619**Setup**: `.claude/settings.json` with hook configuration
620**Detection**: Automatic via hook scripts
621 
622### Codex CLI
623 
624**Activation**: Hooks (same pattern as Claude Code)
625**Setup**: `.codex/settings.json` with hook configuration
626**Detection**: Automatic via hook scripts
627 
628### GitHub Copilot
629 
630**Activation**: Manual (no hook support)
631**Setup**: Add to `.github/copilot-instructions.md`:
632 
633```markdown
634## Self-Improvement
635 
636After solving non-obvious issues, consider logging to `.learnings/`:
6371. Use format from self-improvement skill
6382. Link related entries with See Also
6393. Promote high-value learnings to skills
640 
641Ask in chat: "Should I log this as a learning?"
642```
643 
644**Detection**: Manual review at session end
645