# Self Improve > The Self-Improvement Protocol (SIP). After a participating skill runs, detect concrete signals that the skill itself could be better — ambiguous instructions, an uncovered edge case, a misfired rule, a stale cross-reference, a user correction — and propose a specific diff to it, surfaced for approval and never auto-applied. Conservative by default: silent unless a ready, blocking, or recurring fix exists. Trigger via /self-improve, or automatically when a self-improvable skill completes. Not /insight-skill-gap (deliberate batch scan for new/updated skills) or /insight-retro (post-implementation review) — SIP is the in-the-moment, per-skill detector. - Skill: `allemaar/self-improve` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add allemaar/self-improve` - Raw SKILL.md: https://api.skillmd.com/api/skills/allemaar/self-improve/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: allemaar (https://skillmd.com/u/allemaar) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/allemaar/self-improve --- # /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`](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`](../insight-skill-gap/SKILL.md); for a full post-implementation retrospective use [`insight-retro`](../insight-retro/SKILL.md); 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.