self-improving-agent · jdrhyne — Claude Code skill: what it does, how to install
self-improving-agent keeps a small journal in .learnings/ with failures, user corrections and missing-capability requests, then reads it back before big jobs.
MIT ★ 239 updated 2026-08-30
npx skills add jdrhyne/agent-skills --skill self-improving-agent -a claude-codeWhat self-improving-agent does
The skill keeps a short journal next to your code. Entries land in .learnings/LEARNINGS.md, .learnings/ERRORS.md and .learnings/FEATURE_REQUESTS.md, and the folder is created the first time it is needed. Each entry is a markdown block: an id such as LRN-YYYYMMDD-XXX, a priority, a status and an area (frontend, backend, infra, tests, docs or config), then Summary, Details and Suggested Action.
Repeated patterns get linked through See Also, and the status moves on once an issue is closed or turned into a rule. Before a big job in familiar territory the skill suggests reading .learnings/ first. A fix that holds up outside one project can be promoted into a skill of its own, with a note left behind saying where the rule now lives. Not every failure earns a line: the skill asks for durable lessons rather than noise.
Write access stops at .learnings. Tokens, private keys and personal data are off limits, your own guidance files stay untouched unless you ask for a promotion, and nothing gets marked resolved before the fix was checked. Entries sit in the working tree, so .learnings/ will either be committed or listed in .gitignore.
What it helps with
- Record why a command failed so the next run starts from the answer
- Store a user correction to a project convention
- Track a capability the agent asked for but does not have
- Link recurring failures into one chain of entries
- Re-read past lessons before touching a familiar area
Example prompts for the agent
- The build broke again on the same error. Write the diagnosis into
.learnings/ERRORS.md. - That's wrong — we run migrations with
make migrate, notalembic upgrade. Save that as a learning. - Read
.learnings/before you refactor the billing module.
How to install self-improving-agent
1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill self-improving-agent -a claude-code2Manually: put the files in place
~/.claude/skills/self-improving-agent/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/self-improving-agent/
1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill self-improving-agent -a codex2Manually: put the files in place
.agents/skills/self-improving-agent/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill self-improving-agent -a cursor2Manually: put the files in place
.cursor/skills/self-improving-agent/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jdrhyne/agent-skills clawdbot/self-improving-agent/SKILL.md2Manually: put the files in place
.github/skills/self-improving-agent/SKILL.md1Skills CLI (Vercel)
npx skills add jdrhyne/agent-skills --skill self-improving-agent -a gemini-cli2Platform CLI
gemini skills install https://github.com/jdrhyne/agent-skills --path clawdbot/self-improving-agentManually: put the files in place
.devin/skills/self-improving-agent/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about self-improving-agent
How do I install self-improving-agent in Claude Code?
Run npx skills add jdrhyne/agent-skills --skill self-improving-agent -a claude-code. The skill file lands at ~/.claude/skills/self-improving-agent/SKILL.md.
What does self-improving-agent do?
It writes notes about failures, corrections and missing features into .learnings/, links related entries, and points the agent back at that journal before larger tasks.
Will it edit my project's guidance files?
Only when you explicitly ask for a learning to be promoted into shared guidance. Until then the notes stay inside .learnings/.
Source text
SKILL.md · MIT
---
name: self-improving-agent
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."
permissions:
- file_write: "Appends learning, error, and feature-request notes inside the local .learnings directory."
---
# Self-Improvement Skill
Capture non-obvious lessons, failures, and feature requests in a small local knowledge base so the same mistakes are less likely to repeat.
## When to Use
- A command, tool, or integration fails in a way worth remembering
- The user corrects an assumption or teaches a project-specific convention
- You discover a better repeatable workflow
- The user asks for a missing capability that should be tracked
- You are starting work in an area with known prior learnings
## Storage
Keep entries in a local `.learnings/` directory:
- `.learnings/LEARNINGS.md`
- `.learnings/ERRORS.md`
- `.learnings/FEATURE_REQUESTS.md`
Create the directory on first use if it does not exist.
## Record Types
### Learning
Use for corrections, conventions, and better practices.
```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 learning
### Details
What happened and what is now known to be correct
### Suggested Action
Specific follow-up or rule
### Metadata
- Source: conversation | error | user_feedback
- Related Files: path/to/file.ext
- Tags: tag1, tag2
- See Also: LRN-20250110-001
```
### Error
Use for reproducible failures or flaky workflows.
```markdown
## [ERR-YYYYMMDD-XXX] tool_or_workflow
**Logged**: ISO-8601 timestamp
**Priority**: high
**Status**: pending
**Area**: frontend | backend | infra | tests | docs | config
### Summary
Short failure description
### Error
Exact error text or symptoms
### Context
- Operation attempted
- Inputs or environment details
### Suggested Fix
Likely next step
```
### Feature Request
Use for missing capabilities the user wants tracked.
```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
### User Context
Why it matters
### Suggested Implementation
Likely extension point or implementation direction
```
## Workflow
1. Log the learning as soon as the context is clear.
2. Link related entries with `See Also` when patterns repeat.
3. Update status when the issue is resolved, rejected, or turned into a reusable rule.
4. Review `.learnings/` before major work in a familiar problem area.
## Promotion Rules
If a learning becomes broadly reusable:
- distill it into a concise rule
- move it into the repo's shared guidance only if the user explicitly wants that promotion
- update the learning entry to note where the rule now lives
Recurring patterns are good candidates for extraction into a dedicated skill when the solution is verified, portable, and no longer project-specific.
## Safety Boundaries
- Do not modify user-owned policy or guidance files unless the user explicitly asked for that promotion.
- Do not log secrets, access tokens, private keys, or sensitive personal data in `.learnings/`.
- Do not treat every failure as worth logging; prefer durable lessons over noise.
- Do not mark an entry resolved unless the fix was actually verified.
© jdrhyne · MIT · jdrhyne/agent-skills
Similar skills
All skills for Agent setup: memory, context, orchestration →self-improving-agent by other authors comes first.