Immutable. This exact content is served forever at /api/v1/blob/be042a93b5bd4de5.
---
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-<target-basename>-<epoch>/`).
```
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=<absolute path>
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 "$skill_dir/SKILL.md" "$d/baseline/SKILL.md"
if [ -d "$skill_dir/references" ]; then cp -R "$skill_dir/references" "$d/baseline/references"; fi
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. 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: <one name>
- Hole: "<quote from the current skill or ABSENT>"
- Change: <one sentence>
```
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: <absolute path of references/known-bad.md next to this skill>
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 "<prefix>improve-skill: <dimension> — <one line>"
```
`<dimension>` is the name from `diagnosis.md`. `<prefix>` 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 |
| 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.
- `$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.