Agent skill
using-lsp-tools
Use when mcp-language-server tools are available and you need semantic code intelligence for navigation, refactoring, or type analysis
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/using-lsp-tools
SKILL.md
Using LSP Tools
Invariant Principles
- Semantic > Lexical: LSP understands scope, types, inheritance. Grep sees text.
- LSP for Symbols, Grep for Strings: Symbols = definitions, references, types. Strings = TODOs, comments, literals.
- Verify Before Fallback: Empty LSP result? Check file saved. Then try text-based.
- Atomic Operations Preferred:
rename_symbolhandles all files. Manual Edit misses references.
Reasoning Schema
Inputs
| Input | Required | Description |
|---|---|---|
filePath |
Yes | Absolute path to file being analyzed |
line |
Context | 1-indexed line number for position-based queries |
column |
Context | 1-indexed column for position-based queries |
symbolName |
Context | Fully-qualified name for definition/references |
language |
No | Language identifier if ambiguous |
Outputs
| Output | Type | Description |
|---|---|---|
| Symbol locations | Inline | File paths and positions from navigation queries |
| Type information | Inline | Hover/signature data for understanding |
| Refactoring edits | Applied | Direct code modifications from rename/actions |
| Diagnostics | Inline | Errors and warnings for debugging |
Tool Priority Matrix
| Task | LSP Tool | Fallback |
|---|---|---|
| Find definition | definition |
Grep func X|class X|def X |
| Find usages | references |
Grep symbol name |
| Understand symbol | hover |
Read + infer |
| Rename | rename_symbol |
Multi-file Edit (risky) |
| File outline | document_symbols |
Grep definitions |
| Callers | call_hierarchy incoming |
Grep + analyze |
| Callees | call_hierarchy outgoing |
Read function |
| Type hierarchy | type_hierarchy |
Grep extends/implements |
| Workspace search | workspace_symbol_resolve |
Glob + Grep |
| Refactorings | code_actions |
Manual |
| Signature | signature_help |
Hover or read |
| Diagnostics | diagnostics |
Build command |
| Format | format_document |
Formatter CLI |
| Edit by line | edit_file |
Built-in Edit |
Parameters
Required: filePath (absolute), line/column (1-indexed), symbolName (fully-qualified for definition/references).
Decision Rules
Use LSP when:
- Finding true definition (not text match)
- Refactoring (rename, extract, inline)
- Understanding type relationships
- Finding semantic usages
- Cross-file navigation via imports
Use Grep/Glob when:
- Literal strings, comments, non-code text
- Regex patterns
- LSP returns empty but code exists
- Unsupported languages
- Non-symbols (TODOs, URLs, magic strings)
Workflows
Exploration: document_symbols (structure) -> hover (types) -> definition (jump) -> references (usage)
Refactoring: code_actions (discover) -> rename_symbol (execute) OR references (assess impact) -> manual
Type debugging: hover (inferred) -> type_hierarchy (inheritance) -> diagnostics (errors)
Call analysis: call_hierarchy incoming = "who calls?" | outgoing = "what calls?"
Anti-Patterns
Fallback Protocol
- LSP error/empty -> Check file saved (LSP reads disk)
- Try table fallback
- Persistent failure -> Feature unsupported by server
Self-Check
Before completing:
- Used semantic LSP tool for symbol-based queries (not text search)
- Verified file saved if LSP returned empty/unexpected results
- Applied atomic refactoring operations where available
- Documented fallback rationale if LSP bypassed
If ANY unchecked: STOP and reconsider approach.
Didn't find tool you were looking for?