edit-skills

Files (12)

• SKILL.md
• blind-eval.md · references/
• description.md · references/
• instruction-style.md · references/
• plugging-holes.md · references/
• pressure-scenarios.md · references/
• skill-shape.md · references/
• where-a-fix-lives.md · references/
• wording.md · references/
• pressure-grade.mjs · scripts/
• pressure.mjs · scripts/
• rename-skill.mjs · scripts/

SKILL.md (first lines)

# Skills tool

A skill earns its place only by stopping a mistake the model makes without it, in the fewest words that takes. Produce a skill whose every line changes what the model does, each rule carrying its boundary reason. Avoid restating default behavior, hiding the one rule that changes anything, and an order stripped of its boundary reason.

## When to use

- Creating, changing or sizing a skill, agent, hook or skill script.
- Borrowed by a stage → hand control back once done; otherwise own the turn.
- Not for a one-time fix, one project's habit, or a limit a regex can check: a commit, `CLAUDE.md` or the verifier holds those; a skill is for a call needing judgment.

## The loop

1. **Catch the mistake.** Write one prompt per `references/pressure-scenarios.md` whose answer shows the mistake as one observable symptom.
2. **Watch it happen.** Read `benchmarks/results/` and any earlier `pressure.mjs` answers directory for the case first; a stored result covering the edited file, made after its last edit, stands in for the run. The user asks for a run, or none covers the file → run `scripts/pressure.mjs --prompt <file> --cells <cells> --plugin-dir <clone>` on the cells `--cells-for <edited file>` prints, else the session's own; read only the `without` answers now.
3. **Choose the home.** Place the fix per `references/where-a-fix-lives.md`; write prose in the shape below, style per `references/instruction-style.md`, register per `references/wording.md`.
4. **Watch it stop.** Rerun `pressure.mjs` on the same cells only under step 2's condition (the user asks, or no stored result covers the file); read the `with` answers (`--grade` verdict `INCONCLUSIVE` → rerun with `--full`; one setting alone → `--contrast-env`). `without` run also passed → case shows nothing; harden it until that run fails.
5. **Close each new excuse.** Each justification the `with` run still produced → apply `references/plugging-holes.md`, rerun all cases. Done when a full rerun adds nothing to its tables.
6. **Verify.** Run the check the caller's rules assign to this edit (a caller that reserves the full check to its lead → only the proof it names). Red check → fix the structure; never add an exemption, lock or allowlist entry to turn it green.
7. **Judge blind.** Step 4's read a close call → judge stored pre-edit and edited `with` answers blind, per `references/blind-eval.md`; run its clones only when the user asks.
8. **Name the evidence.** Commit a skill or agent wording change with an `Evidence: benchmarks/results/<file>` or `Evidence: none (<reason>)` trailer; `npm run check` fails the branch without one.

## The shape

| Part | Contract |
|---|---|
| `description` | Trigger only: moments it fires, then what it leaves alone. No workflow: the model acts on that summary instead of the body. |
| Opening | One paragraph: principle, a "Produce ..." sentence, an "Avoid ..." sentence with a concrete list. An overcorrection sentence only as an optional limit once a recorded run shows over-application. An existing enemy/overcorrection opening migrates when that skill is next edited. |
| `## When to use` | Bullets: symptoms first, then each "not for" case. |
| Process | Steps where order matters: numbered, aim at most eight, in order until one matches; a judgment skill with no fixed order: bullets. Each step a rule, with its reason in one clause. |
| `## Red flags` | Only in a skill the model is tempted to skip: table from tempting thought to what is true. |
| `## References` | Table of each file and when to read it; nothing loads before the step that needs it. |
| `## Judgment` | Ladder: which rule wins when two conflict. |

## Form

- Bulk material (template, worked example, checklist over 20 lines) → `references/`; body names when to open it.
- Aim the body at 2,000 tokens (bytes after the frontmatter / 4) and the description at 200 characters; the verifier fails 2,500 tokens and 250 characters.
- A reference holds one topic and links to no other reference; over 100 lines it opens with a contents list linking each section.
- Text handed to a delegate → beside `SKILL.md` as `<role>-prompt.md`, with a References row naming the dispatching step; `references/` holds only what the skill reads itself.

## Red flags

| The excuse | What holds |
|---|---|
| "The body has room to explain itself." | Reason gets one clause; a paragraph-long one → reference. |
| "An edit this small needs no test run." | Without the `without` run, the edit is a guess about what the model does. |
| "Any model already knows this." | Then cut the line; only what the `without` run got wrong earns a place. |
| "I will test them together once all the skills are written." | Each skill clears every case before the next begins; skills written in a batch hide each other's gaps. |

## References

| File | Read it when |
|---|---|
| `scripts/rename-skill.mjs` | Renaming a skill: `node scripts/rename-skill.mjs --from <old> --to <new>` moves its folder, docs page and pressure folder and rewrites every mention in one pass. |
| `references/pressure-scenarios.md` | Step 1. |
| `references/where-a-fix-lives.md` | Step 3, before the first rule is written. |
| `references/instruction-style.md` | Step 3, before writing or editing any instruction file: `CLAUDE.md`, a rule or an output style. |
| `references/wording.md` | Step 3, when two phrasings compete or a rule's tone is unclear. |
| `references/description.md` | Step 3 for the frontmatter; step 5 when a symptom joins the description. |
| `references/skill-shape.md` | Step 3 for a skill started from nothing; never for a change to an existing skill. |
| `references/agent-shape.md` | Step 3 for an agent started from nothing. |
| `references/hook-shape.md` | Step 3 for a hook started from nothing. |
| `references/script-shape.md` | Step 3 for a skill script started from nothing. |
| `../../docs/principles/README.md` | Step 3, when the edit designs a prompt, context, agent, tool, harness or eval. |
| `references/plugging-holes.md` | Step 5, once a run with the skill loaded still produced a justification. |
| `references/blind-eval.md` | Step 7, when step 4's `with`/`without` read is a close call. |
| `../route-skills/references/closing.md` | Before the final message. |

## Judgment

- Rule the `without` run broke outranks a rule that only reads well.
- Edit with neither a run nor a stored result made after its last edit covering its file → revert, never keep as draft.
- Overlong skill → drop its weakest rule, never a rule's reason clause.

From blauwtje/exo, MIT.

More from blauwtje/exo