self-improving-agent Skill: What It Does and How to Install It

Turns a failure or correction into a reviewed, tested change to your agent's behavior, instead of an automatic rewrite.

Installs: 35.4K; on skills.sh
Stars: 85; on GitHub
Files: 5; besides SKILL.md
Updated: Sep 2026; last repo commit

The SKILL.md has the agent end every run in one state: candidate, validated, applied, rejected, superseded or rolled back, no change, or open question. It captures a redacted summary with the apb command, runs an executable eval, and only then changes one named file such as a skill or instruction file. The default result is a candidate or no change, not an automatic rewrite.

It loads after a failure, a user correction, a repeated workaround or a validated success. It needs the apb command from the @codeharbor/agent-playbook package and Node.js 18 or newer. Claude Code is the only host with a failure hook, and you turn it on yourself with --hooks.

Good for

Developers who correct the same agent mistake more than once
Teams that review agent behavior changes like code
Builders who maintain their own agent skills

Install self-improving-agent

Claude Code

Copy this prompt.

Install the self-improving-agent skill in Claude Code. Run this command:

pnpm dlx @codeharbor/agent-playbook init

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js 18+, pnpm.

The skill's commands call apb, the short name of the agent-playbook command from the @codeharbor/agent-playbook package (Node.js 18 or newer). The README runs the package with pnpm dlx and does not document a global install, so check that apb runs in your terminal after installing. Pick one route. init installs the repo's skills for Claude Code, Codex, Gemini and DeepSeek Harness, and leaves Claude hooks off unless you add --hooks. --hooks adds two Claude Code hooks to ~/.claude/settings.json (see Permissions). The skills CLI and folder routes install only the skill, not the apb command.

From the project README. Source.

What's in the skill

When it loads

Use after a failure, user correction, repeated workflow problem, or validated success reveals a reusable lesson. Captures bounded redacted candidates, runs executable behavior evals, and separates validation from application in durable guidance.

Sections in SKILL.md

Use This Skill When
Required Outcome
Start Packet
Lifecycle
1. Capture the Signal
2. Assess Reusability
3. Validate
4. Validate, Apply, or Reject
5. Prove the Loop
Knowledge Export
Host Boundary
Done Checklist

Key facts

Author: zhaono1/agent-playbook (repo owner; the LICENSE names Agent Playbook Contributors)
License: MIT (LICENSE file and package.json)
Installs on skills.sh: 35,386 (Nov 2, 2026)
GitHub stars: 85 for the whole zhaono1/agent-playbook repo (Nov 2, 2026)
Last repo commit: Sep 15, 2026
What it includes: 6 files including SKILL.md: a README, 2 reference files and 2 eval files. The skill folder has no .py, .js or .sh files
Needs: The apb command from @codeharbor/agent-playbook, Node.js 18 or newer
Works in: Claude Code, Codex, Gemini and DeepSeek Harness (skill files); failure hook on Claude Code only

What it includes

State future behavior, a test scenario, evidence, one owner, write limits and proof.
If any item is unknown, the SKILL.md says to capture a candidate and stop before validation or application.
Read · Start packet
apb self-improve capture saves a redacted, deduplicated candidate.
Stores a minimal summary under ~/.agent-playbook/self-improvement/. The SKILL.md says not to copy transcripts, tool inputs, credentials or private paths.
Try: “Capture this correction as a candidate: verify the source before trusting cached state”
Runs code · Capture
apb behavior inbox and apb behavior owners rank candidates and suggest owners.
The SKILL.md treats owner suggestions as review candidates, not decisions.
Runs code · Assess
apb self-improve eval runs a JSON artifact of baseline and candidate scenarios.
Each scenario is a command array with expectations. Validation accepts only a passing CLI-generated result for the same candidate. Source: references/eval-artifact.md.
Runs code · Validate with an eval
apb behavior proposal writes a local Behavior Change Proposal.
Includes the intended change, eval proof, acceptance criteria, privacy boundary and rollback plan. It does not edit the owner or open a pull request.
Runs code · Proposal
Change exactly one durable owner, then record it with --decision apply.
Applies to the narrowest owner: a test or validator, a skill, project instructions, or a notebook. Needs a change reference such as a commit.
Runs code · Apply
apb self-improve export writes applied rules and open candidates as Markdown.
For Obsidian or another local notes folder.
Runs code · Export
apb conformance reports which local files and hooks are in place.
The SKILL.md says a proven file layout does not prove the host discovers or runs the skill.
Runs code · Host conformance

From the official docs

Permissions

Medium risk

The skill can run commands from eval files on your machine, and the --hooks option rewrites your Claude Code settings. Skip --hooks at first and read each eval file before you run it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

--hooks edits your Claude Code settings
Per packages/agent-playbook/src/cli.js, --hooks copies the agent-playbook CLI into an agent-playbook folder under your Claude directory, saves a one-time settings.json.bak, then rewrites ~/.claude/settings.json to add a SessionEnd hook (session-log) and a PostToolUseFailure hook with matcher * (self-improve), plus an agentPlaybook key. The hooks call node on that local copy, not apb from PATH. The README says session summaries and failure capture are redacted and bounded, and hooks stay off unless you pass --hooks. github.com
Eval artifacts run commands on your machine
The reference says an eval artifact starts local processes as your OS user, is not a sandbox and can read accessible files or use the network. Read an artifact before you run it and keep secrets out of it. github.com
It stores lessons on disk and can edit one owner file
Redacted candidates and results go under ~/.agent-playbook/self-improvement/ by default. After validation, the skill changes one durable owner such as a skill or instruction file, and the SKILL.md says not to rewrite repository rules or publish as a side effect of capture. github.com
pnpm dlx runs a package from npm
The install commands download and run @codeharbor/agent-playbook, which copies skills into your host folders. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	Fresh installs leave Claude hooks off; pass no --hooks to keep it manual.
Sign-in and keys	Candidate and eval state sit in ~/.agent-playbook/self-improvement/ by default; AGENT_PLAYBOOK_DATA_DIR or --data-dir moves it.
Scopes	Files the agent can read and edit ~/.agent-playbook/ (candidates and evals) ~/.claude/settings.json (only with --hooks)

Questions

What does self-improving-agent do?

It turns a failure, correction or repeated workaround into a small, tested change to your agent's behavior. The agent captures a redacted candidate, runs an eval, and records the change against one named file.

How do I install self-improving-agent?

Use the install box above. The installer routes also set up the other skills in the repo and the apb command the skill calls. The skills CLI and folder routes install only this skill.

Does it change my skills automatically?

No. The SKILL.md says the default result is a candidate or no change, not an automatic rewrite, and that it should never silently modify repository rules, publish packages or trigger external actions as a side effect of capture.

Does it work in Codex or the Claude app?

The README lists Claude Code, Codex, Gemini and DeepSeek Harness. Only Claude Code has a failure hook, which you enable with --hooks. The README does not document the Claude app, and the skill depends on a local command, so the install box has no Claude app tab.

Does it need an API key?

Neither the SKILL.md nor the README asks for one. It needs the apb command and Node.js 18 or newer.

Is self-improving-agent safe to install?

It can run commands from eval files you give it and, with --hooks, adds hooks to your Claude Code settings. Our advice: skip --hooks at first, read every eval artifact before you run it, and check what the installer changed with apb conformance.

Information

updated Nov 2, 2026

Repository: zhaono1/agent-playbook
Folder: skills/self-improving-agent

zhaono1/agent-playbook skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 7

self-improving-agent SKILL.md · github.com
agent-playbook README · github.com
@codeharbor/agent-playbook README · github.com
eval-artifact.md · github.com
agent-playbook package.json · github.com
agent-playbook LICENSE · github.com
agent-playbook cli.js · github.com