Self Improving Agent

Captures learnings, errors, and corrections to enable continuous improvement. Use when: (1) A command or operation fails unexpectedly, (2) User corrects you, (3) User requests a capability that doesn't exist, (4) An external API or tool fails, (5) Knowledge was outdated or incorrect, (6) A better approach is discovered for a recurring task.

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:

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. Do not log secrets, tokens, private keys, or environment variables.

Quick Reference

Situation	Action
Command/operation fails	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
Knowledge was outdated	Log to .learnings/LEARNINGS.md with category knowledge_gap
Found better approach	Log to .learnings/LEARNINGS.md with category best_practice
Broadly applicable learning	Promote to CLAUDE.md, AGENTS.md, or copilot instructions

Logging Format

Learning Entry

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

---

Error Entry

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

### Suggested Fix
If identifiable, what might resolve this

---

ID Generation

Format: TYPE-YYYYMMDD-XXX

• TYPE: LRN, ERR, FEAT
• YYYYMMDD: Current date
• XXX: Sequential number (001, 002, etc.)

Promotion Targets

Learning Type	Promote To
Behavioral patterns	SOUL.md
Workflow improvements	AGENTS.md
Tool gotchas	TOOLS.md
Project facts	CLAUDE.md

Periodic Review

Review .learnings/ at natural breakpoints:

• Before starting a new major task
• After completing a feature
• Weekly during active development

bash

# Count pending items
grep -h "Status**: pending" .learnings/*.md | wc -l

# List high-priority items
grep -B5 "Priority**: high" .learnings/*.md | grep "^## \["

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. Promote aggressively — if in doubt, add to project memory