ckb/.agents/skills/ckb-export-starlight/SKILL.md
Michał Kopeć bf2cc8e8aa Template 1.23.0: agent-knowledge release 2, schema 1.6
Schema 1.6, all fields optional (D-0014):
- F7 review: `review: draft|reviewed|needs_update`, `reviewed_by`,
  `reviewed_on`; lint check 17 and a review queue; ckb-lint marks reviews
- F4 `> CONTRADICTION:` marker, lint check 18; validity dates deferred
- F21 `tags` against the new `wiki/tags.md`, lint check 19,
  retrieve_candidates.py --tag, DRAFT/NEEDS_UPDATE flags
- F9 profiles in workload/profiles/, protected `## Rules` on project
  scope pages, precedence AGENTS.md > Rules > profile
- F8 explicit lessons (profile or wiki/lessons.md); new ckb-profile skill

Carry-over: `.secrets-allow` `<glob> match:<hash>` entries (also in the
bash/PowerShell fallbacks); open threads no longer print twice.
ckb-upgrade migrates 1.5 -> 1.6; init/reset know tags.md; Starlight
shows review and tags. Smoke test covers a 1.6 KB. Docs in EN and PL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-02 20:06:02 +01:00

123 lines
6.4 KiB
Markdown

---
name: ckb-export-starlight
description: Export wiki/ into an Astro + Starlight-consumable form at outputs/starlight/, producing a human-readable documentation website. Use for "export the wiki to Starlight", "generate the docs site", "build a human-readable wiki site", or "publish the knowledge base as a website".
---
# Export to Astro Starlight skill
## Purpose
One-way and on demand: `wiki/` stays authoritative, `outputs/starlight/` is
derived, never hand-edited, never fed back in. A deterministic script does
the transform; the model asks the two setup questions below, invokes it, and
relays its report. Human-readable counterpart of `ckb-export-okf`.
## 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:
```bash
<python> "<skill-dir>/scripts/export_starlight.py" --mode <full|content-only> [--include-meta]
```
Resolve `<skill-dir>` to this skill's own directory and `<python>` per
"Scripts and the Python Runtime" in `AGENTS.md`. **Python 3.8+ is a hard
requirement here** (and Node.js to build the site afterwards) — there is
no manual fallback. If no interpreter is found, stop before asking the
setup questions, say so, and point to "Prerequisites" in `docs/MANUAL.md`.
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 install`ed — 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`/`review`/`tags`/`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 "Needs update" (if
`review: needs_update`), 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
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
[`references/edge-cases.md`](references/edge-cases.md). Read that file when a
run hits something the steps above don't cover; don't load it otherwise.