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.
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.
- 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.
---
# 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.
## 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.** Rebuild the original situation for subagents: files, context, the current skill. Give them the same task. Run it on several different models. No failing run means no patch. Change the harness (prompt, framing, 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. |
## 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"
Any of these: put the skill back. Start at Diagnose.