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#

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_practiceSimilar 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 (bot workspace)Tool gotchasPromote to TOOLS.md (bot workspace)Behavioral patternsPromote to SOUL.md (bot workspace)

Setup#

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

bash

mkdir -p .learnings

Copy templates from assets/ or create files with headers.

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)

---

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

### 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 (bot)TOOLS.mdTool capabilities, usage patterns, integration gotchas (bot)

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)

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/

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

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

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

Bot#

Activation: Workspace injection + inter-agent messaging Setup: Configure workspace path in ~/.bot/bot.json Detection: Via session tools and workspace files ( AGENTS.md, SOUL.md, TOOLS.md)

Bot uses a workspace-based model with injected prompt files. See references/bot-integration.md for detailed setup.

Agent-Agnostic Guidance#

Regardless of agent, apply self-improvement when you:

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#

For Copilot users, add this to your prompts when relevant:

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

Or use quick prompts:

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

Bot Integration#

Bot uses workspace-based prompt injection with specialized files for different concerns.

Workspace Structure#

text

~/bot/                    # Default workspace (configurable)
├── AGENTS.md              # Multi-agent workflows, delegation patterns
├── SOUL.md                # Behavioral guidelines, communication style
├── TOOLS.md               # Tool capabilities, MCP integrations
└── sessions/              # Session transcripts (auto-managed)

Bot Promotion Targets#

Learning TypePromote ToExampleAgent coordinationAGENTS.md"Delegate file searches to explore agent"Communication styleSOUL.md"Be concise, avoid disclaimers"Tool gotchasTOOLS.md"MCP server X requires auth refresh"Project factsCLAUDE.mdStandard project conventions

Inter-Agent Learning#

Bot supports session-based communication:

• sessions_list - See active/recent sessions
• sessions_history - Read transcript from another session
• sessions_send - Send message to another session

Hybrid Setup (Claude Code + Bot)#

When using both:

1. Keep .learnings/ for project-specific learnings
2. Use bot workspace files for cross-project patterns
3. Sync high-value learnings to both systems

See references/bot-integration.md for complete setup, promotion formats, and troubleshooting.