Skills (project conventions)

Deltas for authoring/maintaining skills under .claude/skills/. The full recipe is the build-claude-skill skill; the quality bar is docs/agents/skill-quality.md. This file is the always-on summary so the conventions are in force the moment you touch a skill.

• Ownership first. Skills with metadata.author (e.g. laravel) are Boost-managed — boost:update regenerates them. Never rename or hand-edit them; a rename just spawns a duplicate. Only author-less skills are yours to change.
• The directory name is the command. Claude Code has no alias field; /-autocomplete and invocation key off the directory, and name: is display-only — keep them identical. Renaming a skill = git mv the directory (+ update every cross-reference; mind that a new name can contain the old token).
• Name by verb — the taxonomy. Six workhorse verbs: build- (create/scaffold — pair with be-complete), qa- (audit a concrete artifact — surface findings, confirm before any write), optimise- (make faster/leaner), find- (divergent discovery — what's missing; frame as goal+context, any category list illustrative not exhaustive), source- (convergent acquisition — get the best known X), check- (meta — reasoning + the check-everything orchestrator). Plus incidental prefixes be- (a manner of working), tidy- (housekeeping), fyi- (reference — no action), and standalone single-word skills whose name is the verb or the actor it names (vet, debug, brainstorm, wrap-up, janitor). App-specific builders take -in-tempo. Kebab-case, self-describing, read as the thing you'd type.
• description is the trigger. Pack it with Use when… / AFTER… / BEFORE…, the NOT cases, and how it differs from sibling skills. Keep (formerly X) after a rename.
• Describe what it is, never who calls it. A skill's or agent's description states its own job; dispatcher/consumer lists ("dispatched by X, used by Y") live with the caller and silently desync on a rename. Same boundary for config: a consumer's config co-locates with the consumer that owns it (e.g. a skill's gate.conf in its own directory), never in the engine's.
• A protocol shared by several skills/agents lives in one cited doc, never N prose copies. Restating a shared procedure inline (e.g. the security evidence-before-severity discipline) drifts the copies apart; extract it to an on-demand doc and have each consumer cite it with a one-line essence (the threat-model / docs/security/review-lens.md pattern).
• Declare the contract in the body — task class (the verb answers it), allowed tools, direct-vs-fork (runs in-thread, or dispatches a subagent to gather), and the verifiable artifact (what's true once it's done). Without these the verb decays into a vague slogan.
• A skill's SKILL.md is its agent-computer interface (ACI). The description + body is how the agent perceives and fires the skill — treat it like a UI: invest in it, and test that it actually triggers and reads right, with the same care as the logic. A skill the agent mis-fires or misreads is a bug, not a doc nit. Keep skill responses high-signal too — terse output costs fewer tokens with no loss (house style; see optimise-context).
• Surface-then-confirm is tiered by irreversibility — order the guards like an onion. A skill that writes / deletes / files issues / saves to memory / pushes proposes and lets the user pick — never acts unprompted (mirror find-untracked-work / find-learnings). Pure-read skills (find-, qa-, check-reasoning, fyi-, vet) carry no confirm tax — they just report. When a skill stacks several guards, compose them cheapest / most-general outermost → irreversible-action approval innermost (onion-ordered guardrails) so the cheap, general check rejects before the expensive or consequential one runs.
• Speak the glossary. Use the harness terms as docs/agents/glossary.md defines them (artifact, the heart, lens, surface-then-confirm, vet, altitude…) — don't coin a synonym for a term that's already pinned. If you genuinely need a new term, add it to the glossary and the flat term index in CLAUDE.md in the same change (keep the two in sync).
• Curated beats maximal. A skill you never fire is debt — prune before you accrete; don't add a near-duplicate. Audit the set with qa-skills.
• House style (code-quality.md applies): terse, why-not-what, and name the heart — mark the one step that carries the skill (**This is the skill.**). fyi-/reference skills are deliberately flat instead.