refining-skills
Use when a skill produced a bad result and there is an example plus a comment about what was wrong; when someone reports a skill failure or regression; when you are about to add a sentence to a skill and ship without reproducing the failure. Fork this conversation into a subagent that owns the loop. Replay the failing example from this session. Do not wait for it.
Synopsis
The YAML description states when to use this skill. disable-model-invocation is unset.
Source file: skills/refining-skills/SKILL.md.
Front matter
- name
refining-skills- description
- Use when a skill produced a bad result and there is an example plus a comment about what was wrong; when someone reports a skill failure or regression; when you are about to add a sentence to a skill and ship without reproducing the failure. Fork this conversation into a subagent that owns the loop. Replay the failing example from this session. Do not wait for it.
- disable-model-invocation
- unset
Full contents
---
name: refining-skills
description: Use when a skill produced a bad result and there is an example plus a comment about what was wrong; when someone reports a skill failure or regression; when you are about to add a sentence to a skill and ship without reproducing the failure. Fork this conversation into a subagent that owns the loop. Replay the failing example from this session. Do not wait for it.
---
# Refining skills
**REQUIRED BACKGROUND:** You MUST understand writing-skills. Same RED-GREEN-REFACTOR. Entry point for a real failure, not a blank page.
A complaint plus an example is a failing test. Patching from the comment is testing after.
## When to use
- A skill already exists
- Someone shows a bad output and says what was wrong
Not for writing a skill from scratch. Use writing-skills.
## Who runs the loop
Fork this conversation into one subagent so it has the full session. That
subagent owns Diagnose through Repeat. The parent does not run the loop.
Do not wait for that subagent. Do not merge its work back unless the user
asks.
## Loop
1. **Diagnose.** Name the unwanted behavior as a class, not as one prompt. If the desired result is unclear, ask. Offer options only when the situation supports them.
2. **Baseline.** Replay the real failing task from this conversation when one
exists. Give each run the current skill and that same prompt. Do not send
those subagents to research the repo or rebuild a heavier setup. Run it on
several different models. No failing run means no patch. Change the prompt
or model until the class appears, or stop and ask. Do not patch from a
report, a title/rules mismatch, or a green baseline.
3. **Patch.** The smallest change that also covers nearby cases.
4. **Verify.** Same prompt, same models, patched skill. The old failure must be gone on every run.
5. **Repeat** until no run shows it.
## Patch contract
A patch is one short constraint or example that names the class of situation.
```markdown
- Return one pasteable line. No greeting, sign-off, or extra sentences.
```
A patch is not the user's prompt pasted in, a WRONG/RIGHT essay, or a list of every phrase from the bad output.
## Rationalizations
| Excuse | Reality |
|--------|---------|
| "I already know" / "the report already defines the gap" | A clear report is still not a failing run. |
| "Just add X and ship" | That is the change you will test, not the end of the loop. |
| "Subagents are overkill for a one-line fix" | Small edits regress too. Same models, same prompt. |
| "One reread or mental pass is enough" | A reread is not a run. One run is not the set. |
| "Don't generalize, encode this case" | Encoding the case overfits. Name the class. |
| "Extra words are fine" | Extra words hide the rule. |
| "The harness cannot re-trigger it, so patch anyway" | Change the harness or stop. Green baseline means no edit. |
| The failing example is already here, but a clean setup is better | Replay that example. Do not send baseline subagents to research. |
## Red flags. Stop
- Editing the skill before a failing baseline
- Patching after every baseline run stayed green
- Shipping after one reread or one model
- Pasting the reported prompt into the skill as the fix
- Declaring done while any run still shows the old behavior
- "This is different because they already reproduced it"
- Running the loop in the parent
- Briefing a fresh subagent instead of forking this session
- Waiting on that subagent before ending the turn
- Inventing a synthetic case when the failing output is already in the session
- Sending baseline subagents to research or reconstruct the product
Any of these: put the skill back. Start at Diagnose.