ckb/.agents/skills/ckb-export-starlight/SKILL.md

name	description
ckb-export-starlight	Export the local wiki/ knowledge base into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use when the user asks to "export the wiki to Starlight", "generate the docs site", "export as Astro Starlight", "build a human-readable wiki site", or "publish the knowledge base as a website".

Export to Astro Starlight skill

Purpose

Regenerate outputs/starlight/ from the current wiki/ tree so it can be built and served as an Astro + Starlight documentation website — a human-readable, browsable version of this knowledge base (unlike ckb-export-okf, which targets machine/tool consumption). This is a one-way, on-demand export — wiki/ stays the authoritative source; outputs/starlight/ is always a derived artifact of it, never edited by hand and never fed back in.

This skill only runs when explicitly invoked — it is deliberately not part of the always-loaded CLAUDE.md/AGENTS.md Ingest/Lint workflows.

The heavy lifting (frontmatter remapping, link rewriting, asset copying, sidebar generation) is done by a deterministic Python script, not by reading and rewriting every page by hand — the wiki now has 60+ pages, and a mechanical transform like this belongs in code, not in per-page model reasoning. Nothing in this skill needs an LLM to run correctly; the model's job is just to ask the two setup questions below, invoke the script, and relay its report.

Trigger phrases

Use this skill when the user says things like:

• "export the wiki to Starlight" / "export as Astro Starlight"
• "generate the docs site" / "build the Starlight site"
• "publish the knowledge base as a website"
• "sync outputs/starlight"

How to run this skill

Step 1 — Ask the two setup questions, every time

The user has explicitly said they want to choose these on every invocation — do not assume a default or reuse an answer from a previous run. Use AskUserQuestion with:

1. Export scope:

   • "Full runnable scaffold" → --mode full — regenerates the whole outputs/starlight/ project (package.json, astro.config.mjs with sidebar, tsconfig.json, src/content.config.ts, splash index.mdx) plus all content. Fully deletes and rebuilds outputs/starlight/.
   • "Content only" → --mode content-only — regenerates only src/content/docs/**, public/assets/**, and a SIDEBAR-SNIPPET.md with the sidebar config to paste in. Leaves any existing scaffold files (package.json, astro.config.mjs, tsconfig.json, content.config.ts, index.mdx) untouched — use this if the user is dropping the output into a Starlight project they already maintain elsewhere.

2. Meta pages:

   • "Include them" → add --include-meta — publishes wiki/log.md as a Change Log page and wiki/error-book.md as an Error Book page.
   • "Exclude them" → omit the flag — only entities, sources, graph, and overview get published.

Step 2 — Run the script

From the repository root:

python3 "<skill-dir>/scripts/export_starlight.py" --mode <full|content-only> [--include-meta]

Resolve <skill-dir> to this skill's own directory. Optional extra flag: --site-title "Custom Title" overrides the auto-derived site title (which otherwise comes from wiki/overview.md's H1 — a serviceable but generic default like "Knowledge Base Overview"). Consider offering this to the user rather than always silently accepting the default, since it's the one piece of branding a reader sees first.

Step 3 — Relay the script's report

The script prints, and you should summarize back to the user:

• Mode used and page count exported.
• Assets (images) copied.
• Which meta pages were skipped (if --include-meta was omitted).
• Any unresolved [[wikilinks]] (bare wikilinks with no matching page title — these get silently degraded to plain text in the output; a small number is normal wiki-content noise, but flag the list so the user can fix the source page if it's not).
• Any broken internal links the validation pass found (a link that was rewritten to a route with no corresponding generated file) — this is a real problem in the source wiki/ content (a stale or malformed cross-reference), not a bug in the export, and is worth reporting back as something to fix at the source.
• A reminder that outputs/starlight/ has been regenerated on disk but not staged, committed, or npm installed — those are separate steps for the user. For --mode full, the site is immediately runnable with cd outputs/starlight && npm install && npm run dev.

What the transform does (for context, not something you need to re-derive)

• Frontmatter: tldr → description; the first # H1 in the body becomes Starlight's required title (and is removed from the body, since Starlight renders title as the page heading itself — leaving the H1 in would duplicate it). type/confidence/quality/retention/ last_updated/resource have no native Starlight field, so they're rendered as a :::note[Knowledge base metadata] aside at the top of the page body instead of being dropped.
• Badges: a page gets a sidebar.badge — "Superseded" (if superseded_by is set), else "Stale" (if last_updated + freshness_window_days has elapsed), else "Low confidence" (if confidence < 0.5) — priority in that order, one badge max.
• Links: dual-linked cross-references ([text](path) ([[Wikilink]]), or the older [[Wikilink]] / [text](path) ordering) collapse to just the markdown link, since Starlight has no wikilink concept. Bare [[Wikilinks]] are resolved against every page's H1 title and converted to a proper link where a match exists, otherwise degraded to plain text. Root-absolute /wiki/... links become site routes (/wiki/entities/foo.md → /entities/foo/; a link to a directory's index.md maps to the bare directory route, e.g. /entities/). linked/.../libs/... cascade references (pointing outside any self-contained export) become plain text noting the path, not a broken link.
• Assets: person photos referenced as ../assets/people/x.jpg are copied to public/assets/people/x.jpg and rewritten to /assets/people/x.jpg.
• Graph: wiki/graph/edges.json is not copied verbatim (Starlight doesn't render JSON as a page) — its content is fully rendered as a Markdown table appended to graph/index.md, sorted by from, so no information is lost.
• Sidebar: one autogenerate group per top-level wiki/ subdirectory (so new pages added to entities//sources/graph/any future topic folder show up automatically on the next export without touching the sidebar config), plus explicit entries for the handful of root-level pages (Overview, the routing table, and the two optional meta pages).

Edge cases

• A future wiki/<newtopic>/ subdirectory: handled automatically — the script discovers top-level wiki/ subdirectories dynamically and adds a sidebar autogenerate group for each; no script changes needed.
• Re-running with no wiki changes: should produce byte-identical output (directory listings are sorted before writing). If asset copying or link rewriting ever introduces nondeterminism, that's a bug in the script, not expected behavior.
• A wiki page with no tldr: description is simply omitted from that page's frontmatter — Starlight tolerates a missing description.
• A wiki page with no H1: falls back to a slugified filename as the title (e.g. foo-bar.md → "Foo Bar"), same fallback rule ckb-export-okf uses.

---

Licensed under the Apache License, Version 2.0 — see LICENSE at the repository root, or http://www.apache.org/licenses/LICENSE-2.0.