Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jdrhyne/agent-skills --skill self-improving-agent -a claude-code
Open on GitHub

What 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, not alembic 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-code

2Manually: put the files in place

~/.claude/skills/self-improving-agent/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/self-improving-agent/

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.

self-improving-agent Alireza Rezvani self-improving-agent — a Claude Code skill that curates the agent's auto-memory into project rules. Reviews MEMORY.md, promotes proven patterns into CLAUDE.md or .claude/rules/, and turns recurring fixes into skills. CX Codex +1 1,078installs self-improving-agent zhaono1 self-improving-agent turns workflow failures, corrections, and workarounds into auditable rules for agents. Prevents blind instruction rewrites by requiring executable proof first. CX Codex +1 35,900installs self-improving-agent pskoett The self-improving-agent skill keeps a markdown log of agent errors, corrections and findings so useful fixes survive between sessions. CX Codex +1 408installs self-improving-agent borghei self-improving-agent — a skill for Claude Code, Codex, and Cursor that curates long-term agent memory. Converts repeated task outcomes into reviewed project rules. CX Codex +1 244installs self-improving-agent Grail-Computer self-improving-agent teaches an agent to diagnose friction, update project guardrails in AGENTS.md, and turn repeated multi-step workflows into standalone skills. CX Codex +1 520installs self-improvement pskoett self-improvement keeps your corrections, failed commands and feature asks in markdown files so the agent can turn repeated lessons into project rules. CX Codex +1 2,100installs memory-curate basicmachines-co memory-curate curates the Basic Memory knowledge graph. Connects orphan notes, cleans up tag taxonomies, detects duplicates, and generates hub notes. CX Codex +1 1,500installs ce-compound-refresh EveryInc ce-compound-refresh maintains backwards compatibility for scheduled learnings refreshes. Forwards calls directly to the ce-compound skill. CX Codex +1 3,500installs planning-with-files OthmanAdi planning-with-files keeps a multi-step task plan in three markdown files and pulls the agent back to them every turn, so long sessions hold their context. CX Codex +1 ★ 28,179repo stars replay-learnings Rohit Ghumare The replay-learnings skill searches project memory and similar sessions for lessons tied to a new task. Run it before coding to bring earlier corrections into view. CX Codex +1 ★ 2,966repo stars Docmancer docmancer Docmancer — an MCP server for Claude Code, Codex and other agents: indexes memory, rules and session history from local directories and consolidates them into a single Markdown store. CX Codex +1 ★ 133repo stars

From the same set27

The whole set →
skill-sync skill-sync is a Claude Code skill that keeps local skills in sync with a shared GitHub repository by listing skills, installing updates, and submitting local changes through pull requests. CX Codex +1 ★ 239repo stars clawdbot-release-check clawdbot-release-check watches GitHub for new OpenClaw releases and pings you once per version. Can run on a cron schedule and send the notice to Telegram. CX Codex +1 ★ 239repo stars Zendesk Work with Zendesk tickets and users through the API, or export queue data on request. Configure the required environment variables before connecting. CX Codex +1 ★ 239repo stars knowledge-graph The knowledge-graph skill keeps durable facts about people, companies, and projects in a workspace graph. Use it to carry useful context between sessions and look it up without reopening long transcripts. CX Codex +1 ★ 239repo stars planner planner structures complex projects into sprints and atomic tasks with acceptance criteria, preparing ready-to-run plans for subagents. CX Codex +1 ★ 239repo stars parallel-task Parses a markdown plan into sprint tasks and hands unblocked ones to parallel subagents. Fires on the explicit /parallel-task command. CX Codex +1 ★ 239repo stars elegant-reports elegant-reports turns markdown into a clean PDF report — executive brief, analysis write-up or slide-style deck — with bundled templates and themes. CX Codex +1 ★ 239repo stars gsc gsc enables read-only Google Search Console analysis in Claude Code across properties, search metrics, URL inspection, and sitemaps. CX Codex +1 ★ 239repo stars

Project sponsors

Companies that keep this analytics open