skill-writing

Skill writing

A skill is a self-contained instruction to a model — one per file at skills/<name>/SKILL.md. This skill carries the how of writing one here; AGENTS.md is the source of truth for the mechanical rules the validator enforces (frontmatter, ## Red flags, no cross-directory links, tier vocabulary). Read it first; don't restate it here.

Two modes, inferred from the request:

• Create — a capability has no skill yet. Start from scaffolding, then clone the shape of the closest existing skill.
• 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 AGENTS.md (## Authoring a skill) for the rules in force.
2. Find the closest sibling and match its shape — don't invent a new one. A "create/update a GitHub thing" clones issue; a two-modes artifact skill clones docs or agents-md; a review dimension clones a *-review skill.
3. Scaffold (Create only): mise run new-skill <kebab-case> "<imperative description>", or copy SKILL_TEMPLATE.md.
4. Write to the conventions: imperative body, terse, description starts with a verb and says when to use it; reference other skills by bare name in ## See also; end with ## Red flags. Match wording to the sibling — same section order, same 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.
5. Validate: mise run validate.
6. Dry-run before commit: run skill-test on unlike real repos for any material change, and fold convergent fixes back in. A change is material if it alters what the skill detects, flags, or produces — even one bullet — not if it merely reads that way; a wording-only fix with no behavioral change (typo, link, terminology) can skip the dry-run.
7. Commit direct to main with a Conventional Commit subject — only once the user gives the go.