Problem
Currently, there's MCP with endpoints descriptions, that does not cover some use cases. Agent sometimes goes misusing. And it's not about the bugs, it's about poor documentation for agent.
Proposal
Create skill (or few skills each for different toolset: explore-only or using separate tools) that is built by users experience. Edge-cases, gotchas and workarounds that people face and report can be added to that skill.
Why
I had to create my own skill to make agent work better with codegraph. Here's an example:
# Codegraph Usage
## Nested types
`codegraph` does NOT traverse nested struct types transitively. When searching usage of a composite struct, use a two-step approach:
1. Query the parent struct → extract nested type names from the source code in the response.
2. Query again with all nested types explicitly listed (e.g. `"config.Log config.S3 config.S2S config.Stages"`).
Do NOT fall back to grep/read for this — codegraph already returns the struct definition with nested type names in step 1.
## Impact analysis
`codegraph_impact` answers the question "what depends on this symbol?". Use it whenever you need that answer — planning a change, answering a question, or evaluating risk. Not only for refactor.
Do not reconstruct this by reading source files and tracing callers manually. `codegraph_impact` does this in one call and covers transitive dependencies that manual tracing misses.
`codegraph_impact` vs `codegraph_callers`: `codegraph_impact` answers "What depends on X transitively?", `codegraph_callers` shows only direct callers.
## Limitations
Structural search only. The graph knows calls and imports, but does NOT understand semantics. "Find code conceptually similar to X" is NOT its job — use another approach for semantic/conceptual search.
Note: ## Nested types is probably fixed in #1064, the skill was written before (actual for v1.1.3)
Collecting more user experience we can improve tool usage by agents.
Also: codegraph a bit lacks documentation for human: concrete cases what is this tool for, and the main thing, what it is NOT for
Problem
Currently, there's MCP with endpoints descriptions, that does not cover some use cases. Agent sometimes goes misusing. And it's not about the bugs, it's about poor documentation for agent.
Proposal
Create skill (or few skills each for different toolset: explore-only or using separate tools) that is built by users experience. Edge-cases, gotchas and workarounds that people face and report can be added to that skill.
Why
I had to create my own skill to make agent work better with codegraph. Here's an example:
Collecting more user experience we can improve tool usage by agents.
Also: codegraph a bit lacks documentation for human: concrete cases what is this tool for, and the main thing, what it is NOT for