code-yeongyu/oh-my-openagent / packages/shared-skills/skills/lsp-setup
lsp-setup
FlaggedConfigures a language server so editor/agent tooling (diagnostics, go-to-definition, references, rename) works. Use when a project needs an LSP installed or wired, or a 'no LSP server configured' error appears.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.1 KB |
| references/bash/README.md | markdown | 2.2 KB |
| references/c-cpp/README.md | markdown | 2.5 KB |
| references/csharp/README.md | markdown | 2.5 KB |
| references/dart/README.md | markdown | 1.9 KB |
| references/elixir/README.md | markdown | 2.2 KB |
| references/go/README.md | markdown | 2.0 KB |
| references/haskell/README.md | markdown | 2.3 KB |
| references/java/README.md | markdown | 2.7 KB |
| references/julia/README.md | markdown | 2.4 KB |
| references/kotlin/README.md | markdown | 2.6 KB |
| references/lua/README.md | markdown | 2.1 KB |
| references/php/README.md | markdown | 2.0 KB |
| references/python/README.md | markdown | 3.1 KB |
| references/ruby/README.md | markdown | 2.4 KB |
| references/rust/README.md | markdown | 2.0 KB |
| references/swift/README.md | markdown | 2.3 KB |
| references/terraform/README.md | markdown | 2.2 KB |
| references/typescript/README.md | markdown | 3.3 KB |
| references/yaml/README.md | markdown | 2.4 KB |
| references/zig/README.md | markdown | 1.8 KB |
| scripts/detect-lsp.ts | script | 6.8 KB |
| scripts/lsp-server-table.ts | script | 5.4 KB |
| scripts/tsconfig.json | config | 397 B |
| scripts/verify-lsp.ts | script | 5.2 KB |
SKILL.md
View on GitHub---
name: lsp-setup
description: "Configures a language server so editor/agent tooling (diagnostics, go-to-definition, references, rename) works. Use when a project needs an LSP installed or wired, or a 'no LSP server configured' error appears."
---
# LSP Setup
Configure the right Language Server for a project so the `lsp` MCP tools
(`diagnostics`, `goto_definition`, `find_references`, `symbols`, `rename`)
actually work. This skill is an index: detect what a project needs, install the
server, write the config, then verify with a real roundtrip.
The list of servers we ship as **builtin** is the source of truth in
`packages/lsp-tools-mcp/src/lsp/server-definitions.ts` (`BUILTIN_SERVERS` +
`LSP_INSTALL_HINTS`). The per-language references below mirror it.
---
## PHASE 0 — LANGUAGE GATE (run first)
Identify the language from the file extension, then **read the matching
reference before installing or configuring anything**.
| Extension(s) | Reference |
|---|---|
| `.ts .tsx .js .jsx .mjs .cjs .mts .cts .vue .svelte .astro` | `references/typescript/README.md` |
| `.py .pyi` | `references/python/README.md` |
| `.go` | `references/go/README.md` |
| `.rs` | `references/rust/README.md` |
| `.c .cpp .cc .cxx .c++ .h .hpp .hh .hxx .h++` | `references/c-cpp/README.md` |
| `.java` | `references/java/README.md` |
| `.kt .kts` | `references/kotlin/README.md` |
| `.cs .razor .cshtml` | `references/csharp/README.md` |
| `.swift .m .mm` | `references/swift/README.md` |
| `.rb .rake .gemspec .ru` | `references/ruby/README.md` |
| `.php` | `references/php/README.md` |
| `.dart` | `references/dart/README.md` |
| `.ex .exs` | `references/elixir/README.md` |
| `.zig .zon` | `references/zig/README.md` |
| `.lua` | `references/lua/README.md` |
| `.sh .bash .zsh .ksh` | `references/bash/README.md` |
| `.yaml .yml` | `references/yaml/README.md` |
| `.tf .tfvars` | `references/terraform/README.md` |
| `.hs .lhs` | `references/haskell/README.md` |
| `.jl` | `references/julia/README.md` |
---
## WORKFLOW — detect → install → configure → verify
### 1. Detect
Scan the project to see which languages are present and whether each server is
installed and configured:
```bash
bun scripts/detect-lsp.ts <projectDir> # human report (default: cwd)
bun scripts/detect-lsp.ts <projectDir> --json
```
For each detected language it prints the builtin server id, the executable it
needs on `PATH`, whether that executable is installed, an install hint, and
whether a project config file already references it.
### 2. Install
Open `references/<language>/README.md` and run the install command for your OS.
Then confirm the executable resolves:
```bash
command -v <server-executable> # e.g. typescript-language-server, gopls, rust-analyzer
```
### 3. Configure
Most builtin servers need **no config** — they are resolved automatically by
file extension. Write config only to: pick between competing servers, set a
`priority`, pass `initialization` options, override `extensions`, set `env`
(user config only), or `disable` a server.
Config files per harness, **identical JSON shape**. Each harness reads the
first project file that exists, plus one user file:
| Harness | Project config | User config |
|---|---|---|
| Codex | `.codex/lsp-client.json` | `$CODEX_HOME/lsp-client.json` (default `~/.codex/lsp-client.json`) |
| OpenCode | `.opencode/lsp.json`, then `.omo/lsp.json`, then `.omo/lsp-client.json` | `lsp.json` in the OpenCode config dir (default `~/.config/opencode/lsp.json`) |
| OmO native | `.omo/lsp-client.json`, then `.pi/lsp-client.json` | `~/.omo/lsp-client.json` (`~/.pi/lsp-client.json` when only that one exists) |
A standalone `lsp-tools-mcp` launch reads the paths in
`LSP_TOOLS_MCP_PROJECT_CONFIG` / `LSP_TOOLS_MCP_USER_CONFIG` instead.
```jsonc
{
"lsp": {
"<server-id>": {
"command": ["<bin>", "<args>"], // optional for builtin ids (supplied automatically)
"extensions": [".ext"], // optional override
"priority": 100, // higher wins when several servers match an extension
"initialization": { }, // server-specific initializationOptions
"env": { "KEY": "value" }, // optional
"disabled": false // set true to turn a server off
}
}
}
```
Rules enforced by `config-loader.ts`:
- In a **project** config an entry whose id is a **builtin** server inherits
`command` automatically — you only override `extensions` / `priority` /
`initialization` / `disabled`. Its `env` is dropped, and a non-builtin id in
a project config is **ignored**.
- To set `env`, or to define a **fully custom** (non-builtin) server with its
own `command`, put it in the **user** config from the table above, where
`command` + `extensions` + `env` are honored.
- Project entries win over user entries; both win over builtin defaults. A user
entry is skipped when an enabled project entry has the same id, so keep an id
that needs `env` out of the project config.
Each language reference gives a ready-to-paste snippet.
### 4. Verify
Run a real diagnostics roundtrip against a source file. This spawns the server,
opens the file, requests diagnostics, and reports `OK`/`FAIL`:
```bash
bun scripts/verify-lsp.ts <path/to/file.ext>
bun scripts/verify-lsp.ts <file> --timeout=90000
```
`OK` = the server started and answered. `FAIL: language server not installed`
= go back to step 2. Other `FAIL` text carries the server/startup error.
`SKIP` = the engine source could not be located; run from inside the omo
repo/worktree, or call the `lsp` MCP `diagnostics` tool directly.
---
## Scripts
| Script | Purpose |
|---|---|
| `scripts/detect-lsp.ts` | Scan a directory; per detected language report server id, install status, install hint, config status. `--json` for machine output. |
| `scripts/verify-lsp.ts` | Real LSP diagnostics roundtrip for one file via the `lsp-tools-mcp` engine; `OK`/`FAIL`/`SKIP` + exit code 0/1/3. |
| `scripts/lsp-server-table.ts` | Embedded snapshot of the primary builtin server per language (mirrors `server-definitions.ts`). |
Run with [Bun](https://bun.sh): `curl -fsSL https://bun.sh/install | bash`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 471k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |