# Distill The Scar > Use when you just hit a real failure worth keeping — a bug, a wrong fix, a wasted hour — and want to turn it into a reusable skill instead of a private lesson. Turns one concrete failure into a Whetstone-shaped SKILL.md: extract the transferable invariant, write it so an agent can apply it without the original context, and gate it with the validator. Triggers on "make this a skill", "turn this into a rule", "capture this lesson", "distill this failure", "add a skill for this", "postmortem into a skill", and any moment you catch yourself saying "I'll remember this next time." - Skill: `iamakbarsha1/distill-the-scar` (Agent Skill) - Install (CLI): `npx skillmds@latest add iamakbarsha1/distill-the-scar` - Raw SKILL.md: https://api.skillmd.com/api/skills/iamakbarsha1/distill-the-scar/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: iamakbarsha1 (https://skillmd.com/u/iamakbarsha1) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/iamakbarsha1/distill-the-scar --- # Distill the Scar **Type:** Open-source — client-agnostic methodology, no project-specific detail. **Created by akbarsha — https://github.com/iamakbarsha1** Distilled from a case where the skill-making method itself lived only in one person's head — every existing skill was forged the same way, but the way was never written down, so it couldn't be handed to an agent or a contributor. **Licence:** Released under CC BY 4.0 — share and adapt for any purpose with credit. Full text: `LICENSE` at the repository root. **Feedback & Support:** If a rule here proves wrong or needs sharpening, open an issue on the repository or contact the author at the profile link above. If the problem is the agent not following a rule below rather than the rule itself, that's an execution failure — acknowledge and correct it. ## The core rule A skill is a scar with the pain removed and the lesson kept. It comes from **one concrete failure**, not from general advice. If you cannot name the single case that produced it — what broke, what the plausible-but-wrong move was, and how you know the real cause — you are writing advice, not a skill, and it will not survive contact with a real agent under load. Distill in five moves. Do them in order; skipping the first two is how you get shapeless "best practice" that reads well and changes nothing: 1. **Capture the raw scar.** Write down the actual failure before you generalize: the real command, the real output/error, the wrong hypothesis that felt right, and the evidence that finally located the true cause. Sanitize names and secrets, keep the mechanics exact. Vague memory here produces vague skills. 2. **Extract the one transferable invariant.** Ask: what rule, applied at the moment of the failure, would have prevented it — stated so it holds in codebases that share nothing with this one? One failure yields one invariant. If you find two, that is two skills. 3. **Write it in the anatomy.** Mirror an existing skill exactly — do not invent a new shape: - Frontmatter `name` (kebab-case, matches the directory) and a folded `description` that opens with **"Use when …"** and ends with a concrete **"Triggers on …"** list of the phrases and situations that should fire it. The description is the whole retrieval surface; a skill that never triggers is dead weight. - `**Type:**`, author, "Distilled from a case where …", licence, and feedback lines. - `## The core rule` — the invariant, in one paragraph. - `## Checks` — for a multi-rule skill, each rule as a bullet ending in a one-line sanitized **`*(real case)*`** grounding it in an actual scar. Ground each case against the record (the incident log, git history); if a check has no separate lived incident behind it, mark its example **`*(Illustrative: …)*`** rather than fabricating a scar — the validator checks the marker exists, not that it is real. A single-rule skill may instead fold that one rule and its case into `## The core rule` (as a **"Real case (sanitized):"** paragraph) and omit `## Checks`. - `## Pre-flight check` — a checklist the agent runs *before* it claims the work is done, with one checkbox per check, phrased so an unchecked box means "not finished." 4. **Name it for the invariant, not the story.** A plain imperative that states the rule — `verify-absence-claims`, `measure-the-delta-not-the- absolute` — beats a clever title. The name is a handle the agent greps for under pressure; match the local convention of the skills already present. 5. **Gate it.** Run `python3 scripts/validate_skills.py`. It enforces the frontmatter, the `**Type:**` line, `## The core rule`, the pre-flight section, the directory-name match, and — when a `## Checks` section is present — that every check carries a grounding case (`*(real case)*` or `*(Illustrative: …)*`) and the pre-flight has a checkbox for each. A skill that fails the validator does not merge — the shape is not decoration, it is what makes the skill usable under load. **Real case (sanitized):** A skills repository grew to nineteen entries, each genuinely distilled from a real failure. But the distilling itself was tacit — captured live by an observer step, then hand-shaped by whoever was at the keyboard. The plausible-but-wrong move was to trust that the observer log already *was* the method; that it wasn't became provable the moment a new contributor, handed only that log, could not produce a twentieth skill that matched the first nineteen. The method was never a written artifact, so the founder was the single point of failure for the repo's whole premise. Writing the method down as this skill — capture, extract, shape, name, gate — turned "how we make skills" from tribal knowledge into a step anyone can run, and made the repository self-hosting: the skill that forges the skills now lives beside the ones it forged. ## Pre-flight check — before you call a skill distilled - [ ] You can name the **single concrete failure** it came from — what broke, the plausible wrong move, and how the real cause was proven. - [ ] The skill states **one transferable invariant**, not a bundle of advice; a second invariant became a second skill. - [ ] The `description` opens with "Use when …" and carries a concrete "Triggers on …" list — it will actually fire when the situation recurs. - [ ] Every check carries a sanitized real case grounded against the record — or, when none exists, an example marked `*(Illustrative: …)*` instead of a fabricated scar (or, for a single-rule skill, the core rule does), and there is a **pre-flight checklist**; names and secrets are sanitized, mechanics kept exact. - [ ] `python3 scripts/validate_skills.py` prints `OK` — the skill passes the same gate as every other skill in the repository. If any box is unchecked, you have a lesson, not a skill — go finish the distillation.