Skill Authoring Standard

---
name: skill-authoring-standard
description: >
  The bar a SKILL.md must clear before it ships in this lacquer — tight
  trigger-oriented frontmatter, single responsibility, no padding, companion
  files only when genuinely needed. Use when writing a new skill, reviewing
  an existing one, or auditing the skill set for quality.
---

# 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.

Prefer concrete and checkable over abstract and aspirational: name specific
tools, specific commands, specific failure modes — not "follow best
practices" or "ensure high quality," which tell a reader nothing they can
act on or verify against.

## Companion files: only when they earn their keep

A skill is a single `SKILL.md` by default. Add a `references/` subdirectory
only when the reference material is long enough that inlining it would bury
the skill's core instructions (a large API surface, a big enumerated
checklist — see this profile's deeper stack-specific skills for the shape).
Add a runnable script only when the skill's value *is* the script — something
a reader executes, not just reads. If you're tempted to add a companion file
"for completeness," that's a sign the content belongs trimmed, not appended.

## Cross-referencing

Reference another skill by name in prose ("the same posture as the
security-review skill's verify-before-report principle") rather than
inventing a link syntax skills don't otherwise use — the reader who already
knows the referenced skill gets the connection; the reader who doesn't isn't
blocked by a dead link.

## Placement

Stack-agnostic guidance (applies regardless of iOS/web/supabase) belongs in
`core/skills/`. Anything that names a stack-specific tool, API, or convention
belongs in that profile's `skills/` — mixing the two either leaks
iOS-specific advice into a web project's synced skill set, or forces a
generalization vague enough to lose the concrete-and-checkable bar above.

Not every stack-specific rule belongs in a skill, though — a skill loads on
Claude's judgment (or `/<name>`), which is wrong for guidance that should load
automatically whenever a matching file is opened. For that shape, a project's
synced `CLAUDE.*.md` should point authors at `.claude/rules/` (path-scoped
files that load only when Claude touches matching paths) instead of growing
the profile body further. A profile `CLAUDE.*.md` pushing toward or past ~200
lines is the signal to split: move the parts that only matter for a specific
directory or file type into a rule, and reserve the profile body for what
every task in that stack needs regardless of which files it touches.

## Before shipping a skill

Read it back and ask: would a reader who's never seen this know from the
`description` alone whether to load it? Does every section either sharpen
that trigger or give an instruction they can act on? Is there a companion
file that exists because it seemed thorough rather than because it's used?
If any answer is no, cut, don't append.