Knowledge Graph

<skill id="knowledge-graph">

<purpose>
An agent's token bill splits into ORIENTATION (finding where the answer lives — reading
files, following imports, grepping) and REASONING (actually solving). On a large, tangled
repo the orientation half dominates, and it is pure overhead: the model is not thinking yet,
it is still navigating. A pre-built code knowledge graph replaces that file-crawl with one
query, so you pay orientation tokens once (at build) instead of every session.

The saving is CONDITIONAL on repo size × tangle, not a fixed multiplier. Measured on real repos: ~5.7x fewer tokens/query on a mid-size service, ~73x on a large interconnected one, ~13% on a tiny library. The graph query cost is ~constant; naive full-corpus cost scales with size — so reduction = corpus ÷ constant. Do the arithmetic on YOUR repo, don't quote a headline.

Hard boundary: the graph helps NAVIGATION, not REASONING. "Design a cache", "why is this slow" get zero lift. It gathers context efficiently; it does not think for the model. </purpose>

<prerequisite> Uses graphify (open-source, tree-sitter + NetworkX, MIT). Code extraction is local + deterministic + free (no API key). Install once: uv tool install graphifyy (or pipx/pip). If graphify is absent, this skill degrades to a no-op — never a hard failure. </prerequisite>

<build>
Code-layer graph (free, offline, seconds):
```bash
graphify extract <path> --code-only        # local AST only; skips docs; no LLM, no cost
```
Outputs `graphify-out/graph.json` (+ report; +interactive graph.html under ~5000 nodes).
NEVER commit `graphify-out/` — it is DERIVED. Gitignore it and rebuild on demand
(the sqlite-mirror discipline: commit the source, rebuild the artifact).
</build>

<query>
```bash
graphify query "what connects auth to the database?"      # BFS over the graph, token-budgeted
graphify path "UserService" "DatabasePool"                # shortest path between two symbols
graphify god-nodes --top 12                                # architectural hubs (most-connected)
graphify affected "RateLimiter"                            # reverse traversal = change blast radius
graphify benchmark                                         # measure YOUR token reduction, per question
```
`god-nodes` doubles as a comprehension + pruning lens: hubs are the real spine; low-degree,
never-linked nodes are dead-code / consolidation candidates. Also available as an MCP server
(`query_graph`, `shortest_path`, `get_neighbors`) for repeated structured access.
</query>

<automatic>
The graph pays off only if it is CONSULTED. A skill telling the agent to reach for it is opt-in
and unreliable, so the orientation layer is AMBIENT: when the working repo has a graph, the
session-start hook injects its architectural spine (top god-nodes + the query commands) directly
into context — the agent boots already oriented, no tool call, no human ask. Deep on-demand
queries ("what calls this exact function") still go through `graphify query`/`path`/`affected`
or the MCP tools; those are available + steered, but the baseline map arrives for free.
</automatic>