using-lsp-tools
Skill11 starsChanged 3 months agoMITView on GitHub
Use when mcp-language-server tools are available and you need semantic code intelligence. Triggers: 'find definition', 'find references', 'who calls this', 'rename symbol', 'type hierarchy', 'go to definition', 'where is this used', 'where is this defined', 'what type is this'. Provides navigation, refactoring, and type analysis via LSP.
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 124
If ANY unchecked: STOP and reconsider approach.
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Using LSP Tools
<ROLE>
Language Tooling Expert. Reputation depends on leveraging semantic analysis over text matching for accurate, complete code navigation and refactoring.
</ROLE>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
<analysis>
- Is target a symbol (function, class, variable) or literal text?
- Is LSP server active for this language?
- Does task need semantic understanding (types, scope, inheritance)?
</analysis><reflection>
- Did LSP return expected results? If empty: file saved? Feature supported?
- Did fallback find matches LSP missed? Indicates LSP limitation vs. saved state.
</reflection>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
<FORBIDDEN>
- Using Grep for symbol rename (misses scoped references, hits false positives)
- Skipping LSP for "simple" refactors (simple becomes complex with inheritance)
- Trusting empty LSP results without checking file saved state
- Manual multi-file edits when `rename_symbol` available
- Ignoring `diagnostics` output when debugging type errors
</FORBIDDEN>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.
In this repository65 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- documentation-updatesSkill
- spellbook-auditingSkill
- advanced-code-reviewSkill
- adversarial-reviewSkill
- agent2agentSkill
- analyzing-domainsSkill
- analyzing-skill-usageSkill
- assembling-contextSkill
- async-await-patternsSkill
- auditing-green-mirageSkill
- autonomous-modeSkill
- branch-contextSkill
- code-reviewSkill
- creating-issues-and-pull-requestsSkill
- debuggingSkill
- dedupeSkill
- deep-researchSkill
- dehallucinationSkill
- design-explorationSkill
- designing-workflowsSkill
- developSkill
- devils-advocateSkill
- dispatching-parallel-agentsSkill
- distilling-prsSkill
- documenting-projectsSkill
- documenting-toolsSkill
- emotional-stakesSkill
- enforcing-code-qualitySkill
- estimating-ticketsSkill
- executing-plansSkill
- fact-checkingSkill
- finding-dead-codeSkill
- finishing-a-development-branchSkill
- fixing-testsSkill
- fractal-thinkingSkill
- gathering-requirementsSkill
- generating-diagramsSkill
- instruction-engineeringSkill
- isolated-testingSkill
- managing-artifactsSkill
- merging-worktreesSkill
- opportunity-awarenessSkill
- optimizing-instructionsSkill
- polish-repoSkill
- reflexionSkill
- requesting-code-reviewSkill
- resolving-merge-conflictsSkill
- reviewing-design-docsSkill
- reviewing-impl-plansSkill
- reviewing-prsSkill
- rounding-up-worktree-sessionsSkill
- sharpening-promptsSkill
- smart-readingSkill
- test-driven-developmentSkill
- testing-strategySkill
- tooling-discoverySkill
- using-git-worktreesSkill
- using-skillsSkill
- The first 60 shown.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.