--- name: improve-skill description: Improve an existing agent SKILL.md through one gated cycle: select the target (default this skill), snapshot the committed baseline, diagnose against skill-design-principles plus four rubric dimensions, apply exactly one focused change, and ship only if a different agent than the author PASSes with quoted evidence. Use when the user says "improve this skill", "improve-skill", "iterate on SKILL.md", or "apply skill-design-principles to a skill". Do not use for code slop over a duration (anneal), generic timeboxed work (timeboxed-iterating), graph orchestration (workgraph), metric hill-climb on a codebase (autoresearch), or stripping slop from existing prose (catalog-deslop). --- # Improve Skill One cycle, one change, one independent verdict. You do not decide the skill got better. ## Role You are the **orchestrator**. You: 1. Resolve the target `SKILL.md`. 2. Snapshot the baseline off-tree before any edit. 3. Diagnose against the lens below and pick exactly one hole. 4. Apply that one change, or dispatch an author who does only that. 5. Dispatch a **different** agent as judge. Enforce the verdict. You do **not**: score your own (or the author's) change; skip the gate; rewrite the skill; hand-edit generated README catalog files; create a skill from scratch. ``` NO INDEPENDENT PASS → NO COMMIT. FAIL → RESTORE BASELINE. ``` If you cannot dispatch a different agent, stop. Leave the tree at baseline. Do not self-score. ## Inputs | Input | Required | Default | |---|---|---| | Target skill | no | The `SKILL.md` next to this file (`improve-skill`) | | Commit prefix | no | none; the dimension still goes in the subject | If the user names a path that is not an existing `*/SKILL.md`, stop and say so. Do not ask them what to change. Out of scope: README, cheatsheet, harness files, new skills, application code, duration-boxed work. ## Working files `$d` is created in step 2 (`/tmp/improve-skill--/`). ``` baseline/ # committed (or pre-edit) copy of the skill tree diagnosis.md # one hole, or "nothing above the bar" gate.md # judge verdict — written by the judge, not you log.md # append-only ``` Pass **paths**, not file contents, to the author and the judge. `references/` next to this file are procedure helpers. `$skill_dir/references/` is the target's. They coincide only when the target is this skill. ## Process ``` select-target → baseline → diagnose → one-change → independent-gate PASS: regen catalog if needed, commit, record hash FAIL: restore baseline, do not commit, record why nothing-to-do: stop, no commit (valid refused improvement) ``` ### 1. Select target Start-here checklist — first match wins: 1. If the user named more than one skill (a list, "all skills", more than one `SKILL.md` or skill directory), stop. One cycle accepts one target. Do not pick a favorite. Do not ask which. 2. If the user named a path that is not an existing `*/SKILL.md` and not a skill directory that contains one, stop and say so. Do not default to this skill. Do not ask them what to change. 3. If the user gave an existing `…/SKILL.md` (or a skill directory that contains one), that is the target. 4. Otherwise the target is this skill: the `SKILL.md` in the same directory as the file you are reading. 5. Confirm the file exists and YAML `name:` equals the directory name. If not, stop. ### 2. Capture baseline Do this **before** any edit. `skill_dir` is the absolute path to the directory that contains the target `SKILL.md`. Run from a shell: ```bash skill_dir= slug=$(basename "$skill_dir") d=/tmp/improve-skill-$slug-$(date +%s) mkdir -p "$d/baseline" repo=$(git -C "$skill_dir" rev-parse --show-toplevel) rel=$(python3 -c "import os; print(os.path.relpath('$skill_dir', '$repo'))") if git -C "$repo" rev-parse --verify --quiet "HEAD:$rel" >/dev/null; then git -C "$repo" archive HEAD "$rel" | tar -x -C "$d/baseline" --strip-components=1 else cp -R "$skill_dir/." "$d/baseline/" fi git -C "$repo" rev-parse --short HEAD > "$d/baseline-rev.txt" ``` If `HEAD:$rel` exists, that tree is the baseline even when the working tree is dirty. If it does not, the live `$skill_dir` tree is the baseline — not only `SKILL.md` + `references/`. Restore uses `$d/baseline/`. If `$d/baseline/SKILL.md` is missing, stop. Do not edit. Do not invent a baseline. ### 3. Diagnose Read the target `SKILL.md` and any `references/` one level under it. Write `$d/diagnosis.md`. Do not ask the user what is wrong. **Lens** (apply all; pick one hole): 1. **Description = WHAT + WHEN.** Triggers named. Siblings that could steal load are excluded by name. 2. **Executable procedure.** A cold agent can name the next action and the stop/fail condition. Ordered steps, not principles. 3. **Degrees of freedom.** Fragile steps (baseline, one-change, independent gate, commit-on-pass) are locked. Wording of a change is free. "Use judgment" on a gated step is a hole. 4. **One home per fact; no sprawl.** No tutorial on what a skill is. No no-op restatement. 5. **Four rubric dimensions** (the judge scores these same four): - **Clarity** — every step names a next action or a stop condition. - **Trigger reliability** — intended utterances land here; sibling collisions do not. - **Procedure completeness** — no step the skill claims to require is missing or "figure it out". - **Anti-failure coverage** — each named failure mode has a named protection (restore, refuse, stop). A hole is above the bar only if you can quote a missing next action, stop/fail condition, trigger or sibling exclusion, or named protection. Rephrase, shorter wording, synonym, extra example of an existing rule, restating a protection already in the table, or a user ask that is only polish / length / wording cleanup is not a hole — write `nothing above the bar`. Write exactly one of: ```markdown # Diagnosis - Dimension or failure mode: - Hole: "" - Change: ``` or ```markdown # Diagnosis nothing above the bar ``` If `nothing above the bar`, append that to `log.md` and **stop**. Do not edit. That is a valid cycle. ### 4. One focused change Edit only the hole named in `diagnosis.md`. One dimension or one failure mode. Not a rewrite. Not "also cleaned up X". - You may edit `SKILL.md` yourself or dispatch an author with the target path, the diagnosis path, and "change only this hole". - Do not edit generated `README.md` files. - After the edit, if `$repo/scripts/generate.ts` exists, run from `$repo`: ```bash deno run --allow-read --allow-write scripts/generate.ts ``` Never hand-patch the root `### Skills` list. If the author touches anything outside the named hole, revert those extras before gating. ### 5. Independent gate Dispatch a **new** agent. Not you. Not the author. Give it only the baseline path, the live candidate path, this section, and the absolute path of `references/known-bad.md` next to this file. Judge prompt (fill the brackets, keep the rest): ``` You are an independent skill judge. You did not author this change. Baseline: < $d/baseline/SKILL.md > Candidate: < live SKILL.md path > Known-bad fixtures: Also read sibling files in each tree if present. Do not improve the candidate. Do not take the author's word. 1. Mechanical validity — FAIL if any miss: - candidate exists; directory name == YAML name - YAML name: and description: are single-line (not `>` / `|`) - description is 1–1024 chars, no XML tags, states WHAT and WHEN - a generate.ts-style first-line parse would capture the real description text 2. Score each dimension BETTER / SAME / WORSE. Quote both versions (or "absent in baseline") for every cell. - Clarity: next action or stop condition newly named vs buried or vaguer - Trigger reliability: intended utterance newly caught, or sibling newly excluded vs lost trigger or new collision - Procedure completeness: a required step newly specified vs removed or weakened to judgment - Anti-failure coverage: a named failure mode newly protected vs a protection removed 3. Known-bad — read that fixtures file. FAIL if the candidate matches any fixture (same shape, not only byte-identical). Do not invent shapes. Do not skip a fixture because the candidate added sentences. Write < $d/gate.md > as: - validity: PASS or FAIL + first miss - four cells with quotes - known-bad: match/no-match per shape - Verdict: PASS or FAIL PASS only if validity holds AND at least one BETTER AND zero WORSE AND no known-bad match. 0 BETTER (rephrase, length-only, synonym churn) is FAIL. Length is not a dimension. "Looks better" without quotes is FAIL. ``` You do not write `gate.md`. After the judge returns, go to step 6 even when `$d/gate.md` or a `Verdict:` line is missing. Do not invent either. ### 6. Commit only on PASS Reuse `$skill_dir`, `$d`, and `$repo` from step 2. If `$skill_dir` is unset or `"$skill_dir/SKILL.md"` is not the live candidate, stop. Do not invent an add or restore path. Parse `$d/gate.md` if it exists. Do not write it. PASS only when a `Verdict: PASS` line is present and no `Verdict: FAIL` line is present. Otherwise FAIL — missing file, missing `Verdict:`, unparseable, or FAIL. **PASS** ```bash git -C "$repo" add "$skill_dir" if [ -f "$repo/scripts/generate.ts" ]; then git -C "$repo" add README.md; fi git -C "$repo" commit -m "improve-skill: — " ``` `` is the name from `diagnosis.md`. `` is the caller's required prefix plus a trailing space, or empty. Add only the skill directory and generated README files. Record the hash in `log.md`. **FAIL** Run the FAIL restore in `references/restore.md` next to this file (not `$skill_dir`): overlay `$d/baseline/`, then delete live paths with no baseline counterpart. Stop if `$d/baseline/SKILL.md` is missing. Then: ```bash if [ -f "$repo/scripts/generate.ts" ]; then (cd "$repo" && deno run --allow-read --allow-write scripts/generate.ts) fi ``` Do not commit. Record the judge's first failing clause in `log.md`, or `missing Verdict:` if the file or `Verdict:` line is absent. You are not the judge. Do not override FAIL because the diff looks fine. ## Failure modes | Failure mode | Protection | |---|---| | Author declares the new version better | Judge is a different agent; self-score is not a verdict | | No subagent available | Stop at baseline; do not self-score | | Kitchen-sink rewrite | Diagnosis names one hole; extras revert before the gate | | Edit with no snapshot | Step 2 runs before any write; stop if `$d/baseline/SKILL.md` is missing; restore path is `$d/baseline/` | | Commit then maybe measure | Step 6 reads `gate.md` first; FAIL does not `git commit` | | Judge returns no `gate.md` / no `Verdict:` | Step 6 still runs; missing or unparseable → FAIL restore; do not write `gate.md`; do not commit | | FAIL restore or PASS add hits the wrong tree | Step 6 reuses `$skill_dir` from step 2; stop if unset or not the live candidate | | FAIL restore leaves newly added `references/` | Always `rm -rf "$skill_dir/references"`; copy from `$d/baseline/references` only if that dir exists | | FAIL restore leaves newly added files outside `references/` | Run `references/restore.md` next to this file: overlay `$d/baseline/`, delete live paths with no baseline counterpart | | Untracked fallback omits `assets/` or extra root files | Step 2 else copies the whole `$skill_dir` tree; FAIL extra-delete cannot drop pre-existing extras | | Catalog description becomes `>` | Single-line `description:` required; generate.ts after description edits | | Hand-edited README catalog | generate.ts only; never patch `### Skills` by hand | | Ask the user what to fix | Default target; lens produces the hole or a refusal | | Improve a non-skill | Step 1 stops unless the path is an existing `SKILL.md` | | More than one target | Step 1 stops; one cycle accepts one target | | Sibling collision (duration work, code slop, graphs, metric loops, prose deslop) | Description excludes anneal, timeboxed-iterating, workgraph, autoresearch, catalog-deslop | | Known-bad scored from memory | Judge reads this skill's `references/known-bad.md`; any fixture match → FAIL | | Cosmetic-only / rephrase cycle | Step 3 refuses unless the hole quotes a missing action, stop, exclusion, or protection; user-asked polish is `nothing above the bar` | ## Red flags — stop and reread - You are about to commit without a `Verdict: PASS` written by someone else. - `$d/gate.md` is missing (or has no `Verdict:`) and you are about to commit or leave the candidate in the tree. - You scored the change yourself. - `diagnosis.md` lists more than one hole and you are fixing them all. - You asked the user what to change. - You are hand-editing a README. - The working tree still has the candidate after a FAIL. - You skipped baseline because it is a small edit. - `$d/baseline/SKILL.md` is missing and you are about to edit. - The target is untracked and `$d/baseline/` is missing live `assets/` (or extra root files) and you are about to edit. - `$skill_dir` is unset (or not the live candidate) and you are about to `git add` or restore. - Live `references/` is still present after a FAIL and `$d/baseline/references` was missing. - Live `assets/` or an extra root file is still present after a FAIL and `$d/baseline/` did not have it. - You are scoring known-bad from memory instead of reading this skill's `references/known-bad.md`. - The hole is a wording preference (rephrase, shorter, synonym, restated protection) and you are about to edit anyway. - The user named two skills (or all skills) and you are about to pick one or run both. - The user named a path that is not an existing `SKILL.md` (or skill directory) and you are about to default to this skill.