/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 @STAMP date.

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):

1. 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).
2. 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.

3. protocol.yon (dual-doc only) — a closing @STEP rid=step:sip as the last step, after step:nsp where 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-apply MUST_NOT + the /ask-gate human approval — not an assumed harness feature. (The harness's auto-mode self-edit classifier does gate writes to agent-config like CLAUDE.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-RESOLVED marker). 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 unguarded SIP → ask-gate → SIP → … loop. SIP closes this the way COP and AGP do: when it invokes them it prepends a SIP-RESOLVED marker carrying depth: 1; under that marker they run inline and neither their own step:sip nor 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.