lsp-local-symbols

Files (1)

• SKILL.md

SKILL.md (first lines)

> Requires the agent-lsp MCP server.

# lsp-local-symbols

File-scoped symbol analysis using the language server index. Faster than
workspace-wide search for questions about a single file: what symbols are
defined here, where is this symbol used within the file, and what type does it
have.

Read-only — does not modify any files.

## When to use

- "Where is `x` used in this file?" — use `get_document_highlights`
- "What functions and types are defined in this file?" — use `list_symbols`
- "What type does this symbol have?" — use `inspect_symbol`
- Reviewing a file before editing — get the full symbol map first
- Local refactor scoping — confirm a symbol is only used in one place before inlining it

Use `/lsp-impact` instead when you need workspace-wide callers and cross-file
references. Use `/lsp-dead-code` when auditing exported symbols for zero callers.

## When NOT to use

`get_document_highlights` is file-scoped by design — it only finds usages within
the open file. If a symbol is used across multiple files, this skill will not
find those. Use `find_references` (via `/lsp-impact`) for cross-file analysis.

---

## Workflow

### Step 1 — Open the file

Open the file so the language server tracks it:

```
mcp__lsp__open_document
  file_path: "/abs/path/to/file.go"
  language_id: "go"              # go, typescript, python, rust, etc.
```

### Step 2 — List all symbols in the file

Get the full symbol tree for the file:

```
mcp__lsp__list_symbols
  file_path: "/abs/path/to/file.go"
```

This returns all functions, types, variables, constants, and methods defined in
the file — including nested symbols (methods on types, fields in structs).

Use this to:
- Understand the file's structure before editing
- Find the exact position of a named symbol
- See what a file exposes before reading it in full

**Reading the output:** Each symbol has a `range` (full body including braces)
and a `selectionRange` (just the name). Coordinates are 1-based. Use
`selectionRange.start.line` and `selectionRange.start.character` as inputs to
`get_document_highlights` and `inspect_symbol`.

### Step 3 — Find all usages within the file

Call `get_document_highlights` at the symbol's position:

```
mcp__lsp__get_document_highlights
  file_path: "/abs/path/to/file.go"
  line: <selectionRange.start.line from Step 2>
  column: <selectionRange.start.character from Step 2>
```

Returns every occurrence of the symbol within the file, classified as:
- `read` — the symbol is read here
- `write` — the symbol is assigned/mutated here
- `text` — a text match (fallback when semantic classification isn't available)

**Speed note:** `get_document_highlights` is significantly faster than
`find_references` for file-local queries — it does not scan the entire workspace
index. Use it first; escalate to `find_references` only if you need cross-file
results.

### Step 4 — Get type information (optional)

For any position of interest, get the type signature and docs:

```
mcp__lsp__inspect_symbol
  file_path: "/abs/path/to/file.go"
  line: <line>
  column: <column>
```

Returns the hover text: type signature, documentation, and inferred types.
Useful for confirming what a symbol is before deciding to rename or inline it.

---

## Output format

Report results in three sections (omit any section with no content):

```
## Symbols in <filename>

### Functions / Methods
- `FuncName` — line N–M
- `(Type) MethodName` — line N–M

### Types
- `TypeName` (struct/interface/alias) — line N

### Variables / Constants
- `ConstName` = value — line N

---

From blackwell-systems/agent-lsp, MIT.

More from blackwell-systems/agent-lsp