Skip to content
Get packs

Guide · Agent skill

How to use the Self-Improving Agent skill: install, trigger and tips

Updated · written with AI from the project's own documentation and checked against our catalogue data

The self-improving-agent skill helps an AI coding agent review what Claude Code has automatically noted about your project, decide which notes are reliable enough to become permanent rules, and remove stale or duplicate notes. This guide is for developers who use Claude Code on a long-running project and want its memory kept tidy. By the end you will know how to install the skill, trigger it with plain requests, and use it safely.

Self-Improving Agentalirezarezvani/claude-skills · MIT

Quick start

  1. 1Check your Claude Code version. Confirm you run Claude Code v2.1.32 or later so auto-memory is supported.
  2. 2Install the skill. Either install the plugin from the marketplace or unzip the downloaded ZIP into ~/.claude/skills/ or a project's .claude/skills/ folder.
  3. 3Ask what the agent has learned. Request a review of what has been saved about the project so you can see the current notes.
  4. 4Run a memory review. Use /si:memory-review to find promotion candidates, stale entries and entries to consolidate.
  5. 5Promote approved patterns. Use /si:promote to move checked patterns into CLAUDE.md or .claude/rules/.
  6. 6Prune and check health. Ask for a cleanup or run /si:memory-status to see line counts and recommendations.

What an agent skill is and what this one does

An agent skill is a folder containing a SKILL.md file that tells an AI agent when and how to perform a task. This skill is built around Claude Code's auto-memory, which records project patterns, debugging insights and your preferences in MEMORY.md. Auto-memory captures what the agent learns but does not judge it, so the skill adds a curation layer.

It can review MEMORY.md and its topic files for learnings worth keeping, promote proven ones into CLAUDE.md or .claude/rules/, record a correction as a lesson that persists across sessions, prune stale or duplicate entries, and turn a recurring fix into a reusable skill.

  • Find promotion candidates: entries that recur across sessions
  • Flag stale entries that reference deleted files or old patterns
  • Consolidate related entries
  • Save explicit corrections so the agent stops repeating a mistake

How to install the skill

You can download the skill ZIP from this page and unzip it into ~/.claude/skills/ for all your projects, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

The source also lists a plugin route for Claude Code, which uses the marketplace commands below. OpenClaw and Codex CLI users have their own install commands.

  • Claude Code plugin: add the marketplace, then install the plugin
  • OpenClaw: install via ClawHub
  • Codex CLI: run the install script from the repository
/plugin marketplace add alirezarezvani/claude-skills /plugin install self-improving-agent@claude-code-skills

Requirements before you start

Full support requires Claude Code with auto-memory, version v2.1.32 or later. The skill also works with OpenClaw and Codex CLI, which read their own memory files (workspace/MEMORY.md and AGENTS.md respectively) in adapted form. On GitHub Copilot, promotion is manual only.

The skill runs scripts, so review them before installing. It does not use the network, according to the listing.

  • Claude Code v2.1.32 or later for full support
  • Plugin install via the Claude Code marketplace, ClawHub for OpenClaw, or the Codex CLI install script

Trigger the skill with natural requests

You do not need to memorise commands to use the skill. The description says it activates when you ask what the agent has learned or saved about the project, which memories should become permanent rules, to remember a lesson or stop repeating a mistake, or to clean up, audit or check memory health.

The plugin also exposes slash commands. Use them when you want a specific action.

  • /si:memory-review: analyze MEMORY.md for promotion candidates, stale entries and consolidation opportunities
  • /si:promote: move a pattern from MEMORY.md into CLAUDE.md or .claude/rules/
  • /si:extract: turn a proven pattern into a standalone skill
  • /si:memory-status: memory health dashboard with line counts, topic files and recommendations
  • /si:remember: explicitly save important knowledge to auto-memory

Examples of requests to try

Plain requests work well. Be specific about the project and the outcome you want, and review what the agent proposes before approving changes.

Promotion is a change to future behaviour, so approve only the notes you have checked.

  • "What have you learned about this project so far?"
  • "Which of my memories should become permanent rules?"
  • "Remember that we use pnpm, not npm, and stop suggesting npm."
  • "Audit my memory and tell me which entries are stale or duplicated."
  • "Check the health of the memory files for this repo."

Understand where memory and rules live

Knowing the file layout helps you judge what the agent proposes. Project rules go in ./CLAUDE.md and are loaded in full every session. Auto-memory goes in MEMORY.md under your project's memory folder, where only the first 200 lines are loaded, and overflow goes into topic files loaded on demand. Scoped rules in .claude/rules/ load only when matching files are open.

A promoted rule moves from a note to an instruction. For example, "I noticed this project uses pnpm" is background context, while "Use pnpm, not npm" is an enforced rule.

  • ./CLAUDE.md: your project rules, full file every session
  • ~/.claude/CLAUDE.md: your global preferences
  • ~/.claude/projects/<path>/memory/MEMORY.md: auto-written project learnings
  • .claude/rules/*.md: scoped rules that load when matching files open
--- paths: - "src/api/**/*.test.ts" - "tests/api/**/*" --- - Use supertest for API endpoint testing - Mock external services with msw - Always test error responses, not just happy paths

Safety notes: scripts, memory edits and review

The skill runs scripts, so read them before you install it and only install from sources you trust. The listing says it does not use the network.

Promoting or pruning entries changes how the agent behaves in future sessions. A careless review can turn a wrong note into a permanent rule, so check every promotion against the actual code. Do not use the skill on projects where the agent's memory should not be edited.

The error-capture hook appends entries to auto-memory when a Bash command fails, at roughly 30 tokens per detected error and zero on success, so review what it records.

  • Read scripts before installing
  • Review each promotion and prune before approving
  • Keep a copy of CLAUDE.md before large edits, since you can then compare changes

What people use it for

  • Turning a recurring package-manager preference into a permanent CLAUDE.md rule
  • Scoping API testing conventions to src/api and tests/api files using .claude/rules/
  • Saving a correction so the agent stops repeating the same mistake in later sessions
  • Trimming MEMORY.md when stale entries crowd out new learnings
  • Turning a fix you keep re-explaining into a standalone reusable skill with /si:extract

Frequently asked questions

Is the Self-Improving Agent skill free?

The skill is published under the MIT licence, as stated on its listing. The source does not mention prices, so check the repository for any terms that apply to you.

How do I install the self-improving-agent skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for all projects or into a project's .claude/skills/ folder. In the Claude apps, upload it under Settings → Capabilities → Skills. The Claude Code plugin route uses the marketplace commands shown in the installation section.

What do I need to run it?

Full support requires Claude Code with auto-memory, version v2.1.32 or later. The skill runs scripts and, according to the listing, does not use the network.

Does it work with GitHub Copilot?

It works with Copilot only for manual promotion. The source says Copilot users must promote entries by hand.

Will it change my code or rules without asking?

Promotion and pruning change future agent behaviour, so review each proposed change before approving it. Use /si:promote only for patterns you have verified.

How is it different from Claude Code's auto-memory?

Auto-memory records what Claude learns in MEMORY.md but has no judgment about which notes are permanent. This skill reviews those notes, promotes proven ones into CLAUDE.md or .claude/rules/, and removes stale or duplicate entries.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you work with Claude Code on a long-running project, want its memory kept tidy, or keep correcting the same mistakes across sessions. Skip it if you do not want the agent's memory edited, or if you use GitHub Copilot and need automatic promotion, since that platform only supports manual promotion.

Download the skill