serena-lsp-tools

name	serena-lsp-tools
description	Navigate code semantically with LSP-backed symbol overview, symbol lookup, declaration/reference search, diagnostics, and guarded symbol edits.

Use this skill when code understanding or edits benefit from language-server semantics instead of plain text search. Prefer it for symbol discovery, definitions, references, diagnostics, and whole-symbol edits.

Run commands from the project root or a subdirectory:

serena-rs <command> ...

Use serena-rs <command> --help when argument format is unclear; command help includes examples for locations, symbol paths, and write confirmations.

Workflow

1. Use doctor --file <file> when first checking a project or dependency setup.
2. Check availability with health --file <file> when a target file is known; otherwise use health.
3. Use overview <file> before reading a large source file.
4. Use symbol <name-or-path> [--file <file>] to locate definitions by semantic symbol name.
5. Use declaration <file:line[:col]> and refs <file:line[:col]> for LSP-style navigation.
6. Use diagnostics <file> before and after risky edits.
7. Treat empty semantic results or LSP environment warnings as untrusted; inspect rg_cross_check when present.
8. Use explain-empty <command-id> when a successful command returns empty or confusing data.

Commands

Read-only:

• health
• health --file <file>
• doctor
• doctor --file <file>
• status
• overview <file> [--depth N]
• symbol <name-or-path> [--file <file>] [--depth N]
• declaration <file:line[:col]>
• refs <file:line[:col]> [--include-declaration]
• diagnostics <file>
• locate "<file>@<symbol-path>"
• explain-empty <command-id>

Lifecycle:

• start
• stop
• cache clear
• server logs
• server logs --tail N

Write commands require explicit --apply; no dry-run is fabricated:

• rename <file>@<symbol-path> <new-name> --apply
• replace-body <file>@<symbol-path> --stdin --apply
• insert-before <file>@<symbol-path> --stdin --apply
• insert-after <file>@<symbol-path> --stdin --apply

Rules

• Locations use 1-based line and col. If col is omitted, function names are preferred on function definitions; nearby-line adjustments are reported in context and warnings. Pass :col when a line contains multiple identifiers.
• If refs returns no semantic references, inspect rg_cross_check before assuming the symbol is unused.
• Runtime success and failure are JSON. Successful output includes command_id for explain-empty; some outputs include parsed_data and context.
• Read-only semantic commands may run concurrently after health --file <file> succeeds for the relevant language.
• start, stop, cache clear, and write commands are project-exclusive.
• cache clear only runs when the recorded server is not alive; use stop first.

Do not use this skill for file reads, shell execution, text search, or memory operations. Use normal agent tools for those.