docs: add community usage skill (codegraph-usage) — #1097#1117
Conversation
Field guide collecting community-reported usage patterns: tool selection (impact vs callers), what CodeGraph is not for, staleness banner semantics, monorepo projectPath, CLI-in-container workflow, and over-calling guidance. Addresses colbymchenry#1097
| description: Community field guide for working with CodeGraph effectively — when to reach for it, which tool answers which question, known gotchas and workarounds, and what CodeGraph is NOT for. Use when working in a repo that has a .codegraph/ index, or when CodeGraph tool calls return confusing or incomplete results. | ||
| --- | ||
|
|
||
| # CodeGraph usage — community field guide |
There was a problem hiding this comment.
I think agent should not know about community, I would remove all mentions
| @@ -0,0 +1,120 @@ | |||
| --- | |||
| name: codegraph-usage | |||
| description: Community field guide for working with CodeGraph effectively — when to reach for it, which tool answers which question, known gotchas and workarounds, and what CodeGraph is NOT for. Use when working in a repo that has a .codegraph/ index, or when CodeGraph tool calls return confusing or incomplete results. | |||
There was a problem hiding this comment.
To make trigger work, agent should check for .codegraph existence. My experience is that agents go lazy especially for skill usage. Better - "Always use before any codegraph tool call. Also use when codegraph return confusing or incomplete results"
The best approach for modal monoliths with separate .codegraph dirs is explicitly tell in AGENTS.md what modules use codegraph and tell to use codegraph here for code exploration. This should be documented as skill usage for users.
My main idea - force reading the skill BEFORE tool call, when agent wants to use it. Skill contain prevent conditions that must be read by agent before it actually makes the call.
My AGENTS.md instruction btw: Before calling any codegraph tool, load and read the codegraph skill first. No exceptions.. It works
| grep + read loop with a single round-trip. | ||
|
|
||
| This skill collects usage patterns, gotchas, and workarounds reported by real | ||
| users. It complements (does not replace) the MCP server instructions. |
There was a problem hiding this comment.
I think It complements (does not replace) the MCP server instructions. is enough
|
|
||
| The default MCP surface is `codegraph_explore` alone; the narrower tools below | ||
| are available via the CLI (`codegraph <command>`) and re-enablable over MCP | ||
| with `CODEGRAPH_MCP_TOOLS`. |
There was a problem hiding this comment.
This is MCP setting made by human. Agent see eithter only explore or other tools user configured. This is unnecessary info for agent
| | You want to know | Use | Not | | ||
| |---|---|---| | ||
| | Almost anything: how X works, where X is, survey an area | `explore` | grep + read loop | | ||
| | One symbol's source + direct callers | `node` | reading the whole file | |
There was a problem hiding this comment.
maybe "full source code?". Just to be more prescise. + should add that node is not replacement for read, maybe not here, as a separate statement
| before every minor edit). Rule of thumb: call when you have a genuine | ||
| structural question, not as a reflex before every change. | ||
|
|
||
| ### Trust results — don't re-verify with grep |
There was a problem hiding this comment.
Think should focus on avoiding re-verifying results already provided by codegraph - reading the same but with grep. Why: this instruction looks like a strict rule to fully rely on codegraph's results. If there's a bug in codegraph that make result more poor (I faced, but already fixed), agent should fallback to grep for symbols codegraph didn't provide. + on large codebase blast radius is truncated with "+N more". Agent can trust what it see from codegraph but search for missing.
This is not critical, need to debate over this. Maybe I'm wrong
| Disambiguate by adding the file path or a neighboring symbol to the query | ||
| rather than picking the first result. | ||
|
|
||
| ### Monorepos: pass projectPath |
There was a problem hiding this comment.
Already fixed. Can be removed. Codegraph now force projectPath as required in schema if no .codegraph dir found. Works, confirmed: I use mcpjungle as mcp gateway, the place where server started obviously has no .codegraph dir, but agent always work as expected
| still work per project — pass `projectPath` pointing into any directory that | ||
| has an index. No restart needed after a new `codegraph init`. | ||
|
|
||
| ### Containers & subagents: use the CLI, skip MCP |
There was a problem hiding this comment.
Does agent have knowledge about how it's subagents are run? Maybe that's separate skill for those who use same approach?
|
|
||
| ### Index freshness outside agent sessions | ||
| The file watcher keeps the graph current (~1s lag) during normal sessions. | ||
| When scripting against the index (CI, hooks, containers), run |
There was a problem hiding this comment.
Didn't understand that, could you explain more detailed what conditions match sync problem?
| there for the rest of the session and use built-in tools. Indexing is the | ||
| user's call — suggest `codegraph init` if relevant, don't run it yourself. | ||
|
|
||
| ## Contributing to this skill |
There was a problem hiding this comment.
This is definetely not agent instruction. Instead, you can instruct agent to report tool misuse and offer to create issue. But I think this should be moved completely outside into user's reference for using the skill. This is context noise
- Reframe as an agent-facing playbook read before using CodeGraph; drop the community/contributing framing and meta. - Remove the projectPath monorepo workaround (now enforced by the tool schema) and the container/subagent and offline-sync sections (user setup, not agent guidance). - Note tool availability depends on MCP config; mark 'affected' as CLI-only. - Clarify 'node' is not a substitute for 'read' on unindexed files. - Soften 'trust results': don't re-verify what CodeGraph returned, but fall back to grep/read for a truncated blast radius or a symbol it didn't cover.
|
Thanks for the detailed review. I pushed a rework that leans into the "agent-facing, read before use" framing you're pointing at. What I took directly:
Two I want to check before hard-coding:
@colbymchenry, the trigger question is the one design call that shapes the rest, so I'd value your read on it. |
2 participants
Summary
Adds
skills/codegraph-usage/SKILL.md— the community field guide proposed in #1097: an agent-agnostic skill collecting real-world usage patterns, gotchas, and workarounds so agents (and humans) use CodeGraph well.Covers:
explore/node/query/callers/callees/impact/affected/files, including the most common mixup:impact(transitive blast radius) vscallers(one hop).exploreon small tasks (Frequent codegraph_explore calls in v1.16 make Codex slow for small tasks #1080, Codegraph consume more tokens than just talk to claudecode. #975), per-file vs global staleness banner semantics, overloaded symbol disambiguation,projectPathin monorepos, CLI-without-MCP for containers/subagents (add CLI skills #676), index freshness when scripting (syncvsindex).Content is grounded in
src/mcp/server-instructions.tsandsite/src/content/docs/reference/cli.md— no invented commands or behavior.Complements (doesn't overlap) #1019, which wraps the CLI surface itself; this one is usage guidance for the toolset.
Closes #1097
Testing
.claude/skills/*/SKILL.mdformat.