allemaar /self-improve
Self-Improvement (SIP) turns each skill run into a chance for that skill to get better. When a participating skill finishes, SIP checks whether the run surfaced a concrete weakness in the skill — and if so, drafts a specific improvement and surfaces it for the handler to approve. It is the per-skill, in-the-moment, signal-triggered counterpart to the deliberate batch reflection of /insight-skill-gap and /insight-retro.
SIP is the structural mirror of NSP: NSP runs after a skill and asks "what should you do next?"; SIP runs after a skill and asks "how should this skill be better next time?"
SIP is invoked two ways: automatically, when a skill carrying the SIP opt-in block completes; or directly, as /self-improve [skill] to review a specific skill against the most recent run.
Structured execution spec:
protocol.yon. Read it for the canonical rules and step sequence; this file is explanation. The two must stay in sync — if you edit one, update the other and refresh the@STAMPdate.
Conservative by default. A missed minor improvement is cheaper than nag fatigue. SIP surfaces nothing unless a signal is concrete, material (it cost something this run — a deviation, a guess, a halt, or a wrong output) or recurring within the session (the same signal seen ≥2× this session), and a specific fix is ready. Silence is the common case.
Signal taxonomy — what counts as a real signal
SIP fires only on concrete signals tied to this run. Vibes ("this could be cleaner") do not qualify. The qualifying signals:
- Ambiguity — the skill's instructions were unclear and the agent had to guess which interpretation to follow.
- Uncovered edge case — the run hit a case the skill's steps/gates don't address, forcing improvisation.
- Forced deviation — getting a good result required departing from the skill's prescribed steps.
- Misfired rule — a gate/check over- or under-fired (e.g. an ABORT that should be WARN, a WARN that should be ABORT, a false-positive halt). This is how live skills get tuned.
- Stale cross-reference — a path, skill, or file the skill names has moved, been renamed, or no longer exists.
- User correction — the handler corrected the agent in a way that exposes a gap in the skill, not just this task.
The protocol — four steps
1. Watch
During and at the end of the participating skill's run, note any of the signals above. Passive — no extra work, just attention to where the skill fought you.
2. Triage (anti-nag + dedup)
Apply the conservative bar: surface a proposal only if the signal is concrete (tied to a specific taxonomy signal) and material — it actually cost something this run (forced a deviation, a guess, a halt, or produced a wrong output) or recurred within this session (the same signal seen ≥2× this session) — and a specific fix is ready to write. Otherwise stay silent. Then check the within-session already-proposed set — if this same improvement was surfaced earlier this session and not acted on, do not re-surface it (re-nagging is the failure mode). This is SIP's equivalent of COP's and AGP's anti-nag gate. (Cross-session dedup is a v2 backlog item — see Depth & safety.)
3. Draft
Produce a specific diff, not prose hand-waving: the target file (SKILL.md and/or protocol.yon, or a directive), the exact lines to add/change, and a one-line rationale tying the change to the signal. If the run instead reveals that a new skill is warranted (recurring multi-step pattern with no home), delegate the authoring question to /insight-skill-gap rather than drafting a skill from scratch here.
4. Surface
Route the proposal through /ask-gate (the proposal is itself a handler question) — invoked under a SIP-RESOLVED marker (see Depth & safety) — recommended action first: approve / edit / decline. Never auto-apply — application goes through the normal Edit path with handler approval. On approve, apply and (for dual-doc skills) keep SKILL.md ↔ protocol.yon in sync and bump the @STAMP. On decline or no-action, record it in the within-session already-proposed set so it isn't raised again this session.
The opt-in contract
A skill joins SIP by declaring itself self-improvable (per-skill front-matter is canonical):
- Front-matter field —
self-improvable: true. Capable procedural skills (phases, gates, judgment) opt in; pure routers, mode-setters, and reference cards omit it (nothing to tune from a run). - SKILL.md prose pointer — paste at the end of the body (SIP runs on completion, like NSP):
Self-improvement. On completion, run the Self-Improvement Protocol (
self-improve/SKILL.md): if this run surfaced a concrete, blocking-or-recurring weakness in this skill, propose a specific fix for the handler to approve. Conservative — silent otherwise. Never auto-apply. - protocol.yon (dual-doc only) — a closing
@STEP rid=step:sipas the last step, afterstep:nspwhere present.
The field is metadata — the harness does not execute it; it is read by SIP, by audit tooling, and by humans.
Depth & safety
- No auto-apply. Proposals are surfaced and approved, never silently written. The real guarantee is the
rule:no-auto-applyMUST_NOT + the/ask-gatehuman approval — not an assumed harness feature. (The harness's auto-mode self-edit classifier does gate writes to agent-config likeCLAUDE.md— confirmed to fire on such edits — but whether it also intercepts edits to individual skill files is unverified, so SIP does not lean on it.) - Dedup / proposed-once (within-session). Re-surfacing an un-acted proposal every run is nag. SIP tracks proposals surfaced during the current session and suppresses repeats within it. Cross-session persistence is not yet implemented — there is no on-disk queue, so a proposal declined in an earlier session can resurface later. Until a persistent
skill-improvements/store ships (v2 backlog), the mitigation is the conservative bar plus surfacing once and respecting the handler's standing decision. - Depth guard (
SIP-RESOLVEDmarker). SIP invokes/ask-gate(to surface) and may invoke/insight-skill-gap— both are themselves SIP participants whose completion would otherwise re-fire SIP, an unguardedSIP → ask-gate → SIP → …loop. SIP closes this the way COP and AGP do: when it invokes them it prepends aSIP-RESOLVEDmarker carryingdepth: 1; under that marker they run inline and neither their ownstep:sipnor any nested SIP re-enters the gate. The marker is the recursion guard — a prose rule alone is memory-dependent, since no harness signal detects the nesting. - Conservative threshold is the contract, not a suggestion. When unsure whether a signal clears the bar, stay silent.
Lifecycle position
SIP joins the skill-hook family and never conflicts with the others:
- COP (
caller-options) — before a skill: routes venue/mode. - AGP (
ask-gate) — the question moment: triages and quality-gates any handler question. - NSP (
next-skills) — after a skill: recommends successor skills. - SIP (
self-improve) — after a skill: proposes improvements to the skill that just ran.
NSP and SIP both run on completion and compose cleanly: NSP points forward (what to do next), SIP points inward (how this skill should evolve). SIP surfaces through AGP.
Platform mapping
- Surface — Claude Code: via
/ask-gate→AskUserQuestion. Codex or any runtime without a structured-question tool: present the proposal + recommended action as prose and wait. - Watch, triage, draft are runtime-agnostic.
Standalone use
/self-improve [skill] runs the protocol on demand against the most recent run of a named skill — useful to deliberately mine a skill you just used heavily for tuning opportunities, or to audit one skill's fit without waiting for an automatic trigger.
Boundary
Not a batch reflection and not a library audit. For a deliberate scan of recent work for new/updated skills use insight-skill-gap; for a full post-implementation retrospective use insight-retro; for library health (descriptions, cross-refs, runtime parity), run a dedicated library-audit pass. SIP is the lightweight, per-run, signal-triggered detector that feeds those when a pattern is bigger than one fix.