1---2name: skills-tool3description: Use when creating, editing or sizing a skill or agent, before the edit and before it is called done. Not for CLAUDE.md, a rule or an output style.4---56# Skills tool78A skill earns its place only by stopping a mistake the model makes when the skill is absent, in as few words as that takes. The enemy is the skill that describes behavior the model already has and hides the one rule that changes anything. The overcorrection is an order stripped of its reason, which the model obeys to the letter without knowing where it ends.910## When to use1112- Creating a skill or an agent, changing one, or judging whether one has grown too long.13- Not for a fix that happens once, a habit of one project, or a limit a regex can check: a commit, `CLAUDE.md` or the verifier holds those, because a skill exists for a call that needs judgment.14- Not for `CLAUDE.md`, a rule or an output style.1516## The shape1718| Part | Contract |19|---|---|20| `description` | At most 400 characters of trigger: the moments it fires and the ones it does not. Workflow written into the description replaces the body, because the model acts on the summary it already read; `references/description.md` lists what goes in and in which order. |21| Opening | A single paragraph naming the principle, the enemy and the overcorrection. |22| `## When to use` | Bullets naming the symptoms first, then each "not for" case. |23| Process | Numbered steps, at most eight, taken in order until one matches; every step is a rule with its reason. |24| `## Red flags` | Only in a skill the model is tempted to skip: a table from the tempting thought to what is actually true. |25| `## References` | A table of each file and the moment to read it; nothing is loaded before the step that needs it. |26| `## Judgment` | A ladder saying which rule wins when two conflict. |2728## Form2930- A line holds one sentence of fewer than 25 words; a bullet runs two lines at most.31- Bulk material, such as a template, a worked example or a checklist longer than 20 lines, lives in `references/`, and the body names the moment to open it.32- Text handed to a delegate lives beside `SKILL.md` as `<role>-prompt.md` and appears in the References table with the step that dispatches it; `references/` is only for what the skill reads during its own run.3334## The loop35361. **Catch the mistake.** Write one prompt, built as `references/pressure-scenarios.md` describes, whose answer shows the mistake as one observable symptom; save it as `evals/<skill>-<case>/prompt.md` with a grader next to it, in the layout `tests/evals.test.mjs` checks.372. **Watch it happen.** Give that prompt alone to a `general-purpose` delegate on the model the skill under test runs on, or to `claude -p` in a scratch repository without `--plugin-dir`, and copy down the exact justification it gives.383. **Choose the home.** Place the fix with `references/where-a-fix-lives.md`, then write what must be prose in the shape above and in the register `references/wording.md` sets.394. **Watch it stop.** Rerun the prompt with the skill: the same delegate told to load it, or `claude -p --plugin-dir <clone>`; when the run without the skill also passed, the case shows nothing, so harden it until that run fails.405. **Close each new excuse.** For every justification the run with the skill still produced, apply `references/plugging-holes.md` and rerun all cases; the skill is finished when a full rerun adds nothing to its tables.416. **Verify.** Run `node verify.mjs`; a red check means the structure is wrong and gets fixed, never exempted.4243## Red flags4445| The excuse | What holds |46|---|---|47| "The body has room to explain itself." | Each rule gets one reason clause; reasons that need a paragraph belong in a reference. |48| "An edit this small needs no test run." | Without the run lacking the skill, the edit is a guess about what the model does. |49| "Any model already knows this." | Then the line goes; only what the run without the skill got wrong earns a place. |50| "Forbidding it will do." | Forbidding a wrong output shape tends to produce more of it; the failure picks the form. |51| "I will test them together once all the skills are written." | Each skill clears every case before the next one begins, because skills written in a batch hide each other's gaps. |5253## References5455| File | Read it when |56|---|---|57| `references/pressure-scenarios.md` | Writing the prompt in step 1, and whenever the run without the skill passes a prompt that only asks for the rule. |58| `references/where-a-fix-lives.md` | In step 3, before writing the first rule, to find the cheapest place that stops the observed mistake. |59| `references/wording.md` | In step 3, when two phrasings compete or the tone of a rule is unclear. |60| `references/description.md` | In step 3 for the frontmatter, and in step 5 when a symptom is added to the description. |61| `references/skill-shape.md` | In step 3 when the skill starts from nothing; never for a change to an existing skill. |62| `references/plugging-holes.md` | In step 5, once a run with the skill loaded still produced a justification. |6364## Judgment6566- A rule the run without the skill broke outranks a rule that only reads well.67- An edit that was never tested is reverted rather than kept as a draft, because without the run lacking the skill it is a guess.68- Short outranks complete: a skill that grew too long drops its weakest rule, never a reason clause.
blauwtje