CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Use this file when editing Skill Kit itself. For a quick overview of the repository, read README.md. For the deeper workflow philosophy and detailed delivery model, read SYSTEM-OVERVIEW.md.

What This Repository Is

Skill Kit is a personal directory of Claude Code skills — composable workflow steps that form a feature development pipeline. Skills are installed globally for Claude Code via npx skills@latest add chrislacey89/skills --skill '*' --agent claude-code --global -y.

This repo is not an application — there is no build system, test runner, or deployment target. Each subdirectory contains a SKILL.md (with YAML frontmatter for name and description) and optional reference files.

The Pipeline

Skills compose into an ordered pipeline for taking a feature from idea to shipped:

/shape → /research → /write-a-prd → /prd-to-issues → /execute → QA → /pre-merge → /compound (in-PR) → /pre-merge (re-run: re-stamp) → /closeout (merge + teardown) → cleanup

This summary is here so skill authors can keep handoffs consistent. For work that requires multiple independent PRDs, /shape may branch to /create-milestone, which creates a planning milestone plus feature issues that mature from roadmap bet to research-ready to prd before re-entering the default path at /research. For big-batch work (6 weeks) that fits a single PRD, /write-a-prd creates a lightweight container milestone and attaches the PRD issue to it; /prd-to-issues then propagates the milestone to all slice issues. Ralph is the AFK execution mode/persona for the /execute stage, not a separate pipeline step. The canonical rationale, state model, and recovery rules live in SYSTEM-OVERVIEW.md.

Operating Modes

The pipeline steps stay the same, but skill authors should be explicit about which operating mode a stage assumes:

• Planning mode — shaping, research, decomposition, and review. The output is a better artifact or better decision, not code throughput.
• HITL execution mode — implementation or verification that still depends on active user judgment.
• AFK execution mode — implementation from durable artifacts when the next slice is already unblocked and sufficiently legible.

When a skill participates in execution, say whether it is normally HITL, AFK, or both. If AFK execution is allowed, say what artifacts must already exist before it is safe to proceed.

Key interactions between skills:

• /research is mandatory between /shape and /write-a-prd — never skip it
• /shape branches to /create-milestone only when the shaped work requires multiple independent PRDs — not for all blank projects or large-scope efforts that fit one PRD
• /create-milestone creates a planning milestone plus sequenced feature issues and promotes the next chosen feature from roadmap bet to research-ready before it re-enters the main flow at /research
• /write-a-prd creates a container milestone for big-batch (6-week) work that fits a single PRD; /prd-to-issues propagates the milestone to all slice issues
• /research invokes /api-design-review for higher-risk API contract work (new external APIs, contract changes, OAuth/webhook security, or unresolved paradigm choices)
• /write-a-prd uses Shape Up's shaping discipline (appetite → solution → rabbit holes → no-gos), requires a lightweight API contract sketch for API-shaped work, and auto-invokes /design-an-interface or /api-design-review when the interface or contract is still uncertain; when the input issue came from /create-milestone, it expands the existing research-ready feature issue into the full PRD rather than creating a duplicate issue
• /execute delegates to /tdd for backend code and consults docs/solutions/ and the research archive entry (at the path /research Phase 5c writes) before implementation
• /execute auto-invokes /pre-merge at the end of Step 6 when Step 5's manual verification checklist ran and the user confirmed the "Ready for PR Review" item — this is the default HITL flow. AFK Ralph iterations skip Step 5 (no user to ask) and exit cleanly for the user to invoke /pre-merge manually after the batch. Trivial-task flows that took the .claude/.tdd-skipped exception also skip Step 5.
• /init-pipeline is auto-invoked by /execute Step 0 when .claude/hooks/enforce-classification.sh is missing, or when it exists but does not read every path the hook's own classification clause tests — .claude/.review-stamped (a pre-lock install) or any classification marker, .claude/.lfg-active being the one that shipped last — or lacks a # gate: sentinel line the gate's GATE_SENTINELS names (the project-scope clause, which adds no path). Either way it is re-scaffolded without re-asking the trigger-surface question, and scripts/test-lfg-marker.sh pins Step 0's term list against the clause it is derived from, and its sentinel list against the hook's sentinel lines, so the next marker cannot ship undistributed the way .lfg-active did — scaffolds Claude Code hooks (TDD classification gate, git guardrails), pre-commit hooks, and package manager enforcement into the target project
• /setup-ralph-loop is auto-invoked by /execute when the task comes from a multi-slice GitHub issue and no Ralph scripts exist — prepares ralph-once.sh and bounded ralph.sh for HITL-to-AFK execution
• /tdd creates .claude/.tdd-active with a ! command the harness runs when the skill loads. That does not depend on the model, except in auto mode for a command that would need approval, where the skill loads with an instruction for the model to run it instead (Claude Code skills docs). /execute Step 6 removes it after commit, and /pre-merge Phase 4 and /fix-findings' report clear every classification marker too, so one left armed by a side-route does not outlive the review — a PreToolUse hook blocks .ts file writes unless the classification gate was passed
• /prd-to-issues produces boundary maps (Produces/Consumes) that /execute reads to understand interfaces, plus a Context subsection on AFK slices that /execute Step 1 is required to read before its docs/solutions/ grep (the subsection's slots are defined once, in /prd-to-issues §4, and pinned to the issue template by scripts/test-context-block-contract.sh)
• /pre-merge creates the PR with PRD lineage and verifies boundary map contracts from /prd-to-issues against actual code
• /fix-findings is the fix half of the review seam. It is model-invocable so /pre-merge Phase 4's next-step menu option Fix a finding on this branch first can run it, but human-gated: /pre-merge asks which finding numbers and invokes it with exactly those, and it never runs on numbers a model chose. It takes those numbers, spawns one fresh fixer sub-agent per finding under /pre-merge Phase 3's context contract, then one fresh read-only breaker in a git archive copy, and caps at one fixer pass and one breaker pass per finding. Three boundaries are load-bearing and must not erode in a later edit: it never selects findings (#190 — disposition is the human's; a finding the tree does not confirm is reported refuted, not decided away), it never writes the review-currency stamp (/pre-merge is the only writer, pinned by scripts/test-review-currency-marker.sh), and it never merges. It is backed by the post-review edit lock — /pre-merge Phase 4 writes .claude/.review-stamped, /init-pipeline's classification hook refuses implementation writes while it exists and .claude/.fix-findings-active does not, and /closeout removes it at merge
• /respond-to-review is the side-route for a teammate's review of the author's PR, the one review the pack did not produce. /closeout Step 2 and /help route a CHANGES_REQUESTED PR to it. It reads the unresolved threads verbatim in one GraphQL call (on Bitbucket Cloud, through the REST API with a read-only token, into the same numbered JSON), has a fresh read-only sub-agent sort each claim (supported / refuted / preference / out-of-scope / discussion, each cited), and asks the human to decide each thread: fix, push back, postpone, or answer. Threads marked fix go to /fix-findings (how a fix run is recorded is stated in docs/state-backend.md). Pushback gets a Triple-R reply draft per docs/comment-craft.md § Receiving a review. It never posts, resolves, stamps, or merges, and it writes nothing in the project tree: its record goes to <sidecar>/review-responses/pr-<n>.md through sidecar.sh path review-responses, a re-run reads it first, and a supported-and-fixed thread is marked a /compound candidate. Pinned by scripts/test-respond-to-review-contract.sh
• /closeout owns the merge/cleanup git-hygiene tail after /pre-merge: confirm → merge the reviewed PR → re-anchor the shell to the base checkout before removing the worktree → prune the merged branch → pull base → verify a clean end state. It is HITL-confirmed (never auto-merges), orchestrates existing tools (gh pr merge, wt remove/git worktree remove, commit-commands:clean_gone), introduces no filesystem state, and defers lesson capture to /compound and issue-closing + research-artifact hygiene to SYSTEM-OVERVIEW Step 9, except on the sidecar backend, where Step 3 closes the slice work item whose pr field holds the merged PR, never a PRD that holds it (no Closes #N line does it there) and offers the parent PRD's close as a confirm once every slice is closed, pinned by scripts/test-closeout-work-close.sh. When isolation is host-owned (worktree.provisioning: host, or a host env var like CONDUCTOR_WORKSPACE_PATH/CODESPACES), /closeout still merges but cedes worktree teardown and branch pruning to the host; symmetrically, /execute Step 0 stands down rather than provisioning a worktree the host already created
• /compound captures lessons into docs/solutions/ — by default onto the open PR before /closeout merges (so the lesson is reviewed and merged with the code that taught it), or post-merge as the fallback for lessons that surface at/after merge; this is the compounding loop, and it may also capture tranche-level lessons when a milestone closes. The in-PR path's terminal step is a /pre-merge re-run, not /closeout (#336): committing the entry onto the branch moves the head past the review-currency stamp, /pre-merge is that stamp's only writer, and without the hand-back the entry merges with the code that taught it and is read by nobody — which is the one thing the in-PR default was chosen to avoid. The re-run takes the compound commit as its post-stamp delta and re-stamps; it does not re-recommend /compound, so the leg runs once. /closeout Step 2 and /pre-merge both judge such a commit by its paths rather than its docs: compound subject, because Phase 5 stages Phase 4's mechanism in the same commit — docs/solutions/ and the root UBIQUITOUS_LANGUAGE.md (Phase 1's Vocabulary check, #512) are the paths that still count as the captured lesson; anything else is a code delta — pinned by scripts/test-compound-restamp-handoff.sh
• /compound and /pre-merge may recommend /improve-pipeline when the main lesson is about Skill Kit itself rather than the downstream project; /improve-pipeline files a GitHub issue in chrislacey89/skills and is advisory until the user approves follow-on implementation. Separately, /compound Phase 4 may file a proposal stub in chrislacey89/skills itself, as the fifth of its permitted mechanisms — available only when the preventing change belongs to the pack rather than to the downstream repo, and not as a substitute for a downstream mechanism that is merely hard to build
• When backtracking to an earlier skill, stale artifacts (research archive entries, PRD issues, slice issues) must be explicitly updated or superseded before proceeding forward — /correct-course is the invocable front door for this, and the canonical rules live in SYSTEM-OVERVIEW.md "Pipeline Recovery". Archive entries are superseded by a new dated file, not deleted.
• /visual-recap is an optional side-route at the /pre-merge → merge boundary (like /walk-commits): it renders a finished diff/PR/branch as a transient, self-contained interactive HTML artifact so a reviewer who didn't author the change can grasp its shape before reading lines. It renders in one of two canonical modes, selected in Step 1 against a one-line rule (is there one story the screens advance? deck; is the reviewer auditing parallel hunks? scroll) — the scrolling recap (docs/visual-recap-design.md Part I) or the walkthrough deck (Part II, premise → changes → mechanism → aftermath, one idea per screen, paged by toggling hidden over sections rather than swapping innerHTML). Diagrams take the CSS .fc-* spine when trivial and Mermaid-via-CDN when multi-stage or behavioral, each Mermaid figure carrying a visible degrade note; the offline invariant is scoped to core blocks, so a figure may degrade but a finding may not. It is never auto-invoked, skips small/obvious diffs, and produces a transient artifact (gitignored .context/ or mktemp, never committed). It may recommend /re-pitch when the change feels abstract to the audience, and never invokes it. Defect-finding stays in /pre-merge; free-form diagramming stays in /excalidraw-diagram. It shares docs/visual-rendering-core.md (rendering vocabulary, copy-text feedback serializer — required on handoff, optional when the author is in the room — Grounding Rule, secret-redaction, Tufte quality bar) with /walk-commits — bundled into both via scripts/skill-references.manifest
• /re-pitch is the comprehension-repair side-route: it fires when an explanation did not land, diagnoses whether the reader is missing a term, missing the situation, or was given too much at once, and re-states the same content under a checkable rule set with every domain term glossed on first use. It rewrites an existing answer rather than producing new work, never runs against a wrong answer (correct that instead), writes nothing to disk, and returns control to whatever was in flight. It reads UBIQUITOUS_LANGUAGE.md when present and may recommend /ubiquitous-language when the same terms keep needing glosses — but never invokes it
• /execute and /fix-findings share docs/mutation-at-consumption.md — the single statement of the mutation rung (name the property, mutate at the point of consumption, draw the edit from the corpus, and the two readings of a green result), plus the apparatus check that gates its four verdicts. /execute Step 4 points at it for the author-time move; /fix-findings points at it for the breaker's procedure. Neither restates it — bundled into both via scripts/skill-references.manifest
• /tdd, /pre-merge, /execute, and /fix-findings share docs/restated-claims.md — the single statement of the restated-claim-in-unchecked-prose class (what a prose contract and an operative site are, which kinds of text are not prose contracts, the census move, the limit of the literal-count assertion, and the fallback when interpolation is unavailable). /tdd § 4 Refactor points at it for the author-time move; /pre-merge's Deep Modules dimension points at it for the review-time detector, and its Severity Classification points at the list of kinds that are not prose contracts to cap a finding on one at Suggestion; /execute Step 4 points at it for the scope check on set-claims, the author-path rung that keeps an existential measurement from being written up as a universal claim; /fix-findings Step 1 points at the same list to scope its closed action set for a finding about a sentence's claim — delete the sentence or point it at the canonical statement, never reword it, with the after-state read off the fix and a reworded fix reverted. None restates it — bundled into all four via scripts/skill-references.manifest; scripts/test-bundled-pointer-resolution.sh pins that the pointers resolve, and scripts/test-prose-fix-disposition.sh pins that the section they cite exists and that /fix-findings' after-state vocabulary matches its report block
• /lfg is a user-invoked side-route (disable-model-invocation: true) for a proof of concept. It auto-sizes the ask with docs/trivial-task-rule.md (bundled). A one-off fix takes a tiny path under the existing skip marker. Anything else takes a feature path: a short HITL shaping conversation, then AFK through research-lite, a PRD-lite issue, /init-pipeline declared on Path B, a tracer-bullet build loop capped on slices and attempts, and a close that removes .claude/.lfg-active before /pre-merge --loop. It reuses only /init-pipeline Path B and /pre-merge --loop, which reconnect it to the main workflow. It never writes the review-currency stamp, never fixes a finding in-run, never merges, never creates per-slice issues, and never advances a ledger row past filed. Its marker set is pinned by scripts/test-lfg-marker.sh. It is GitHub-backend only for now: before either path writes, it asks sidecar.sh backend slices and backend stamp and stops on a sidecar answer or a refusal, pinned by scripts/test-guest-footprint.sh
• /hackathon is a user-invoked side-route (disable-model-invocation: true) for a judged, time-boxed hackathon day, run in two sittings. Prep (event profile, project choice, shaping) writes one dossier to <sidecar>/research/hackathon-<date>.md because events require the repo to stay empty until the start; the build day writes PLAN.md and DECISIONS.md into the event repo, a scoped exception to the no-project-tree rule because that repo is the judged deliverable. It never estimates in hours: it plans an over-full scope ladder and re-plans at fixed clock checkpoints from the measured median rung time, and it never moves the freeze or the deadline. It never invents a rubric field the brief does not state. It invokes /init-pipeline at kickoff and /tdd in the rung loop, creates no marker of its own, never stamps, and never merges. Its boundary with /lfg: /lfg is an unjudged, unattended proof of concept that ends in /pre-merge --loop; /hackathon is HITL all day and ends at the judging table
• /excavate is a user-invoked side-route (disable-model-invocation: true) for onboarding to a legacy repo that has history but no docs/solutions/, research archive, or written decisions. It mines a fixed window (default 12 months) of git history, plus PR bodies, reviews, and linked issues via gh when available, from one shared filtered log that two parallel miner sub-agents read, into Tornhill-style hotspots, recovered decisions, and a who-to-ask map. Three boundaries are load-bearing: only stated decisions are committed (a verbatim quote cited to a SHA or PR that resolves; inferred ones stay in the off-tree dossier at <sidecar>/research/excavation-<date>.md), no name or handle reaches docs/solutions/, and it never degrades silently (a Coverage block states window, shallow status, squash ratio, and gh reach). Entries use /compound's format and are confirmed per item onto a docs-only PR it never merges; scripts/test-excavate-entry-contract.sh pins the frontmatter keys and categories to /compound's template and the fix-grep string to /triage-issue's, and scripts/test-documented-git-commands.sh runs every fenced git block against a planted fixture. It reconnects at /shape; /help recommends it on the legacy signal and /research Phase 3 reads the newest dossier
• /ubiquitous-language is a user-invoked side-route (disable-model-invocation: true, #512) for hardening domain vocabulary into UBIQUITOUS_LANGUAGE.md. Nothing in the pipeline invokes it; /qa, /prd-to-issues, and /re-pitch read the file when it exists, /shape's closing summary names the terms a shape coined or contested, and /compound Phase 1's Vocabulary check writes a term the shipped change introduced, renamed, or contradicted — so the glossary has a writer at the retrospective seam and the standalone skill is for the bulk session
• /help is the orientation skill — it reads repo state (branch, PRs, issues, research archive, milestones) and recommends the next pipeline skill with a one-line reason. It is advisory only and never invokes the recommended skill itself.

Invocation Roles

Use these categories consistently across the repo:

• Primary pipeline skills — direct-entry steps in the default delivery path, plus the milestone-planning branch for oversized work: /shape, /create-milestone, /research, /write-a-prd, /prd-to-issues, /execute, /pre-merge, /closeout, /compound
• Invoked helper skills — usually not top-level entry points for a feature, but delegated when a narrower decision is unresolved: /api-design-review, /design-an-interface, /tdd, /triage-issue, /fix-findings
• Side-route skills — valid alternate or supporting paths beside the main pipeline: /qa, /request-refactor-plan, /improve-codebase-architecture, /improve-pipeline, /ubiquitous-language, /ts-audit, /walk-commits, /visual-recap, /help, /correct-course, /handoff, /re-pitch, /respond-to-review, /lfg, /hackathon, /excavate
• Infrastructure skills — project setup or safety tooling, not normal delivery steps: /init-pipeline, /setup-pre-commit, /setup-ralph-loop, /git-guardrails-claude-code

Each skill should make its role obvious.

• Direct-entry skills should say when to start with them and whether they are on the default feature path or the milestone-planning branch.
• Invoked helpers should say who calls them and when not to call them directly.
• Side-route skills should say how they reconnect to the main workflow.
• Infrastructure skills should say they are setup tasks, not feature-delivery stages.

Invocation mechanics — a cost axis orthogonal to role

The roles above say where a skill sits in the workflow. They say nothing about how it is invoked, which is a separate axis with its own cost:

• Model-invoked skills can self-trigger, so their description sits in the context window on every turn of every session — in every downstream repo the pack is installed into. The cost is context load, paid whether or not the skill ever fires there.
• User-invoked skills fire only when a human types /name (disable-model-invocation: true in Claude Code). The cost is cognitive load: zero context, but the human must remember the skill exists.

The two axes are independent — a side-route or an infrastructure skill can be either. Naming the axis gives the vocabulary to ask, per skill, "can this ever usefully self-trigger in a downstream session?" For a side-route that is always typed in practice the answer is plausibly no, and its always-on description is an unpriced cost that grows monotonically as the set grows.

Handoff Contract

Each pipeline skill should end with a clear transition statement:

• Expected input — the artifact, decision, or context it needs
• What it produces — the artifact, decision, or verified outcome it leaves behind
• What comes next — the default next skill or branch

If a skill can branch, the branch condition should be explicit. Example: /shape normally hands off to /research, but branches to /create-milestone when the work requires multiple independent PRDs. Example: /write-a-prd creates a container milestone for big-batch appetite before creating the PRD issue. If a skill advances an issue through maturity states, name them explicitly (roadmap bet → research-ready → prd) so downstream skills do not guess what artifact they are consuming.

At branch-point handoffs (and high-frequency control-yield seams like /execute → /pre-merge), offer the next step as an AskUserQuestion menu rather than leaving the user to retype a command — see docs/next-step-menu.md for when this applies and how to shape the options. The menu renders the What comes next line and composes with existing auto-invokes; it does not replace them, and it never appears on linear single-successor handoffs or AFK runs. The same doc carries the threshold above which a fork's options must be compared — as a table or panel matrix, cells cited or marked asserted — before the menu takes the choice.

Conversational Principles

One question per turn. When a skill needs to ask the user multiple questions, ask one question at a time and wait for the answer before asking the next. Never present a numbered list of questions, a bulleted set of questions, or multiple questions in a single message. This applies to every phase of every skill — discovery, constraint confirmation, review, and closing. The goal is a genuine back-and-forth conversation, not a form to fill out.

Architectural Principles

Deep modules over shallow modules. Skills like /tdd, /improve-codebase-architecture, and /write-a-prd all reference John Ousterhout's "A Philosophy of Software Design" — small interfaces hiding deep implementations. This shapes how interfaces are designed and refactored.

Vertical slices, not horizontal layers. /tdd enforces one-test-one-implementation cycles (not "write all tests then all code"). /prd-to-issues decomposes into tracer-bullet vertical slices that cut through all layers end-to-end.

Durable state never lives in the project tree on Skill Kit's own path. PRDs, milestones, work items, and bugs are GitHub issues or GitHub milestones, except where sidecar.sh backend answers sidecar: then PRDs and slices are work items in the sidecar's work/ store, and the review stamp is a record in its reviews/ store. docs/state-backend.md states that rule. Milestones serve two procedural roles: container milestones (from /write-a-prd for single-PRD big-batch work) and planning milestones (from /create-milestone for multi-PRD tranches). Per-project configuration and (when the project chooses) solutions entries live in the project's sidecar: a private, local-only git repository outside the working tree at ~/.claude/sidecars/<name>/, found and written only through sidecar.sh. No .gsd/ directories, no STATE.md, no PLAN.md per slice. The one scoped exception, PLAN.md and DECISIONS.md in a /hackathon event repo, is stated in SYSTEM-OVERVIEW.md § What is NOT in the project tree. The only persistent artifacts in the project tree are skills themselves and, when the project writes solutions in-tree, docs/solutions/, plus the root UBIQUITOUS_LANGUAGE.md when a project keeps a glossary.

Research location. Where /research writes its file, and whether it is committed, is stated once, in /research Phase 5c. It is referenced by the PRD and by /execute executions including Ralph's AFK loop, and persists after ship — branch switches, worktree cleanup, and /compound closeout do not touch it. Stale research still harms agent performance; the file's frontmatter (date, installed_versions_snapshot) exists so future readers can judge freshness before relying on it.

Writing Conventions

American English spelling, repo-wide. This applies to every file authored in this repo — SKILL.md bodies and frontmatter, README.md, SYSTEM-OVERVIEW.md, CHANGELOG.md, CLAUDE.md, everything under docs/ and site/, and comments in scripts/. It is not a skill-editing rule; it is a repo rule, and treating it as skill-only is how British forms drift into the prose files that skills are generated from.

behavior not behaviour, color not colour, initialize not initialise, center not centre, optimize not optimise, neighbor not neighbour, canceled not cancelled, labeled not labelled, modeling not modelling, artifact not artefact, judgment not judgement, skeptic not sceptic, analyze not analyse, gray not grey, defense not defence, toward not towards, while not whilst, among not amongst.

When forking an upstream skill that uses British spelling, convert it in the same change (this is what the /mermaid SKILL.md fork did).

Exceptions — leave the original spelling:

• Words that only look British. The always--ise verbs (supervise, exercise, promise, compromise, advertise, improvise, otherwise) and the words already correct in both dialects (analysis, characteristics, mechanism, fulfillment, forwards as a verb) are American English as written. Do not "correct" them.
• Proper nouns, book titles, author names, and quoted material
• Identifiers that must match an external contract: package names (@img/colour), CSS keywords and API values (stroke: grey, $bgColor="grey"), config keys
• Verbatim vendored files. mermaid/references/*.md are autogenerated copies of upstream Mermaid docs, carry a THIS IS AN AUTOGENERATED FILE. DO NOT EDIT. header, and are the syntax source of truth for /mermaid. Their British spellings (recognise, modelling, summarises, centred, capitalised, Popularisation) are correct as-is — rewriting them breaks fidelity against upstream for no reader benefit.

Skill Structure

Every skill has a SKILL.md with:

---
name: skill-name
description: "When to invoke this skill"
sources:
  primary:
    - "Book Title — Author"
  secondary:
    - "Book Title — Author"
  papers:
    - "Paper Title — Author"      # optional type marker; see docs/skill-anatomy.md
---

Some skills have supporting reference files (e.g., tdd/ has deep-modules.md, interface-design.md, mocking.md, tests.md, refactoring.md). The improve-codebase-architecture/ skill has a REFERENCE.md with dependency categories and the RFC issue template. git-guardrails-claude-code/ bundles a shell script at scripts/block-dangerous-git.sh.

Editing Skills

When modifying a skill:

• Preserve YAML frontmatter (name and description) — these are used for skill discovery and invocation
• The description field determines when the skill triggers; write it as a usage hint, not a summary
• Make the description immediately answer three questions when possible: when to invoke, when not to invoke, and whether the skill is direct-entry, delegated, or conditional
• sources is an optional repo-local field, but expected for skills making substantive methodological claims
• primary means core lineage — the skill is fundamentally built on this work
• secondary means a supporting influence — a specific technique or check drawn from this work
• papers is an optional type marker, not a third tier — every entry must also appear under primary or secondary, and scripts/test-canon-coverage.sh fails if it does not. Use it only for a work that is a paper rather than a book and whose author field carries no citation convention to read (no et al., no trailing (Venue Year)); papers cited the normal way are typed without it. It exists because the landing page's canon section is derived from these blocks and renders papers as a different object than books
• Do not put provenance into description; keep it optimized for triggering
• Only claim a source if the skill body clearly operationalizes it
• Prefer short source lists over comprehensive ones
• Keep skills self-contained — each should work without requiring the user to read SYSTEM-OVERVIEW.md
• Cross-skill references (like /execute delegating to /tdd) should use the /skill-name convention
• Add a short invocation-position or handoff section when a skill participates in a larger workflow
• If a skill reconnects to the main pipeline, say exactly where it reconnects
• If a skill advances an issue through lifecycle states, define those states and the minimum content required to move between them
• If a skill can run HITL or AFK, say which mode is expected by default and what durable artifacts must exist before AFK execution is safe
• Follow the repo-wide American-spelling rule in § Writing Conventions

Inventory-sync rule (a router that lies is worse than no router). Adding, renaming, removing, or re-roling a skill must update every inventory surface in the same change, never in a follow-up. The surfaces are:

• the skill tables in README.md
• the Handoff Table and the role lists in SYSTEM-OVERVIEW.md
• the role lists in this file (CLAUDE.md § Invocation Roles)
• the classification ladder in help/SKILL.md Step 2 (state-driven rows only — a skill with no repo-state signal, like /re-pitch, correctly has no row)
• the catalog array in site/src/lib/data.ts, which the landing page's collection section renders and both spelled-out skill counts are now derived from

A stale surface routes agents and users to a skill that no longer exists, or under a role it no longer holds — the drift #143 reconciled once by hand. Keeping the surfaces in lockstep with the change that causes the drift makes that reconciliation standing rather than after-the-fact, and puts the inventory knowledge in the world instead of the maintainer's head.

Commands a skill documents

Skills ship executable prose: a downstream agent copies a fenced block out of a SKILL.md and runs it unsupervised in someone else's repo. A wrong command does not fail here — it fails later, quietly, somewhere the author will never see. Two rules govern it, and they apply in this order.

(a) Reference, don't re-author. When a skill's prose needs a third-party tool's exit codes, flag behavior, or defaults, link or quote that tool's own documentation instead of paraphrasing it from memory. A paraphrase is a permanent drift liability this repo then owns and has to maintain, and it is usually unforced: #243 records six successive drafts of one passage each shipping a wrong claim about a git subcommand that the triggering issue had never asked anyone to document. Before writing the claim, ask whether the skill needs it at all — the cheapest command claim to keep accurate is the one you did not make.

(b) Route to the mechanism. When a skill's prose does make a checkable claim about tool behavior, pin it with an executable contract test under scripts/test-*.sh and wire it into both .github/workflows/validate-skills.yml and lefthook.yml. That glob is the inventory — do not restate the list here, it drifts. test-review-currency-marker.sh and test-context-block-contract.sh are the readable entry points into the shape: a header naming the drift class and the incident behind it, then assertions that extract the real text from the real files rather than restating it. Careful reading is not the mechanism — in #243, every wrong draft was caught by a human or a review sub-agent, and none by a check.

Rule (a) runs before rule (b): the subtraction shrinks the set of claims that need pinning, and pinning a claim that should never have been written is the more expensive order.

Shared reference files

The skills npm CLI installs each skill as a self-contained directory under ~/.claude/skills/<skill>/. It does not copy repo-root files (SYSTEM-OVERVIEW.md) or sibling top-level directories (docs/). Any skill that needs to read those at runtime must bundle its own copy inside <skill>/references/.

When editing a skill:

• If you add a reference to SYSTEM-OVERVIEW.md or anything in docs/ (other than docs/solutions/, which is a downstream-project artifact), add a source consuming-skill line to scripts/skill-references.manifest and run bash scripts/sync-skill-references.sh.
• Point the skill body at the bundled path (references/<file>.md), not the repo-root path, so the instruction is valid post-install.
• The sidecar resolver ships the same way: its canonical copy is init-pipeline/scripts/sidecar.sh, and every skill that reads or writes the sidecar bundles it as references/sidecar.sh through the same manifest and sync.
• Canonical content lives at the repo root / in docs/. Never edit a <skill>/references/*.md copy directly — it will be overwritten by the next sync.
• The check-skill-references CI job runs scripts/sync-skill-references.sh --check on every PR and fails if a bundled copy has drifted.

Local dev setup

Install Lefthook (brew install lefthook or see https://github.com/evilmartians/lefthook) and ShellCheck (brew install shellcheck), then run lefthook install once per clone. This wires:

• Pre-commit — runs sync-skill-references.sh --check and shellcheck on any staged shell script. Cheap (<1s), catches drift and shell gotchas before CI does.
• Pre-push — runs every scripts/test-*.sh suite plus shellcheck across all scripts, except test-fixture-git-isolation.sh, which re-runs all the others and so runs in CI only (its header says why). The list is not repeated here; lefthook.yml and .github/workflows/validate-skills.yml are the two places a new suite must be registered.

Both suites also run in CI (.github/workflows/validate-skills.yml), so local hooks are an early-warning layer, not a gate. The repo intentionally has no package.json — no JS/TS to tend — so Biome and other Node-ecosystem linters are out of scope until that changes. scripts/test-skill-frontmatter-loads.sh also needs the Claude Code CLI (claude) at the version in .claude-code-version; without it that suite prints a SKIP line locally, and CI installs the pinned version and runs it.

Reading a prose diff

Paragraphs here are single physical lines, routinely past 400 characters — SYSTEM-OVERVIEW.md:207 is 1,051 and pre-merge/review-checklist.md tops out near 2,800. Git's unit is the line, so a paragraph edit renders as the whole paragraph deleted and a near-identical paragraph re-added, with nothing marking where the two diverge, and a large share of what the reviewer re-reads never changed. (#295 quantified that share; the figure is not restated here, because a count over "the last 60 markdown commits" is a sliding window that moves with every commit and nothing checks it. The two line lengths above are fixed and greppable.)

Use git diff --word-diff. It renders the same change as [-old-]{+new+} word-runs instead of two walls of text. It is a display flag on git's own diff (git-diff docs) and needs no repo configuration. Worth an alias once per machine:

git config --global alias.wd 'diff --word-diff'

.gitattributes does a different job — do not confuse the two. *.md diff=markdown selects git's built-in markdown userdiff driver, which supplies an xfuncname: hunk headers become @@ -4,3 +4,3 @@ ## Pre-merge rather than a bare line range, so a reviewer can see which section a hunk lands in. It supplies no wordRegex, and --word-diff output is byte-identical with and without it. That negative is easy to get backwards and was gotten backwards in #295's own proposal, so it is pinned by scripts/test-markdown-diff-attribute.sh against the installed git rather than trusted here.

Post-merge install verification

After a change to the manifest or any shared reference file lands on prod, run a one-shot install check to confirm the install CLI still delivers what we expect:

npx skills@latest add chrislacey89/skills --skill '*' --agent claude-code --global -y
scripts/verify-install.sh ~/.claude/skills

verify-install.sh exits 0 only if every manifest entry has a corresponding file under <install-dir>/<skill>/references/. This step is manual-only — it depends on live GitHub state and a published branch, so it's not part of per-PR CI.