docs: add community usage skill (codegraph-usage) — #1097

skills/codegraph-usage/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: codegraph-usage
+description: How to use CodeGraph well — which tool answers which question, when to reach for it and when not, and the gotchas that trip agents up. Read before using CodeGraph tools in a project that has a .codegraph/ index, and whenever a CodeGraph call returns confusing or incomplete results.
+---
+
+# Using CodeGraph
+
+CodeGraph is a local knowledge graph of a project's symbols, call edges, and
+files. One call returns verbatim line-numbered source plus the call paths
+between symbols and a blast-radius summary — replacing a grep + read loop with a
+single round-trip. Read this before reaching for CodeGraph so you pick the right
+call and avoid the mistakes below.
+
+## When to reach for it
+
+- "How does X work?" / "Where is X?" / "What happens when X runs?"
+- Before editing a symbol: source + callers + blast radius in one call.
+- Tracing a flow: name both endpoints in one query (e.g. `mutateElement renderScene`) —
+  it rides dynamic-dispatch hops (callbacks, re-renders) that grep can't follow.
+- Judging impact before a change, or when reviewing risk — not only your own refactors.
+
+## When NOT to
+
+- **Semantic/conceptual search.** It knows structure (calls, imports, definitions),
+  not meaning. "Code similar to X" or "where do we handle billing edge cases?" —
+  reason over results yourself or use plain search.
+- **Unindexed content.** Configs, docs, lockfiles, generated code — use Read/Grep.
+- **Trivial single-file edits.** If you know the exact file and line, editing
+  directly is faster than a graph round-trip.
+- **Correctness.** No type-checking or test-running here — the compiler, tests,
+  and linter still own "is this right?".
+
+## Which call answers which question
+
+Which tools you can reach depends on how CodeGraph was set up: the default MCP
+surface is `codegraph_explore` alone, other tools are enabled per config, and all
+of them exist as CLI subcommands (`codegraph <command>`). Use whichever is
+available — `explore` alone answers most questions.
+
+| You want | Use | Instead of |
+|---|---|---|
+| Almost anything: how X works, where X is, survey an area | `explore` | grep + read loop |
+| One symbol's full source + direct callers | `node` | reading the whole file |
+| "What calls X?" (direct, one hop) | `callers` | `impact` |
+| "What does X call?" | `callees` | reading X and grepping each name |
+| "What depends on X **transitively**?" (blast radius) | `impact` | chaining `callers` by hand |
+| Symbol lookup by name/kind | `query` | grep |
+| File/module layout of an area | `files` | `ls -R` + reading files |
+
+`node` returns a symbol's full source or a file's contents from the index — it is
+**not** a substitute for `read` on files CodeGraph doesn't cover.
+
+CLI-only (not an MCP tool): `codegraph affected <files...>` — which test files a
+change touches, without running the suite.
+
+**`impact` vs `callers` is the common mixup:** `callers` is one hop; `impact` walks
+the graph transitively. "What could break?" → `impact`.
+
+## Gotchas
+
+### Don't re-verify what CodeGraph returned — but do fill gaps
+
+Its results come from a full AST parse, so re-grepping the same symbols is slower
+and blinder (grep misses dynamic dispatch) — don't double-check what it gave you.
+It is **not** infallible, though: a blast radius may be truncated (`+N more`), and a
+symbol you expected may be missing. When you need more than it returned, fall back
+to grep/read for that gap — without discarding the parts it did provide. (The one
+case where its output itself is suspect: the staleness banner, below.)
+
+### Don't over-call on small tasks
+
+One `explore` usually answers the whole question — treat what it returns as already
+read. If the first call answered it, stop. Calling before every minor edit just
+burns tokens.
+
+### The staleness banner is per-file
+
+"⚠️ Some files referenced below were edited since the last index sync…" — only the
+**listed** files are stale; Read those directly and keep trusting the graph for the
+rest. The rarer "auto-sync is DISABLED" banner means the whole index is frozen —
+Read directly until it's resolved.
+
+### Same-named symbols
+
+A bare name that exists in several places returns every match. Disambiguate with a
+file path or a neighboring symbol rather than taking the first result.
+
+### Not indexed? Stop calling it
+
+If a tool reports no `.codegraph/` for a project, stop calling CodeGraph there for
+the rest of the session and use built-in tools. Indexing is the user's decision —
+mention `codegraph init` if it comes up, but don't run it yourself.