kb-visualize

name	kb-visualize
description	Render a knowledge bundle as an interactive graph — native UI where the host supports it, otherwise a self-contained HTML artifact.
disable-model-invocation	true

kb-visualize — see the bundle as a graph

Render a bundle as an interactive force-directed graph of its concepts, so a human can see its shape — hubs, clusters, orphans, and how concepts connect. You author the view from a deterministic graph model, so it can adapt to the request (a whole-bundle map, or a subgraph around one concept); it is not a fixed template.

1. Extract the graph model

Run the bundled extractor against the target bundle (default knowledge/):

python3 "${CLAUDE_SKILL_DIR}/scripts/graph.py" <bundle-dir>

It prints JSON: nodes (each with id, type, title, description, tags, resource, status, body, links, cited_by), the distinct types, and edges. Backlinks (cited_by) and edges are already computed from the cross-links in concept bodies. If the user scoped the request to one concept/area, filter the model to that node plus its neighbors.

Completion criterion: you have the graph model, and (if scoped) filtered it to the requested subgraph.

2. Choose the output form by host capability

• Host renders interactive UI (e.g. Claude Desktop, Codex Desktop, an MCP-Apps host): render the graph as native UI so it's live in the conversation.
• Host is text/artifact only (e.g. Claude Code, a terminal): write a self-contained HTML file (single file, no backend, CDN libs only) next to the bundle or as an artifact, and give the user the path.

If unsure whether the host renders UI, default to the HTML file — it works everywhere.

Completion criterion: the output form matches the host's capability.

3. Render the view

Whichever form, the view must show (mirroring a conformant OKF viewer):

• A force-directed graph: one node per concept, colored by type, directed edges from each cross-link. A layout the user can switch (e.g. cose / concentric / breadth-first / grid) is a plus.
• A detail panel for the selected node: its frontmatter (description, resource as a link, tags) and its rendered markdown body, with internal concept links rewired to navigate within the view (select that node) rather than following a file path.
• A "Cited by" list per node, from cited_by (the reverse link graph).
• A search box (matches title, id, tags) and a type filter.

For the HTML form, a proven stack is Cytoscape.js (graph) + marked (markdown) from a CDN, with the graph model inlined as a JSON literal so the file is self-contained and nothing leaves the page. All node data is already in the model from step 1 — do not re-read the bundle.

Completion criterion: the rendered view shows the graph (colored by type), a working detail panel with in-view link navigation, backlinks, search, and type filter.

4. Deliver

Hand over the result: for UI, the live view; for HTML, the file path (and note it can be committed next to the bundle, shared as an artifact, or hosted on any static file server). This is a read-only consumer — it never modifies the bundle, so no log entry.

Completion criterion: the user has the view or its path.