code-navigation
CodeGraph-first code navigation with LSP and grep fallback. Provides agents with a reusable strategy for semantic code exploration -- codegraph tools when available, LSP goToDefinition/findReferences/documentSymbol otherwise, grep as last resort.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 1.6k
- Forks
- 491
01 前言 Front Matter
- name
- code-navigation
- description
- CodeGraph-first code navigation with LSP and grep fallback. Provides agents with a reusable strategy for semantic code exploration -- codegraph tools when available, LSP goToDefinition/findReferences/documentSymbol otherwise, grep as last resort.
- user-invocable
- false
02 资源文件 1
- 参考文档TEST-PLAN.md2.2 KB
03 SKILL.md 正文
Code Navigation
Reference skill for agents that search the broader codebase. Defines when to use LSP vs Grep/Glob and how to handle fallback.
Navigation Hierarchy
Three tiers, highest precision first. Use the highest available tier for each operation.
| Tier | Tools | Available When | Best For |
|---|---|---|---|
| CodeGraph | codegraph_search, codegraph_context, codegraph_callers, codegraph_callees, codegraph_impact, codegraph_node |
.codegraph/ exists in project root |
Symbol lookup, task-relevant files, call chains, change impact |
| LSP | goToDefinition, findReferences, documentSymbol |
Language server installed | Definition jump, reference finding, file structure |
| Grep/Glob/Read | Pattern matching + file reads | Always | File discovery, text patterns, config files, non-code content |
CodeGraph Operation Catalog
Six semantic operations. For file discovery and text patterns, use Grep/Glob regardless of CodeGraph.
| Operation | Use When |
|---|---|
codegraph_search |
Find symbols by name (functions, classes, types) |
codegraph_context |
Get relevant code context for a task description |
codegraph_callers |
Find what calls a function |
codegraph_callees |
Find what a function calls |
codegraph_impact |
Assess what is affected by changing a symbol |
codegraph_node |
Get details and source code for a specific symbol |
LSP Operation Catalog
Three semantic operations where LSP outperforms grep. For everything else, use Grep/Glob/Read directly.
| Operation | Use When | Grep Fallback |
|---|---|---|
goToDefinition |
Find where a function, class, or type is defined | Grep for function {name}, class {name}, def {name}, const {name} |
findReferences |
Find all callers or consumers of a symbol | Grep for the symbol name (noisier -- includes comments, strings, partial matches) |
documentSymbol |
Get a structural overview of a file's exports and symbols | Read the file and parse manually |
Not covered by this skill (Grep/Glob is already sufficient):
- File discovery -- use Glob
- Text pattern matching -- use Grep
- Content reading -- use Read
Agent Instructions Block
Agents that search the broader codebase should include this block in their prompt. The dispatching skill passes codegraph_available: true|false and lsp_available: true|false as part of the agent's context.
## Code Navigation Strategy
You have been provided `codegraph_available` and `lsp_available` flags in your context.
**When `codegraph_available: true`:**
- First, load codegraph tool schemas by calling ToolSearch with query `"select:mcp__codegraph__codegraph_search,mcp__codegraph__codegraph_context,mcp__codegraph__codegraph_callers,mcp__codegraph__codegraph_callees,mcp__codegraph__codegraph_impact,mcp__codegraph__codegraph_node"`. Codegraph tools are deferred and cannot be called without this step.
- For finding symbols by name: use codegraph_search first.
- For understanding what code is relevant to a task: use codegraph_context first.
- For finding callers of a function: use codegraph_callers first.
- For finding what a function calls: use codegraph_callees first.
- For assessing change impact: use codegraph_impact first.
- For getting source code of a specific symbol: use codegraph_node.
- If codegraph returns insufficient results, fall through to LSP (if available) then grep.
- For file discovery and pattern matching: always use Grep/Glob regardless of codegraph.
**When `codegraph_available: false` and `lsp_available: true`:**
- For finding where a function/class/type is defined: use LSP goToDefinition first.
- For finding all callers or consumers of a symbol: use LSP findReferences first.
- For getting a structural overview of a file: use LSP documentSymbol first.
- If LSP returns empty or unhelpful results for any operation, inform the user:
"LSP returned no results for {operation} on `{symbol}` -- falling back to grep-based search."
Then use the grep equivalent from the catalog above.
- For file discovery and pattern matching: always use Grep/Glob regardless of LSP availability.
**When both unavailable:**
- Use Grep, Glob, and Read for all code navigation.
Skill-Level Navigation Detection
Skills that dispatch code-exploration agents (/plan, /quiver:review) run this detection once before agent dispatch. Results are passed as codegraph_available and lsp_available flags to quiver:code-navigator and other agents that search the codebase.
CodeGraph Detection Flow
- Check if
.codegraph/directory exists at project root. - If exists: set
codegraph_available=true. - If not: set
codegraph_available=false. No user prompt -- CodeGraph is a passive enhancement. - Pass
codegraph_availablealongsidelsp_availableto all dispatched agents.
LSP Detection Flow
-
Check project memory for cached LSP preference.
- If
lsp_confirmedfound: setlsp_available=true, skip to step 4. - A negative result is never cached (see step 3), so nothing else short-circuits here.
- If
-
Attempt an LSP probe.
- Try a lightweight LSP call (e.g.,
documentSymbolon any source file from the project root). - If LSP responds with results: set
lsp_available=true, cachelsp_confirmedin project memory, skip to step 4.
- Try a lightweight LSP call (e.g.,
-
LSP not available -- continue with grep.
-
Set
lsp_available=false. -
Detect the project language from manifest files (
package.json,Gemfile,requirements.txt,pubspec.yaml,go.mod,Cargo.toml,Package.swift, etc.) and print one line naming the recommended server from the table below:> LSP not available; using grep. Install {recommended_server} for {language} to enable go-to-definition and find-references. -
No
AskUserQuestion. LSP is an enhancement, and a question here stops every skill that runs detection, including one another skill invoked with no user at the prompt. Do not cache the negative result: the probe is a single call, and a server installed later is picked up by the next run.
-
-
Pass
lsp_availableflag to all dispatched agents as part of their context.
Language Server Recommendations
| Language | Recommended Server | Install Command |
|---|---|---|
| TypeScript/JavaScript | typescript-language-server | npm install -g typescript-language-server typescript |
| Python | pyright | npm install -g pyright or pip install pyright |
| Go | gopls | go install golang.org/x/tools/gopls@latest |
| Rust | rust-analyzer | Install via rustup or IDE extension |
| Swift | sourcekit-lsp | Included with Xcode |
| Dart/Flutter | dart language-server | Included with Dart SDK |
| Ruby | solargraph | gem install solargraph |
| Java/Kotlin | jdtls | Install via IDE or manually |
Memory Caching
LSP preference is stored in project memory:
- File:
lsp_preference.mdin the project's auto-memory directory - Content:
lsp_confirmed, which language server responded, date cached. Only a successful probe is written; an absent server is re-probed on every run. - Lifetime: Persists across sessions. User can reset by saying "forget LSP preference" or by removing the file; installing a server needs no reset.
For Agent Authors
If your agent searches the broader codebase (beyond files it already knows about), reference this skill:
- Add the Code Navigation Strategy block from above to your agent's prompt.
- Ensure the dispatching skill passes
codegraph_availableandlsp_availablecontext to your agent. - Your agent does NOT need to handle LSP detection -- that is the skill's responsibility.
Locate vs Map
Two agents serve code navigation. Pick by output need:
| Job | Agent | Output |
|---|---|---|
| Where is X defined / what calls Y / list uses of Z / map a directory / verify a path | quiver:code-locator |
Compressed path:line -- symbol -- note table |
| Conventions, patterns, planning context, feature impact | quiver:code-navigator |
Structured file:role:pattern report with Key Conventions and Gaps |
Both agents use the tier strategy from this skill (codegraph -> LSP -> grep). code-locator runs on haiku and refuses convention extraction; code-navigator runs on inherit and emits the full map /plan consumes.
04 同仓库更多 Skills
worktable-review-with-annotations
Create, inspect, reply to, update, or resolve situated Worktable annotations. Use when feedback belongs to a Doc section, block, text range, or HTML Doc, or when the user asks to address existing review feedback and coordinate a requested artifact edit.
worktable-find-and-synthesize-context
Find, assess, and synthesize context from Worktable Docs and Records. Use when the user asks what a workspace contains, wants workspace-backed research, needs current facts reconciled across artifacts, or requests a cited synthesis without changing workspace state.
worktable-create-or-update-docs
Create, edit, rename, or maintain narrative Worktable Docs. Use for plans, decisions, briefs, notes, research syntheses, and other durable prose when the user requests a new artifact or a safe update to an existing one.
worktable-create-or-manage-records
Organize repeated structured information as durable Worktable Records. Use for research datasets, inventories, directories, pipelines, trackers, and other collections whose items need identity, fields, filtering, links, validation, or individual updates.
worktable-create-or-manage-interactive-html
Create or improve durable visual and interactive artifacts in Worktable. Use for dashboards, trackers, calculators, mini apps, slide presentations, and other requests that benefit from a polished HTML Doc.
worktable-collaborate-threads
Read, answer, and hand off messages through durable Worktable threads with users or other authenticated participants. Use when the user asks to check addressed messages, reply to a participant, continue a thread, request another agent's help, wait briefly for a response, or watch for comments and messages sent to the agent.