skill-authoring-standard

Skill Authoring Standard

A skill earns its place by being the thing someone reaches for at the right moment, not by existing. Every line either helps a reader recognize when to use it or tells them exactly what to do — nothing else survives review.

Frontmatter

• name matches the directory name exactly (core/skills/<name>/SKILL.md, name: <name>). A mismatch (seen and fixed in this lacquer before) breaks discovery silently — the skill loads, but nothing points a reader at it by the name they'd search for.
• description is a trigger, not a summary. State when to reach for this skill — the scenarios, phrasings, or task shapes that should surface it — not just what it is. "Reviews code for style" tells a reader nothing actionable; "use before merging, when the user says 'is this safe', or when a change touches auth/secrets/exec" tells them exactly when to load it. Keep it to the trigger conditions — the body is where the how-to lives.
• disable-model-invocation: true for a skill with real side effects (it ships a release, pushes somewhere, deletes something) that should only ever run because a human explicitly typed /<name>, never because Claude's own judgment matched the description to a task. Without it, the description above is the only thing standing between an ambiguous prompt and an unintended side effect.

Single responsibility

One skill, one job. If the body has an "and also" section that's really a different concern (a distinct trigger, a distinct audience, a distinct output), it's two skills wearing one name. Split it — a reader searching for one of the two jobs shouldn't have to read past the other to find it.

Body: instruction over exposition

Lead with the rubric or process, not throat-clearing about why the topic matters. Cut anything a competent reader already knows (don't explain what a git branch is; do explain the specific branching convention this lacquer uses). If a sentence would be true of any skill on any topic, it's filler — remove it.