Claude Skill

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, a practice that improved the result,

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Download allemaar-open-skills-skills_self-improve-acf5f79.zip · 8 KB

Install

skills CLI npx skills add https://github.com/allemaar/open-skills/tree/main/skills/self-improve
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
Git git clone https://github.com/allemaar/open-skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

/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 improvement signal for 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 or gained something this run — a deviation, a guess, a halt, a wrong output, or a practice that improved the result) 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.
  • Good practice — a practice this run used improved the result and is absent from the skill's dos.
  • Fixed pitfall — a mistake this run made and fixed is not named in the skill's don'ts or gates.

The protocol — five steps

1. Watch

During the run, note any signal above. On completion, answer from this run's evidence:

  • Which practice improved the result and is absent from the skill's dos? (good-practice)
  • Which mistake did you make and fix that the skill's don'ts or gates do not name? (fixed-pitfall)
  • Which step did the task need that the skill's checklist lacks? (forced-deviation or edge-case)

An answer the skill already covers is not a signal.

2. Triage (anti-nag + dedup)

Apply the conservative bar above; 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. Bundle all qualified signals into one proposal of at most 3 items, each in the skill's nearest existing section; never add a section for one item. Prefer replacing or deleting text over adding it. 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. Cross-examine

If a required vetting or approval helper is unavailable, stop the dependent proposal path, name the missing coverage when material, and do not reconstruct the helper or surface an unvetted approval request. This does not block completion of the parent task. Full installations retain the existing depth and vetting sequence. Run /insight-cross-examine inline under a SIP-RESOLVED marker on the drafted items plus the no-change option; no fan-out when the caller is a leaf; suppress next-skill offers for this sub-step. Keep the items that survive, revised as it recommends. If none survive, record the proposal in the within-session already-proposed set and stay silent.

5. Surface

Route the cross-examined 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 — Apply an approved proposal through its verified canonical source owner and Skill Smith update/write procedure; current approval selects scope but never replaces path, preimage, conflict or recovery prerequisites. An installed projection is not the source. Managed directives must go through their owner; do not edit managed bytes as an ordinary skill tweak. On approve, use that owner 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): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. 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 /insight-cross-examine and /ask-gate and may invoke /insight-skill-gap; all 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.

Files (open-skills)
  • protocol.yon 9.8 KB · in bundle
  • SKILL.md 11.2 KB
    ---
    name: self-improve
    description: >
      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, a practice that improved the result, a fixed pitfall — and propose a specific diff to it, surfaced for approval and never auto-applied. Conservative by default: silent unless a ready, material, 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.
    visibility: public
    self-improvable: false
    triggers:
      - "/self-improve"
      - "/self-improve [skill]"
    next-skills:
      - skill: ask-gate
        phrase: "/ask-gate"
        why: "SIP never auto-applies — the proposed diff must be surfaced to the handler, which is exactly the question-triage gate ask-gate governs."
      - skill: insight-skill-gap
        phrase: "/insight-skill-gap"
        why: "When the in-the-moment signal points to a recurring pattern, escalate to the deliberate batch scan for new or updated skills."
      - skill: skill-smith
        phrase: "/skill-smith"
        why: "If the detected gap is a whole missing capability rather than a tweak, scaffold it as a new skill."
    ---
    
    # /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* improvement signal for 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 or gained something *this run* — a deviation, a guess, a halt, a wrong output, or a practice that improved the result) **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.
    - **Good practice** — a practice this run used improved the result and is absent from the skill's dos.
    - **Fixed pitfall** — a mistake this run made and fixed is not named in the skill's don'ts or gates.
    
    ## The protocol — five steps
    
    ### 1. Watch
    During the run, note any signal above. On completion, answer from this run's evidence:
    
    - Which practice improved the result and is absent from the skill's dos? (`good-practice`)
    - Which mistake did you make and fix that the skill's don'ts or gates do not name? (`fixed-pitfall`)
    - Which step did the task need that the skill's checklist lacks? (`forced-deviation` or `edge-case`)
    
    An answer the skill already covers is not a signal.
    
    ### 2. Triage (anti-nag + dedup)
    Apply the conservative bar above; 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. Bundle all qualified signals into one proposal of at most 3 items, each in the skill's nearest existing section; never add a section for one item. Prefer replacing or deleting text over adding it. 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. Cross-examine
    
    If a required vetting or approval helper is unavailable, stop the dependent proposal path, name the missing coverage when material, and do not reconstruct the helper or surface an unvetted approval request. This does not block completion of the parent task. Full installations retain the existing depth and vetting sequence.
    Run `/insight-cross-examine` inline under a `SIP-RESOLVED` marker on the drafted items plus the no-change option; no fan-out when the caller is a leaf; suppress next-skill offers for this sub-step. Keep the items that survive, revised as it recommends. If none survive, record the proposal in the within-session already-proposed set and stay silent.
    
    ### 5. Surface
    Route the cross-examined 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** — Apply an approved proposal through its verified canonical source owner and Skill Smith update/write procedure; current approval selects scope but never replaces path, preimage, conflict or recovery prerequisites. An installed projection is not the source. Managed directives must go through their owner; do not edit managed bytes as an ordinary skill tweak. On approve, use that owner 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`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. 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 `/insight-cross-examine` and `/ask-gate` and may invoke `/insight-skill-gap`; all 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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.