Kb Query

EXECUTE NOW

Query: $ARGUMENTS

Parse the query type and run the matching subcommand. The script lives at scripts/kb_graph_query.py and reads docs/assets/kb_graph.json (it will rebuild the graph automatically if the JSON is missing).

For free-text questions ("what is X about", "what's similar to X"), prefer info followed by related — info gives the description, related gives the neighborhood across all edge kinds including TF-IDF semantic suggestions.

Execution

Run the relevant subcommand as a single Bash invocation and return its output verbatim. Do not synthesize or summarize unless the user asked you to — the caller usually wants the raw structure.

python scripts/kb_graph_query.py <subcommand> <args>

If the user gave a free-text query ("tell me about delegation games"):

python scripts/kb_graph_query.py info delegation_games
python scripts/kb_graph_query.py related delegation_games

If the query is ambiguous (multiple title matches), the script prints the candidates and exits non-zero. Ask the user which one they meant, or pick the clearest exact match by id.

When to use this skill (and when not to)

Use kb-query when:

• You need to know what links to a doc/scenario/command/agent before renaming or deleting it.
• You want the shortest conceptual path between two ideas (introductions, related-work sections, onboarding paths).
• You're looking for semantically related pages that aren't explicitly linked yet (densification candidates, duplicate-content candidates).
• You want orphan pages for triage — by kind, by section.
• You want to navigate the corpus structurally instead of by full-text grep.

Don't use it when:

• You need the contents of a specific file you already know — just Read it.
• You want full-text occurrence counts of a phrase — use Grep.
• You need live state of a service or test run — the graph is a static snapshot of the markdown/code corpus.

Edge kinds in the graph

• link — explicit [text](path.md) markdown link
• wikilink — [[name]] resolved by filename stem
• mention — bare repo-relative path mention (scenarios/foo.yaml)
• slashcmd — /command-name reference resolving to a .claude/commands/ node
• code — mkdocstrings ::: swarm.x.y directive in api docs → source file
• semantic — TF-IDF cosine ≥ 0.18 suggestion; not a real corpus link. path and backlinks deliberately ignore semantic edges; related includes them so you can find topical kin.

See also

• scripts/build_kb_graph.py — regenerate the graph (run after large doc changes; the mkdocs hook does this automatically per build).
• scripts/build_kb_graph.py --check — CI gate that fails on new orphans not in .kb-graph-orphans.
• The /graph page in the rendered docs site — the interactive viz of the same data.