Skills
skills/clawdbot/skills/self-improvement

self-improvement

SKILL.md

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 .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 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 and/or AGENTS.md

Setup

Create .learnings/ directory in project root if it doesn't exist:

mkdir -p .learnings

Copy templates from assets/ or create files with headers.

Logging Format

Learning Entry

Append to .learnings/LEARNINGS.md:

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

---

Error Entry

Append to .learnings/ERRORS.md:

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


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

Append to .learnings/FEATURE_REQUESTS.md:

## [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:
### 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 or AGENTS.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
CLAUDE.md Project facts, conventions, gotchas for all Claude interactions
AGENTS.md Agent-specific workflows, tool usage patterns, automation rules

How to Promote

  1. Distill the learning into a concise rule or fact
  2. Add to appropriate section in target file
  3. Update original entry:
    • Change **Status**: pending → **Status**: promoted
    • Add **Promoted**: CLAUDE.md or **Promoted**: AGENTS.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):

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

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

# 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

Priority When to Use
critical Blocks core functionality, data loss risk, security issue
high 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
frontend UI, components, client-side code
backend 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. 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
  8. Review regularly - stale learnings lose value

Gitignore Options

Keep learnings local (per-developer):

.learnings/

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

Hybrid (track templates, ignore entries):

.learnings/*.md
!.learnings/.gitkeep
Weekly Installs
5
Repository
clawdbot/skills
Installed on
windsurf3
opencode3
codex3
clawdbot2
trae2
cursor2