How self-improving skills turn corrections into lasting rules

A self-improving skill is a packaged capability, such as a Claude Code SKILL.md folder, that turns user corrections, test failures and scores into written rules the model loads in later sessions. Without one, a coding session that ran the wrong test command on Monday runs it again on Tuesday, because in Claude Code each session begins with a fresh context window. With one, the correction becomes a line in a memory file, and the next session reads that line before it starts work.

What is a self-improving skill

A self-improving skill is a skill that runs a feedback loop and writes what it learns to persistent memory, with no change to model weights. Anthropic describes skills as folders of instructions and scripts with a SKILL.md file whose YAML frontmatter carries a name and a description.

The research lineage is older than the file format. Shinn et al.’s Reflexion reinforces language agents “not by updating weights, but instead through linguistic feedback,” storing reflections in an episodic memory buffer for later trials. A self-improving skill packages that idea into three parts:

• A trigger: The skill activates after a correction, a failed check or an explicit “record” action.
• A writer: The skill turns the event into a short, general rule and writes it to a file.
• A loader: The runtime reads that file at the start of the next session or task.

Anything that must hold even when the model disagrees belongs in enforced configuration instead. Claude Code’s docs state that CLAUDE.md and auto memory are context, not enforced configuration, and that a PreToolUse hook is the way to block an action outright.

How a self-improving skill works

Five components make up a working skill: the loop itself, the signals that feed it, the files that store results, the categories of lessons and the pruning that keeps memory small.

The feedback loop from mistake to stored rule

Reflexion formalizes the loop as three models: an Actor produces a trajectory, an Evaluator scores it, and a Self-Reflection model turns the trajectory and score into a summary stored in memory (NeurIPS 2023 paper). With that loop, Shinn et al. reported 91% pass@1 on HumanEval against 80% for GPT-4 (Reflexion).

A file-based skill runs the same loop in five steps:

1. Mistake. A test fails, a command errors or a user writes “no, use X.”
2. Reflect. The model writes a diagnosis: what happened, why, and what should have happened. ACE’s Reflector prompt asks for error_identification, root_cause_analysis, correct_approach and key_insight fields (Zhang et al., ACE).
3. Generalize. The model generalizes the diagnosis into a rule that applies beyond this one case. Zhao et al.’s ExpeL compares failed and successful trajectories and applies ADD, EDIT, UPVOTE or DOWNVOTE to an existing insight set.
4. Write. The model writes the rule to a file. In ACE, a Curator produces compact delta entries that “lightweight, non-LLM logic” merges into the existing context (ACE v1).
5. Load. Claude Code reads the file in the next session, loading CLAUDE.md files at launch and the first 200 lines or 25KB of MEMORY.md at the start of every conversation.

Make step 4 plain code wherever possible. A model that rewrites the whole memory file on each update can erase details it was supposed to keep, which the pruning section below covers.

How success and failure signals are captured

Signals fall into four groups, and each one sets a different bar for what gets written:

• User corrections: Claude Code’s auto memory consists of notes Claude writes from corrections and preferences, and Claude skips anything it can derive from the codebase or that CLAUDE.md already says.
• Tests and execution results: With no ground-truth labels, ReAct plus ACE improved 14.8% over the ReAct baseline on AppWorld by using signals such as code execution success or failure.
• Scores and counters: Each ACE playbook bullet carries counters for how often it was marked helpful or harmful (ACE repository), so a rule’s track record travels with it.
• Explicit record actions: The self-learning-claude project loads patterns at task start, records success when an approach works and records failure when it goes wrong. The skill-loop MCP server’s skill_loop_log tool records each run as success, failure or partial.

Some projects also log outcomes passively. The self-improving-skills repository uses a PostToolUse hook, skill-outcome-observer.sh, that writes every skill outcome to ~/.claude/debug/skill-outcomes.jsonl.

What triggers a write matters more than what gets observed, and the self-learning-skills project promotes a session to a skill only when three conditions hold: a passing check, a named failure pattern and at least one ruled-out dead end. A later paper argues that agents writing memory from self-assessed binary pass/fail signals can store causally wrong diagnoses. Require a verifiable signal, such as a passing test, before any lesson becomes a rule.

Where learned knowledge lives

Learned rules live in plain files; the runtime uses each file’s location to determine who sees the rule and when it loads:

Persistence differs by file. Claude Code’s auto memory is machine-local: all worktrees of one git repository share one directory, nothing syncs across machines, and memory files are excluded from the transcript cleanup sweep, so they stay until someone edits or deletes them.

Repositories that already use AGENTS.md can keep it as the single source. A CLAUDE.md containing @AGENTS.md imports it, and the docs say this never makes Claude read AGENTS.md twice. Put team-wide lessons in the committed project CLAUDE.md, personal ones in CLAUDE.local.md, and leave auto memory for machine-specific notes.

Categories of learned patterns

The self-learning-claude playbook sorts patterns into pitfall, strategy, domain, endpoint and code, and ACE bullets hold “a reusable strategy, domain concept, or common failure mode” (ACE v1). The table below maps five categories to sample entries. Two samples come from published projects; the other three are illustrations written for this article:

Tag every entry with its category when it is written. Pruning and review both get easier when a reviewer can filter for corrections or meta-rules alone.

Keeping memory lean with tiers and pruning

Every always-loaded line costs tokens and attention in every session, and Claude Code’s docs warn that files over 200 lines may reduce adherence. Community skills manage this with tiers. The ClawHub Self-Improving skill keeps HOT entries in memory.md (always loaded), WARM entries in projects/ and domains/ (loaded on context match) and COLD entries in archive/ (loaded on explicit query).

Its movement rules are explicit:

• Promotion: A pattern used 3x in 7 days moves to HOT.
• Demotion: A pattern unused for 30 days moves to WARM.
• Archive: A pattern unused for 90 days moves to COLD, and the skill never deletes without asking.

Rewriting memory wholesale is the main hazard. ACE’s authors call it context collapse: on AppWorld, a context of 18,282 tokens scoring 66.7 collapsed at the next step to 122 tokens and scored 57.1, below the 63.7 baseline with no adaptation (ACE paper). ACE avoids this with itemized delta updates and a de-duplication step that compares bullets by semantic embeddings.

Contradictions need a named resolution path, because the docs say CLAUDE.md content carries no guarantee of strict compliance when instructions are vague or conflicting. Tools handle this differently:

• Flag and propose: Claude Code’s /doctor prompt-audit reports outdated or conflicting instructions and proposes edits, and nothing changes until the user asks Claude to apply them (memory docs).
• Vote down: ExpeL lets the model DOWNVOTE an insight it disagrees with (ExpeL).
• Keep both: Mem0’s v3 open-source algorithm is ADD-only; when information changes, the new fact is stored alongside the old one and retrieval handles ranking.

Set a hard line cap on the always-loaded tier and demote on disuse. When two rules conflict, have the skill flag both for a person instead of picking a winner on its own.

A worked example in Claude Code

The skills documentation (page last modified November 2026) lists Claude Code’s personal skills path as ~/.claude/skills/<skill-name>/SKILL.md and project skills path as .claude/skills/<skill-name>/SKILL.md. Personal skills load in every project on that machine; project skills load in that repository, and committing them shares them with the team.

The steps below install a small skill that writes learned rules to the project CLAUDE.md. The skill and the session are an illustration, not a recorded run:

1. Create the folder: mkdir -p ~/.claude/skills/learn-from-corrections.
2. Save SKILL.md in that folder with the content shown below.
3. Run /skills to confirm it is listed. If ~/.claude/skills did not exist when the session started, run /reload-skills first.
4. Invoke it with /learn-from-corrections, or let Claude load it when the description matches the task.
5. In the next session, run /context and check that CLAUDE.md appears under Memory files.

Only description is recommended in the frontmatter; name defaults to the directory name (skills docs). Step 5 follows Anthropic’s guidance to keep CLAUDE.md under 200 lines.

Before (illustration): Claude runs npm test to check a change. The run hangs because the integration suite needs a local database that is not running. The user writes: “Use npm run test:unit for quick checks.”

The skill’s reflection output reads:

The rule written to CLAUDE.md, after approval:

After (illustration): In the next session, Claude reads CLAUDE.md at launch and runs npm run test:unit first. A project-root CLAUDE.md also survives compaction, because Claude re-reads it from disk after /compact, so the rule holds through long sessions. If the rule must never be broken, move it into a PreToolUse hook that blocks npm test until the container is up.

Key features and capabilities

File-based learning has five properties that separate it from training:

• Cross-session persistence: CLAUDE.md rules sit on disk and load at launch, so a lesson from one session shapes the next without anyone repeating it.
• Human-readable rules: Auto memory and CLAUDE.md are plain markdown that a person can read, edit or delete through /memory.
• Git versioning: Project skills and project CLAUDE.md files commit with the code. skill-loop writes skill amendments on a new git branch and tests them against recent failure cases before a pull request.
• Portability across projects and tools: Anthropic reports that more than 70 platforms, including ChatGPT, Cursor, GitHub Copilot and VS Code, have integrated Agent Skills since the standard was published in December 2025 (Anthropic). Cursor also loads skills from .claude/skills/ for compatibility.
• No weight updates: ACE defines context adaptation as “modifying inputs with instructions, strategies, or evidence, rather than weight updates” (ACE), so any rule can be reverted by editing a line.

Risks and guardrails

Shao et al. found that self-evolving agents “misevolve”: an agent without memory triggered virtually no risks in baseline tests, while an agent with memory still showed malicious or high-risk behaviors in a significant portion of scenarios, even with explicit safety prompts placed before the memory module (Your Agent May Misevolve, ICLR 2026). A lesson written once loads every session, so a wrong one compounds.

Each failure mode below has one mitigation taken from published guidance or shipping projects:

• Overfitted lesson from a single case: Require recurrence before promotion. The alirezarezvani self-improving-agent skill flags a pattern only after it recurs 2 to 3 times, then writes it to CLAUDE.md after approval through /si:promote.
• Treating memory as law: Frame stored lessons as references. Shao et al. reported that prompts stating memory is “for reference” reduced risky behaviors, while noting this addresses symptoms rather than the root cause.
• Self-reinforcing contamination: Block automatic re-ingestion. The OWASP Top 10 for Agentic Applications 2026 says to prevent an agent’s own generated outputs from flowing back into trusted memory.
• Prompt injection persisted into memory: Gate writes on provenance. Anthropic notes that an injection landing in CLAUDE.md, product memory or agent state directories is reloaded each time the agent starts, and MINJA poisoned agent memory through query-only interactions.
• Stale rules: Expire unverified entries. OWASP’s mitigation text says to decay or expire unverified memory to limit poison persistence.
• A skill edit that makes results worse: Keep a rollback path. self-improving-skills returns IMPROVED, NO CHANGE or DEGRADED from /skill-evaluate, and /skill-rollback restores the previous version.
• Malicious third-party skill: Audit before installing. Snyk’s ToxicSkills audit of 3,984 skills from ClawHub and skills.sh found 76 confirmed malicious payloads, and Anthropic recommends installing skills only from trusted sources and auditing less-trusted ones, including bundled scripts.

Start with a review gate on every write. Version control and rollback only help if a person can see what changed.

How to measure whether it works

The most direct published evidence for skill libraries comes from Wang et al.’s SAGE, Skill Augmented GRPO for self-Evolution (arXiv 2512.17102). On AppWorld’s Test Normal split, the SAGE-trained skill-library model generated 59% fewer tokens and took 26% fewer interaction steps than a GRPO-trained baseline without a skill library, and scenario goal completion rose from 51.8 to 60.7 (paper tables).

The baseline determines the headline. An SFT-initialized GRPO control in the same paper used 1,284 tokens on average against SAGE’s 1,475, so the 59% figure holds only against the plain GRPO row (PDF).

SAGE is also RL-trained, so its numbers describe a trained skill library, not a markdown file. The paper’s ablation is the closest analog to “skill on versus skill off”: SAGE with skills used 1,475 tokens and scored 60.7 SGC, and without skills used 1,937 tokens and scored 54.8.

Track three metrics on your own work:

• Repeat-error rate: The share of tasks where a previously diagnosed failure reappears. An SSRN paper defines this as Error Recurrence Rate (ERR). Tag each failure with a diagnosis code so recurrences can be counted.
• Task success across repeated runs: τ-bench’s pass^k measures whether all k trials succeed. Its best gpt-4o function-calling agent averaged over 60% task success, but pass^8 dropped below 25% (τ-bench).
• Tokens and steps per task: These are the units SAGE and ACE report. ACE cut adaptation latency 82.3% and rollouts 75.1% against GEPA in offline AppWorld adaptation (ACE v1).

Run a fixed task set with the skill disabled, then enabled, on the same model version. Vary task order too: PATH-Bench found that different task paths over an identical task set can change the relative ranking of agents. Keep the skill only if the repeat-error rate falls without task success dropping.

How self-improving skills fit in

Teams can compare four places to put learned behavior by cost, persistence and risk: a static rules file, a self-updating memory skill, an external memory server over MCP, or a skill library trained with RL. The same idea also runs inside an AI employee who keeps a team’s skills and memory in one workspace.

Prompt and file based learning vs fine-tuning and RL

Context files change behavior without touching weights, and the published cost gap is wide. The Training-Free GRPO authors report using 100 data points at roughly $18, against fine-tuned 32B systems that “typically require thousands of training examples and incur costs exceeding $10,000” (author-reported). AWS guidance says to prioritize prompt engineering and RAG before model customization.

Hosted fine-tuning is also shrinking as an option. OpenAI’s deprecations page says it notified developers on May 7, 2026 of changes to its self-serve fine-tuning platform, and sets Jan 6, 2027 as the date active customers can no longer create new fine-tuning jobs.

SAGE shows where training still wins: on Qwen2.5-32B-Instruct, a prompting-only skill library reached 19.6 scenario goal completion, while SFT on Claude 3.5 Sonnet V2 expert data followed by SAGE reached 60.7 (paper). The authors conclude that prompt-based skill libraries are hard to implement consistently on open models. Start with file-based skills on a hosted frontier model, and consider RL only when the team owns the weights, has expert trajectories and can grade every outcome automatically.

Self-improving skills inside an AI employee

Viktor is the AI employee who lives in Slack and Microsoft Teams, connects to 9,800+ tools, and does the work. He keeps workspace memory of the team’s context, decisions and preferences across conversations, and he follows and improves skills: written procedures the team can browse, edit and share, and run by typing “/” in the chat composer. That shared, improving context is the core of what an AI employee is: one hire for the whole company, not a separate memory file per person.

He also learns by watching: when someone screen-records a job once, with narration, he turns it into a written skill that anyone can open and correct. If the job repeats, he proposes a scheduled task that stays paused until someone approves it.

The guardrails from the risks section apply to him as product settings: Viktor is an AI employee who waits for approval before he changes an account, and installing a skill always needs approval, as do joining channels and changing integration access. According to Viktor’s security page, money moves, code pushes and customer emails wait for explicit approval. Approval cards appear in Slack or Microsoft Teams, admins can set any tool to “needs approval” or “forbidden,” and each workspace is isolated, so skills, memory, files and connections never cross to another customer.

His integrations mostly connect through one-click OAuth, and new teams can also start in the web app at app.viktor.com. Engineering teams can hand work to him from Claude Code or Cursor through his MCP server. Hand him one recurring report, correct the first skill he writes, and check that the correction holds the following week. Start free with up to $100 in credits, no credit card →

For a company-wide rollout with security review: Plan a governed rollout with the Viktor team →

What’s next for self-improving skills

Three shifts are already visible in shipping products and published proposals:

• Shared skill marketplaces with review: Claude Team and Enterprise organizations can set publishing to “Requires review,” where an owner approves each skill and every update, and users stay on the approved version until the update is approved (Claude Help Center). Anthropic’s help center says skills, plugins and connectors move to one Plugins page, and that the organization-level Skills setting will be renamed to Plugins on November 30 (help article).
• Team-level memory: GitHub’s Copilot Memory, in public preview since January 2026, scopes memories to a repository, validates them against the current code before use and expires them after 28 days. Claude Managed Agents create an immutable memory version on every change, which gives an audit trail and point-in-time recovery.
• Standardized evaluation signals: No shared standard exists yet. Anthropic donated Agent Skills to the Agentic AI Foundation, and a roadmap covering versioned releases, a formal proposal process and security guidance has been proposed. Benchmarks such as LifelongAgentBench measure sequential learning across database, operating-system and knowledge-graph tasks.

Teams adopting self-improving skills now should build their own review gate and evaluation set rather than wait for a standard.

FAQ

Does a self-improving skill require fine-tuning or reinforcement learning?

No, a self-improving skill stores lessons as text that the model reads at the start of a session, so the weights never change. RL-trained skill libraries such as SAGE are a separate approach that needs GPU training and graded outcomes.

How is it different from a double-check prompt or a static rules file?

With a double-check prompt, the model re-verifies within one session but retains no lesson afterward. A static rules file persists but changes only when a person edits it. A self-improving skill writes new rules itself from corrections and test results, which is why it needs a review gate that the other two do not.

What happens when the skill learns a wrong lesson?

The wrong rule loads every session until someone removes it. Catch it with human approval before each write, keep memory files in git, and use a rollback command such as /skill-rollback in the self-improving-skills project when results degrade.

How do you tell whether the skill is improving results?

Compare the same task set with the skill off and on, using one model version. Count recurrences of previously diagnosed errors, task success across repeated runs, and tokens and steps per task.

How do you install one in Claude Code?

Put a folder containing SKILL.md in ~/.claude/skills/ for personal use or .claude/skills/ in the repository for the team. Run /skills to confirm it loaded, then invoke it with /skill-name.

How do you keep memory from going stale?

Cap the always-loaded tier, demote entries that go unused, and expire unverified ones. Run /doctor prompt-audit in Claude Code to flag outdated or conflicting instructions, and review CLAUDE.md and .claude/rules/ on a schedule.

Start with one recurring job you want off your team’s plate, and let the skills improve where everyone can read them. Hire your first AI employee, free with up to $100 in credits and no credit card →