- Skills: descriptions cut to routing-hint length (1925w -> 840w), Trigger
phrases removed, Purpose collapsed, Edge cases moved to references/.
- Rule B names the decisions-log exception; "Sync the wiki" trigger dropped;
reserved sections "Four" -> "Three"; directory contract adds ckb.yaml,
docs/, tests/.
- MANUAL/CHANGELOG/OPENSPEC (EN+PL) moved to docs/; template ADRs D-0001 and
D-0002 restored from 0c06cb6 into docs/decisions/; referrers repointed.
- ckb-retrieve: rank fusion moved into scripts/retrieve_candidates.py;
Purpose states the one write it owns (query-gaps).
- tests/: fixture KB, golden JSON, smoke.sh.
- Scaffold: overview.md describes content not schema; graph/index.md names
base skills only; query-gaps.md loses its self-rotting freshness window.
- README/MANUAL/OPENSPEC/CHANGELOG ghost-writer pass in both languages.
- VERSION 1.9.0 -> 1.10.0.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
5.6 KiB
| name | description |
|---|---|
| ckb-onboard-me | Walk the wiki knowledge graph for a topic and print a guided reading order — a short overview plus the best sequence of pages to read, prerequisites first. Use for "onboard me on X", "where do I start with X", "walk me through X", "mini tour of X", or "what should I read to understand X". |
Onboard me (guided wiki tour) skill
Purpose
Turn a topic into a reading order: a short scene-setting overview followed by an ordered list of wiki pages, each with a one-line note on what you'll find there and why it comes at that point. Built by walking the knowledge graph outward from the topic — foundations first, then the topic, then what builds on it.
Read-only. Never writes to wiki/, so it never touches wiki/log.md. It
synthesizes a route through existing knowledge; it adds no new claims. If the wiki has
nothing on the topic, say so — don't invent a tour.
How to run this skill
Step 1 — Resolve the topic to a starting page
Read the cheap indexes first, in cascade order (first match wins):
wiki/index.md— match the topic against the Use when column.wiki/entities/index.md— match against entity titles and theirtldr.- If nothing local matches, check each
linked/<name>/index, then eachlibs/<name>/index (alphabetical). The localwiki/always wins if both have a candidate.
Pick the single best-matching page as the anchor of the tour.
- No match anywhere — tell the user the wiki has nothing on that topic
yet. Offer the closest 2–3 pages by title/
tldrif any are vaguely related, and suggest running Ingest to add the material. Do not fabricate a tour. - Several equally good anchors — list them (title +
tldr) and ask which one to start from, or offer to build a short tour that covers all of them.
Step 2 — Walk the graph outward from the anchor
Read wiki/graph/edges.json. Edges are typed relationships between entity
pages (uses, depends_on, caused, contradicts, supersedes) with a
source and a target. Starting from the anchor, do a breadth-first walk:
- Collect every page directly connected to the anchor (anchor is
sourceortargetof the edge). - Follow one more hop out from those pages. Stop at 2 hops — a tour is a route, not the whole map. Keep a visited set so cycles don't loop.
- Cap the tour at roughly 8 pages. If the 2-hop neighbourhood is larger,
keep the pages closest to the anchor and highest
confidence/retention: high, and tell the user you trimmed it (say how many were left out) rather than silently dropping them.
If edges.json is missing or empty (no ingest has extracted edges yet),
fall back to link-following: read the anchor page and collect the pages it
links to via [[wikilinks]] and [markdown](path.md) links, then one hop out
from those. Same 2-hop, ~8-page, visited-set rules apply. Note in the output
that ordering came from page links rather than the typed graph.
Step 3 — Order the pages pedagogically
The reading order is the whole point — don't just dump the neighbourhood. Order by dependency direction, not by hop distance alone:
- Foundations first. A page the anchor
depends_onorusesis a prerequisite — it comes before the anchor. Recurse: a prerequisite's own prerequisites come before it. - The anchor — the topic itself, once its groundwork is laid.
- Builds-on / related — pages that
depend_onorusethe anchor, or are related without a clear dependency, come after. These are "where to go next." - Put
contradicts/superseded_bylinks near the page they qualify, with a note that they offer a competing or newer view.
Within a tier, order by confidence then last_updated (higher/newer first)
so the most solid reading comes first. Read each page's tldr (frontmatter)
to write its one-line "what you'll find" — only open the body if the tldr is
missing or too thin to describe the page.
Step 4 — Print the tour
Print to chat (this skill produces a message, not a file). Use this shape:
## Guided tour: [Topic]
[2–3 sentence overview: what the topic is and what this tour will teach you,
synthesized from the anchor page's tldr and its immediate context.]
**Reading order:**
1. **[Page title](wiki/entities/foo.md)** — *foundation.* [what you'll find,
and why it's first — e.g. "the concept everything here builds on."]
2. **[Page title](wiki/entities/bar.md)** — *the core.* [what you'll find.]
3. **[Page title](wiki/entities/baz.md)** — *builds on it.* [what you'll find.]
...
**After this you'll understand:** [one line on the payoff — what the reader
can do or reason about once they've read the sequence.]
Rules for the output:
- Use clickable markdown links to the actual pages (project-root-relative,
e.g.
wiki/entities/foo.md), so the reader can jump straight in. - Label each step with its role in the tour (foundation / core / builds on it / alternative view) so the ordering logic is visible.
- Keep each "what you'll find" to one line, drawn from the page's
tldr. - If pages came from
linked/orlibs/, link them with their full cascade path and mark them as upstream.
Step 5 — Offer follow-ups
Close with a short offer: to go deeper on any single step, to widen the tour (3+ hops), or to start a different topic. Don't act on these unless asked.
Edge cases
Unusual situations — an empty target, a partial run, a conflicting state,
a missing dependency — are catalogued in
references/edge-cases.md. Read that file when a
run hits something the steps above don't cover; don't load it otherwise.