Skill v1.0.1
currentAutomated scan100/10011 files
version: "1.0.1" name: self-improvement description: "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. For CI-only/headless learning capture, use self-improvement-ci."
Self-Improvement Skill
Install
gh skill install pskoett/pskoett-skills self-improvement
For CI-only execution, use:
gh skill install pskoett/pskoett-skills self-improvement-ci
Fallback using the Agent Skills CLI:
npx skills add pskoett/pskoett-skills/skills/self-improvementnpx skills add pskoett/pskoett-skills/skills/self-improvement-ci
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 | |
| Simplify/Harden recurring patterns | Log/update .learnings/LEARNINGS.md with Source: simplify-and-harden and a stable Pattern-Key | |
| Similar to existing entry | Link with **See Also**, consider priority bump | |
| Broadly applicable learning | Promote to CLAUDE.md, AGENTS.md, and/or .github/copilot-instructions.md | |
| Workflow improvements | Promote to AGENTS.md (openclaw workspace) | |
| Tool gotchas | Promote to TOOLS.md (openclaw workspace) | |
| Behavioral patterns | Promote to SOUL.md (openclaw workspace) |
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### SummaryOne-line description of what was learned### DetailsFull context: what happened, what was wrong, what's correct### Suggested ActionSpecific 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
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### SummaryBrief description of what failed### Error
Actual error message or output
### Context- Command/operation attempted- Input or parameters used- Environment details if relevant### Suggested FixIf 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 CapabilityWhat the user wanted to do### User ContextWhy they needed it, what problem they're solving### Complexity Estimatesimple | medium | complex### Suggested ImplementationHow 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:
- Change
**Status**: pending→**Status**: resolved - 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 onwont_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
| Target | What Belongs There | |
|---|---|---|
CLAUDE.md | Project facts, conventions, gotchas for all Claude interactions | |
AGENTS.md | Agent-specific workflows, tool usage patterns, automation rules | |
.github/copilot-instructions.md | Project context and conventions for GitHub Copilot | |
SOUL.md | Behavioral guidelines, communication style, principles (openclaw) | |
TOOLS.md | Tool capabilities, usage patterns, integration gotchas (openclaw) |
How to Promote
- Distill the learning into a concise rule or fact
- Add to appropriate section in target file (create file if needed)
- 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. Attemptednpm installbut failed.Lock file ispnpm-lock.yaml. Must usepnpm 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 Changes1.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:
- Search first:
grep -r "keyword" .learnings/ - Link entries: Add
**See Also**: ERR-20250110-001in Metadata - Bump priority if issue keeps recurring
- 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
Use this workflow to ingest recurring patterns from the simplify-and-harden skill and turn them into durable prompt guidance.
Ingestion Workflow
- Read
simplify_and_harden.learning_loop.candidatesfrom the task summary. - For each candidate, use
pattern_keyas the stable dedupe key. - Search
.learnings/LEARNINGS.mdfor an existing entry with that key:
grep -n "Pattern-Key: <pattern_key>" .learnings/LEARNINGS.md
- If found:
- Increment
Recurrence-Count - Update
Last-Seen - Add
See Alsolinks to related entries/tasks
- If not found:
- Create a new
LRN-...entry - Set
Source: simplify-and-harden - Set
Pattern-Key,Recurrence-Count: 1, andFirst-Seen/Last-Seen
Promotion Rule (System Prompt Feedback)
Promote recurring patterns into agent context/system prompt files when all are true:
Recurrence-Count >= 3- Seen across at least 2 distinct tasks
- Occurred within a 30-day window
Promotion targets:
CLAUDE.mdAGENTS.md.github/copilot-instructions.mdSOUL.md/TOOLS.mdfor openclaw workspace-level guidance when applicable
Write promoted rules as short prevention rules (what to do before/while coding), not long incident write-ups.
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 itemsgrep -h "Status\*\*: pending" .learnings/*.md | wc -l# List pending high-priority itemsgrep -B5 "Priority\*\*: high" .learnings/*.md | grep "^## \["# Find learnings for a specific areagrep -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
- Log immediately - context is freshest right after the issue
- Be specific - future agents need to understand quickly
- Include reproduction steps - especially for errors
- Link related files - makes fixes easier
- Suggest concrete fixes - not just "investigate"
- Use consistent categories - enables filtering
- Promote aggressively - if in doubt, add to CLAUDE.md or .github/copilot-instructions.md
- 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
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:
{"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)
{"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
| Script | Hook Type | Purpose | |
|---|---|---|---|
scripts/activator.sh | UserPromptSubmit | Reminds to evaluate learnings after tasks | |
scripts/error-detector.sh | PostToolUse (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:
| Criterion | Description | |
|---|---|---|
| Recurring | Has See Also links to 2+ similar issues | |
| Verified | Status is resolved with working fix | |
| Non-obvious | Required actual debugging/investigation to discover | |
| Broadly applicable | Not project-specific; useful across codebases | |
| User-flagged | User says "save this as a skill" or similar |
Extraction Workflow
- Identify candidate: Learning meets extraction criteria
- 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 ``
- Customize SKILL.md: Fill in template with learning content
- Update learning: Set status to
promoted_to_skill, addSkill-Path - Verify: Read skill in fresh session to ensure it's self-contained
Manual Extraction
If you prefer manual creation:
- Create
skills/<skill-name>/SKILL.md - Use template from
assets/SKILL-TEMPLATE.md - Follow Agent Skills spec:
- YAML frontmatter with
nameanddescription - 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 Alsolinks (recurring issue) - High priority + resolved status
- Category:
best_practicewith 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:
## Self-ImprovementAfter solving non-obvious issues, consider logging to `.learnings/`:1.Use format from self-improvement skill2.Link related entries with See Also3.Promote high-value learnings to skillsAsk in chat: "Should I log this as a learning?"
Detection: Manual review at session end
OpenClaw (Optional)
OpenClaw-specific setup, promotion targets, and hybrid usage details are kept in references/openclaw-integration.md so this main skill stays focused on the core self-improvement workflow for coding agents.
Agent-Agnostic Guidance
Regardless of agent, apply self-improvement when you:
- Discover something non-obvious - solution wasn't immediate
- Correct yourself - initial approach was wrong
- Learn project conventions - discovered undocumented patterns
- Hit unexpected errors - especially if diagnosis was difficult
- 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"