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.
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.
1---2name: knowledge-graph3description: "Build + keep-fresh + query a deterministic code knowledge graph to cut agent orientation-token cost. Triggers: knowledge graph, graphify, code graph, god nodes, orientation cost, token bill, map the codebase, what connects X to Y, callers of, blast radius."4allowed-tools: Read, Bash, Grep, Glob5kernel:6 kind: methodology7 version: 18 side_effects: filesystem9 confirmation: none10---1112<skill id="knowledge-graph">1314<purpose>15An agent's token bill splits into ORIENTATION (finding where the answer lives — reading16files, following imports, grepping) and REASONING (actually solving). On a large, tangled17repo the orientation half dominates, and it is pure overhead: the model is not thinking yet,18it is still navigating. A pre-built code knowledge graph replaces that file-crawl with one19query, so you pay orientation tokens once (at build) instead of every session.2021The saving is CONDITIONAL on repo size × tangle, not a fixed multiplier. Measured on real22repos: ~5.7x fewer tokens/query on a mid-size service, ~73x on a large interconnected one,23~13% on a tiny library. The graph query cost is ~constant; naive full-corpus cost scales with24size — so reduction = corpus ÷ constant. Do the arithmetic on YOUR repo, don't quote a headline.2526Hard boundary: the graph helps NAVIGATION, not REASONING. "Design a cache", "why is this slow"27get zero lift. It gathers context efficiently; it does not think for the model.28</purpose>2930<prerequisite>31Uses `graphify` (open-source, tree-sitter + NetworkX, MIT). Code extraction is local +32deterministic + free (no API key). Install once: `uv tool install graphifyy` (or `pipx`/`pip`).33If graphify is absent, this skill degrades to a no-op — never a hard failure.34</prerequisite>3536<build>37Code-layer graph (free, offline, seconds):38```bash39graphify extract <path> --code-only # local AST only; skips docs; no LLM, no cost40```41Outputs `graphify-out/graph.json` (+ report; +interactive graph.html under ~5000 nodes).42NEVER commit `graphify-out/` — it is DERIVED. Gitignore it and rebuild on demand43(the sqlite-mirror discipline: commit the source, rebuild the artifact).44</build>4546<query>47```bash48graphify query "what connects auth to the database?" # BFS over the graph, token-budgeted49graphify path "UserService" "DatabasePool" # shortest path between two symbols50graphify god-nodes --top 12 # architectural hubs (most-connected)51graphify affected "RateLimiter" # reverse traversal = change blast radius52graphify benchmark # measure YOUR token reduction, per question53```54`god-nodes` doubles as a comprehension + pruning lens: hubs are the real spine; low-degree,55never-linked nodes are dead-code / consolidation candidates. Also available as an MCP server56(`query_graph`, `shortest_path`, `get_neighbors`) for repeated structured access.57</query>5859<automatic>60The graph pays off only if it is CONSULTED. A skill telling the agent to reach for it is opt-in61and unreliable, so the orientation layer is AMBIENT: when the working repo has a graph, the62session-start hook injects its architectural spine (top god-nodes + the query commands) directly63into context — the agent boots already oriented, no tool call, no human ask. Deep on-demand64queries ("what calls this exact function") still go through `graphify query`/`path`/`affected`65or the MCP tools; those are available + steered, but the baseline map arrives for free.66</automatic>6768<continuous>69A stale graph is worse than none. Keep it fresh, cheaply:70- **Code layer (free):** `graphify extract <path> --code-only` is incremental via its AST cache71 ("N cached/unchanged, 0 re-extracted"). Wire it into `post-commit` so the graph is never more72 than one commit stale, at ~zero cost. Opt-in installer: `hooks/scripts/knowledge-graph.sh install`73 (gated on `KERNEL_GRAPH_ON=1`, mirroring autopush — never stamps hooks by surprise).74- **NEVER `graphify update`** for the code graph: it re-scans ALL files and adds docs as bare75 nodes (measured 1506 → 13156 on one tree). Always `extract --code-only`.76- **Doc/semantic layer** (summaries, tags, prose edges) needs a model and is OPTIONAL polish.77 Run it incrementally (changed files only), never full-corpus, never on every commit. Local78 models are "good enough for orientation, not a top-tier artefact"; a frontier model is sharper.79</continuous>8081<boundaries>82- Free + deterministic is the CODE layer only. The doc/paper/image "why" layer sends semantic83 descriptions (never raw source) to a configured backend — that costs a model.84- Small or reasoning-heavy repos: the graph is a solved problem you did not have. Skip it.85- The graph is a comprehension artefact that also saves tokens — value it as a map first.86</boundaries>8788</skill>
hashgraph-online