Some skills solve narrow problems. Others change how agents learn. The self-improving agent skill is firmly in the second category — which is likely why it has 244,000 downloads on ClawHub, more than any other skill in the ecosystem.
This post breaks down what the skill actually does, why it resonates with developers, and how to wire it into your setup today.
The Problem It Solves
Every AI agent has the same structural weakness: it forgets. You spend 20 minutes debugging why Stripe’s webhook signature check keeps failing. Claude figures it out. You fix the bug. The session ends — and next time, Claude hits the exact same mistake.
This is not a bug in the model. It’s an architectural constraint. Claude doesn’t have persistent memory across sessions by default. Every conversation starts fresh.
The self-improving agent skill is the simplest possible fix: when something goes wrong, write it down. When a user corrects an assumption, write it down. When a better approach surfaces, write it down. The agent builds a file-based memory that survives session restarts.
How It Works
The skill maintains three log files in a .learnings/ directory at the root of your project:
- LEARNINGS.md — corrections, knowledge gaps, best practices discovered in the field
- ERRORS.md — command failures, API misbehaviors, exceptions with context
- FEATURE_REQUESTS.md — capabilities users asked for that didn’t exist
The skill activates automatically when specific patterns appear in a conversation. You corrected Claude? That triggers a LEARNINGS.md entry. A bash command returned a non-zero exit code? That triggers an ERRORS.md entry. The detection is pattern-based and runs without manual prompting.
What a Learning Entry Looks Like
## [LRN-20260318-001] correction
**Logged**: 2026-03-18T10:15:00Z
**Priority**: high
**Status**: pending
**Area**: backend
### Summary
Stripe webhook verification fails when JSON middleware parses the body before signature check
### Details
When using Express with app.use(express.json()) globally, the raw body is consumed
before the webhook handler receives it. Stripe computes the signature against the raw
bytes, not the parsed JSON object. Re-serializing the parsed object produces different
bytes, causing signature verification to always fail.
### Suggested Action
Use express.raw({ type: 'application/json' }) specifically for the webhook route,
placed BEFORE the global json middleware in route ordering.
### Metadata
- Source: user_feedback
- Related Files: src/webhooks/stripe.ts
- Tags: stripe, webhooks, express, middlewareCompare that to a comment in the code or a note in a README. The structured format means any future agent session — or any teammate — can search these logs, find relevant entries, and apply the fix without repeating the investigation.
The Cascade That Makes It Valuable
Individual log entries are useful. But the skill’s real value comes from what happens next: promotion.
When a learning proves broadly applicable — not just a one-time fix but a pattern that recurs across contexts — the skill guides you to promote it to permanent project memory:
CLAUDE.md— project facts and conventions every Claude interaction should knowAGENTS.md— workflow improvements for multi-agent setups.github/copilot-instructions.md— context for GitHub CopilotSOUL.md/TOOLS.md— for OpenClaw workspace-level behavioral patterns
The result is a ratchet: every session makes the agent slightly better. Errors get caught earlier. Corrections don’t need to be repeated. Over weeks, a project’s Claude setup accumulates a dense, project-specific knowledge base that no amount of prompt engineering alone can replicate.
Installation Walkthrough
There are two installation paths depending on your setup.
Via ClawHub (Recommended)
clawdhub install self-improving-agentClawHub handles the directory structure and drops the skill into the right location for your agent framework. After installation, the skill activates automatically based on its description field — no configuration required.
Manual Installation
git clone https://github.com/peterskoett/self-improving-agent.git ~/.openclaw/skills/self-improving-agentThen create the log directory:
mkdir -p ~/.openclaw/workspace/.learningsCreate three empty files: LEARNINGS.md, ERRORS.md, and FEATURE_REQUESTS.md. The skill includes templates in its assets/ folder.
For OpenClaw Users
If you’re running AgentSkillExchange skills through OpenClaw, the workspace injection model handles context loading automatically. Add to your openclaw.json:
"skills": {
"entries": {
"self-improving-agent": {
"enabled": true
}
}
}The skill is available in OpenClaw’s skills directory and loads at session start alongside other workspace context files.
Hook Integration: Automatic Error Detection
Manual logging works, but the skill also supports hook-based automation for Claude Code and Codex. Hooks let you trigger logging automatically when commands fail, without relying on the agent to remember to log.
Create or update .claude/settings.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"
}]
}]
}
}The activator.sh hook injects a reminder at the start of each prompt (roughly 50–100 tokens overhead). The error-detector.sh hook fires after every bash tool call and flags non-zero exit codes for logging. Both are opt-in and available in the skill’s scripts/ directory.
Why It Went Viral: The Recurring Mistake Problem
The download count — 244K — is high for a skill that doesn’t do anything visually impressive. It doesn’t generate images, write emails, or automate CI pipelines. It logs text to markdown files.
The reason it spread: developers recognized a pattern they’d all experienced. The same mistakes, in every project, in every session. “Don’t forget to null-check this.” “Use pnpm, not npm.” “The API rate-limits at 100 requests/minute, not 1000.” All of these live in someone’s head, or in a comment buried three files deep, where the agent will never see them.
The self-improving agent skill makes that knowledge computable. It gives agents a way to learn from mistakes and carry that learning forward — which is, arguably, the thing that distinguishes a useful coding partner from an expensive autocomplete.
Patterns Worth Watching For
Thariq’s viral thread on how Anthropic uses skills internally identified the gotchas section as “the highest-signal content” in any skill. The self-improving agent skill is, in many ways, a systematic machine for building gotchas sections — it captures real failures as they happen, exactly the raw material that turns a generic SKILL.md into one that actually prevents mistakes.
The skill also implements the progressive disclosure principle Thariq recommended: the SKILL.md stays lightweight, detailed logging formats live in references/, and hook scripts live in scripts/. Context is loaded on-demand, not dumped into every session.
Recurring Pattern Detection
One feature that gets overlooked: the skill tracks recurring patterns. When you log something similar to an existing entry, it prompts you to link them with a See Also reference and bump the priority. Entries with enough recurrences and breadth get flagged for promotion to permanent project files.
The detection criteria:
- Recurrence count ≥ 3
- Seen across at least 2 distinct tasks
- Occurred within a 30-day window
When all three are true, the learning gets promoted as a short prevention rule — not a verbose incident write-up, but a concise directive that fits in a system prompt or CLAUDE.md without burning context.
Using It Across Multiple Agents
One of the design choices that broadened adoption: the skill is agent-agnostic. The core mechanism — log to markdown files, review before major tasks — works with Claude Code, Codex, GitHub Copilot, and OpenClaw without modification. Hook-based automation is available where hooks exist; manual review works everywhere else.
For teams running multiple agents across the same codebase, the .learnings/ directory can be checked into version control, turning individual agent learnings into shared team knowledge. Alternatively, per-developer .gitignore entries keep logs local if the content is too context-specific to share.
Getting Started
If you run into an issue in your next Claude session that takes more than 10 minutes to debug, log it. If Claude gets corrected, log the correction. Start there. The skill doesn’t require full configuration to be useful — a single well-written error entry, reviewed before the next session, can save the next hour of debugging.
The full skill is available on AgentSkillExchange. For more on writing high-quality skills, see our post on agent skill best practices from Anthropic’s Thariq.