Skill writing

A skill is a self-contained instruction to a model — a directory holding a SKILL.md, the references it reads when a step needs them, and the scripts it names, each reached under that directory. This skill carries the how of writing one; the repo that holds the set owns its mechanical rules (frontmatter, required sections, links, its validator), usually in its AGENTS.md. Read those first; don't restate them in the skill.

Two modes, inferred from the request:

• Create — a capability has no skill yet. Clone the shape of the closest existing skill; the repo's validator catches what is missing.
• Update — a skill exists and a rule needs adding or sharpening. Merge into the right section and trim what it duplicates; never blind-append. Updating is the harder half.

Workflow

1. Pick the mode and read the repo's rules for authoring skills.
2. Find the closest sibling and match its shape — don't invent a new one. A skill that files something clones the nearest skill that files something; a review dimension clones another review dimension.
3. Write to the conventions: imperative body, terse, description starts with a verb and says when to use it; reference other skills by bare name, never by path; match the sibling's section order and lead-in style. Keep only what changes what the model does: for each line, ask whether the model would act differently without it, and cut what it already knows, such as a standard catalog or a textbook method. Keep project specifics out: a skill states what holds in any repo and defers the rest to the repo's own rules.
4. Sweep for drift: apply no drift from principles to the skill's own description, any index or README that lists it, and sibling skills or hooks that restate what changed, and, where the repo has a trigger check, that skill's trigger prompts (evals).
5. Validate with the repo's validator. Reach for an eval (evals) only when the change's risk needs one, such as a behavior the skill exists for or a past regression no cheaper check can judge; a model run needs the owner's approval, so name the run and why in the report instead of starting it.
6. Commit the way the repo's rules say, only once the user gives the go.
7. Check it in real use once it lands, where the host has the signals: the session record's skill loads by version, and a coach's experiment record with a check date for the change. workflow-review judges the change by them.