Self-improve
Suggest durable improvements to the skill, doc or check that should have steered the agent, so the next session gets it right without being told again — and apply them only after the user approves. The skill proposes; the user stays in control of every change. Three ways in:
- Manual — the user invokes
/self-improveto deliberately improve a skill or doc. - Self-triggered — the agent notices it was corrected on something a skill, doc or check governs (or should). Don't silently correct and move on, but don't derail the task either: note the lesson, finish what the user asked for, and offer to persist it at the next natural breakpoint.
- Driven by another skill — a caller (or its launch command, pasted by the user) hands over lessons already phrased as durable guidance, sometimes with all or part of a target it settled with the user (scope, form, path — possibly a new file or a merge into an existing one). Skip step 1; skip step 2 for a lesson whose target the caller settled fully, run it for the rest keeping what the caller settled — its Mechanical lesson bullet and new-doc indexing requirement always apply. Several lessons at once → first propose their placement as one table, each lesson with its doc, existing or new; then draft + apply, lessons sharing a target as one diff.
"Skill/doc" means any standing instruction: a SKILL.md, AGENTS.md/CLAUDE.md, a
coding-standards or convention doc, a rules file — anything that guides future agents. A "check"
(lint rule, hook, CI job) enforces one mechanically and is not a skill/doc.
Hard rules
- Confirm before applying. The skill's job is to suggest, never to change text on its own. Never edit a skill, doc or check without the user's explicit go-ahead on the concrete change — present it as a diff and apply only on approval, whether the user invoked the skill or the agent self-triggered. State plainly whether a change is not yet applied (awaiting approval) or already applied (and where), so the user never has to ask.
- Editing any skill/doc → always route the write through one of two skills to keep it compact;
never edit it directly. A
SKILL.mdgoes through compact-skill-creator; any other doc (rule,AGENTS.md/CLAUDE.md, convention doc) goes through compact-docs-writer. Actually invoke the skill and follow its workflow before drafting or applying; reading it, applying its principles by hand, or naming it after a direct edit does not count. A check is edited directly.
Recognize a persistable correction (self-trigger)
Signals the agent was corrected in a way worth persisting: the user rejects or reverts a choice ("no, do X instead"), states a standing preference ("we always…", "never…"), or redirects an action the agent took under a skill or doc.
Only persist a durable lesson — one that generalizes and will recur. Skip one-off, task-specific tweaks that won't apply next time; persisting those pollutes the docs. Whenever unsure whether it generalizes, ask the user.
Workflow
- Capture the lesson. State, in one line, the general rule the feedback implies — not the surface incident ("Mock external HTTP in unit tests," not "the agent mocked the wrong call").
- Locate the target. Settle scope first: would the lesson hold in another project? No → a
project doc, rule or wrapper, never a shared generic skill. Yes → the governing skill or doc,
shared ones included, edited at its canonical source when the installed copy is a symlink or
sync — the proposal says so. Find which skill/doc governs this action (search skills,
AGENTS.md/CLAUDE.md, convention docs); when the repo defines a doc-placement guide (e.g..agents/docs/README.md), follow it for locating and creating targets. If one exists, it's the target — and if that rule already existed yet failed to steer the agent, the discoverability gap is the lesson, not a no-op: don't stop at "the rule exists." Diagnose why it didn't fire (buried, in a doc the agent wouldn't open for this action, scoped or worded too narrowly, or unenforced) and fix that root cause: surface it where the agent looks, tighten its scope, cross-reference it, or enforce it mechanically. If none fits, propose a new target and ask before drafting: a check for a mechanical lesson (below), a new skill for a recurring workflow, a new rule for a standing constraint, or the most fitting doc otherwise; a new doc comes with its entry-file index line and read-when hook, or nothing ever loads it. Ask whenever unsure.- Mechanical lesson (a banned API, an import shape, a file location: any fixed pattern) → propose a deterministic check over prose; the check is declined, or no tooling can host it (the proposal says so) → write the rule. Read the repo's check scripts and CI first: wire or repair an existing check rather than add one.
- Place by context cost. Always-loaded docs (
AGENTS.md/CLAUDE.md) hold mostly pointers; a rule that matters only when reviewing goes in a review-time doc, not implementation context.
- Draft the edit. Write the rule into the target as the least text that fully captures it: agent-agnostic ("the agent", never a vendor name), no process narration, no restating — a real durable instruction. Prefer tightening or extending an existing rule over appending a new one. If the lesson reverses an existing rule, surface that explicitly — show the old rule, the feedback, and the proposed replacement — and never overwrite it silently; the contradiction may mean the feedback is context-specific, not a true reversal. A check is drafted outside the repo, with its proof: run it on a reproduction of the mistake (must fail) and on the corrected case (must pass), both results in the proposal; one that cannot run here is labelled untested.
- Apply the edit. Route the write per the Hard rules —
SKILL.md→ compact-skill-creator, any other doc → compact-docs-writer, a check → edited directly — presenting a diff and applying only on approval. Done when every handed-over or captured lesson is applied, declined by the user, or reported as already covered, each named in the closing message.
