starlight-handbook-kit

The key words MUST, MUST NOT, SHOULD, SHOULD NOT and MAY in this skill are to be interpreted as described in BCP 14 (RFC 2119, RFC 8174) when, and only when, they appear in all capitals.

Build and grow a decision-oriented engineering handbook: an Astro + Starlight static site where every topic is shaped identically (a fixed nine-section skeleton), diagrams and interactive widgets render usefully without JavaScript, and nine dependency-free CI gates fail the build the moment a page drifts from the contract. The gates are what make it safe to let an agent author content — a dropped page, an undated topic, a fenced-mermaid mistake, or a broken link all fail loudly instead of shipping.

Locating this skill's helpers (do this first). The steps below run bundled scripts. You execute from the target repo, not from this skill's directory, so a path written relative to this skill will not resolve. Resolve the base directory once and use it everywhere — including in any subagent prompt, which MUST receive the literal absolute path:

SKILL_DIR="<this skill's base directory>"   # your harness provides it when the skill loads
# If you don't have it, discover it:
SKILL_DIR=$(find ~/.claude ~/.config ~/.agents -type d -name 'starlight-handbook-kit' 2>/dev/null | head -1)
test -d "$SKILL_DIR/assets" || test -d "$SKILL_DIR/scripts"   # verify before proceeding

When to use

Use when you want to:

Scaffold a brand-new handbook site from scratch (Mode A), or
Author a new cluster or a single topic page into a site that already follows this pattern (Mode B).

Decision flow

Does a site with this pattern already exist (astro.config.mjs + templates/topic.mdx + the check-*.mjs gates)?
├── No  → Mode A: Scaffold a new setup.
└── Yes → Mode B: Author content.
            ├── A whole new theme/area      → add a CLUSTER (directory + index.mdx + topics + sidebar block)
            └── One more page in a cluster  → add a TOPIC (one .mdx from the template + sidebar item)

Output style. Write reports and explanations for the user in about 80% ASD-STE100 Simplified Technical English. Use short sentences, common words, active voice and one action per step. This style is for prose to the user, not for the code, prompts or files that this skill makes.

Mode A — Scaffold a new setup

Collect the parameters. Read PARAMETERS.md and decide a value for each of the five placeholders (package name, site title, site description, deploy base path, GitHub Pages host).
Copy the scaffold into the target repo root. The complete, gate-passing site lives under assets/templates/scaffold/ (including dotfiles like .gitignore and .github/workflows/). Copy it recursively:
```
cp -R "$SKILL_DIR/assets/templates/scaffold/." <target-repo>/
```
Substitute the five placeholders in the copied files. They appear only in astro.config.mjs, package.json, Makefile, README.md, src/content/docs/index.mdx, and .github/workflows/deploy.yml. Replace every {{PLACEHOLDER}} with its value (see PARAMETERS.md). After this, no {{...}} token may remain anywhere.
- Project page (served at host/<repo>/): set the deploy base to /<repo>.
- User/org root page (user.github.io): set the deploy base to `` (empty).
Install and verify.
```
npm install
npm run verify   # astro build + all 9 integrity gates
```
A fresh scaffold passes all nine gates out of the box: it ships one example cluster (example-cluster/) with an overview and one topic, plus the hidden _demo/widgets.mdx page the accessibility gate inspects. Do not delete _demo/widgets.mdx — the a11y/no-JS gate reads its built HTML.
Make it yours. Rename example-cluster/ to your first real cluster (also update its sidebar block in astro.config.mjs and the LinkCard in src/content/docs/index.mdx), then add clusters and topics via Mode B.

Mode B — Author a cluster or a topic

Add a TOPIC (one page in an existing cluster)

Copy the canonical template templates/topic.mdx to src/content/docs/<cluster>/<topic-slug>.mdx. (In the skill, the canonical copy is assets/templates/scaffold/templates/topic.mdx.)
Fill in the frontmatter: title, description, and last_reviewed (an ISO YYYY-MM-DD date — required by the frontmatter and freshness gates). Optionally set volatility: stable | volatile (defaults to volatile) to pick the review window the freshness gate measures against — volatile = 12 months, stable = 24.
Fill in all nine ## sections, in this exact order: Overview, Mental model, Types / Variants, When to use / When NOT, Tradeoffs, Diagram, Try it, Real-world examples, Further reading. Do not add, remove, rename, or reorder them.
Diagrams MUST use the <Mermaid code={\...`} />` component, not a fenced ```mermaid block — Starlight renders that as code, not a diagram (the mermaid gate fails it).
Widgets (optional, in ## Try it): import from ../../../components/ (three levels up from a <cluster>/<topic>.mdx page) and pass client:visible.
Register the page in astro.config.mjs: add { label: '...', slug: '<cluster>/<topic-slug>' } to that cluster's items.
Run npm run verify.

Add a CLUSTER (a new group of topics)

Create src/content/docs/<cluster-slug>/.
Add <cluster-slug>/index.mdx — the cluster overview. It also follows the full nine-section skeleton and needs last_reviewed (it is not a splash page). Use the example at assets/templates/scaffold/src/content/docs/example-cluster/index.mdx as the model.
Add one or more topic pages per the TOPIC steps above.
Append a sidebar block in astro.config.mjs (the file documents the exact shape inline). The overview's slug is the bare cluster slug; topics are <cluster>/<topic>.
Add a <LinkCard> for the cluster in src/content/docs/index.mdx, using the ${base}<cluster-slug>/ href form so the deploy base is applied at runtime.
Run npm run verify.

The nine gates (why authoring is safe)

npm run verify builds the site, then runs nine checks. Each pairs a design invariant with a script that fails CI when violated:

Gate (npm script)	Enforces
`verify:template`	Canonical template keeps its `TEMPLATE_VERSION` + 9 sections in order
`verify:pages`	Every routable content page actually rendered to `dist/` (no silent drops)
`verify:frontmatter`	Every topic carries a valid ISO `last_reviewed` date
`verify:skeleton`	Every authored page follows the 9-section order
`verify:a11y`	Widgets stay readable with no JS + keep ARIA/keyboard affordances
`verify:artifacts`	No tool-call artifacts leaked into authored MDX
`verify:links`	Every internal link resolves to a built file (base-aware)
`verify:mermaid`	Diagrams use `<Mermaid>`, never a fenced mermaid block
`verify:freshness`	Topics stay within their `volatility` review window — undated/malformed fails the build, overdue warns

The freshness gate fails closed on a missing or malformed last_reviewed (an integrity violation), but a topic merely overdue for review is a non-blocking warning — staleness shouldn't make the site un-buildable purely by the passage of time. Pin FRESHNESS_NOW=YYYY-MM-DD to make it deterministic in tests.

If you change the nine-section skeleton on purpose, bump the TEMPLATE_VERSION marker in templates/topic.mdx — the template-integrity gate keys off it.

Parameters

The five scaffold placeholders are documented in PARAMETERS.md.