{"slug": "show-hn-skill-language-server-a-language-server-for-agent-skills", "title": "Show HN: Skill-language-server – A language server for agent skills", "summary": "A new open-source language server, skill-language-server, provides IDE-grade tooling for agent skill references in markdown files, offering completion, rename refactoring, and go-to-definition for `/skill-name` and `$skill-name` patterns across VS Code, Zed, Neovim, and Helix. Created by CyrusNuevoDia, the server indexes skills from `**/skills/<name>/SKILL.md` and references in `.md` files under `.claude/`, `.agents/`, `.codex/`, or `skills/`, with built-in near-miss detection and silent handling of non-skill paths like `/usr/bin`.", "body_md": "A language server for agent skills — `/skill-name`\n\nand `$skill-name`\n\nbecome real symbols in VS Code, Zed, Neovim, and Helix.\n\n▸ completion w/ descriptions on `/`\n\nand `$`\n\n▸ \"did you mean\" on typos\n\n▸ go to definition, find references\n\n▸ F2 rename w/ editor undo — folder, frontmatter `name:`\n\n, and every reference update as one edit\n\n▸ clickable links + semantic highlighting on resolved references\n\nYour skill library now has tooling.\n\nSkills, `CLAUDE.md`\n\n/`AGENTS.md`\n\n, and agent files reference each other by name — a dependency graph with all the refactoring hazards of code and none of the tooling. Rename a skill by hand and stale references look like ordinary prose: nothing errors, the agent silently stops loading the skill.\n\nQuiet by design — a false reference in prose costs more than a missed one:\n\n- Fenced code blocks are never parsed; inline code spans are (that's how people write skill names in prose)\n`/usr/bin`\n\n,`$PATH`\n\n,`docs/`\n\n— never references, never popups- Near miss of a real skill (edit distance ≤ 2) →\n*did you mean*warning; other unresolved`/name`\n\n→ info hint; unresolved`$name`\n\n→ silent - Built-in commands (\n`/help`\n\n,`/compact`\n\n, …) and your own`.claude/commands`\n\n/`.codex/prompts`\n\nare commands, not skills — never flagged\n\nIt's a language server, not a linter — pair with `skill-lint`\n\nor `agnix`\n\nfor structural/security linting.\n\n```\nnpm install -g skill-language-server\n```\n\nThen wire up your editor below. To see it work: cursor on any `/skill-name`\n\n, hit `F2`\n\n, type a new name — folder, frontmatter, and every reference update as one undo step.\n\n```\n# languages.toml\n[language-server.skill-language-server]\ncommand = \"skill-language-server\"\nargs = [\"--stdio\"]\n\n[[language]]\nname = \"markdown\"\nlanguage-servers = [\"skill-language-server\"]  # add e.g. \"marksman\" here if you use it\n```\n\nCreate `~/.config/nvim/lsp/skill-language-server.lua`\n\n:\n\n```\nreturn {\n  cmd = { \"skill-language-server\", \"--stdio\" },\n  filetypes = { \"markdown\" },\n  root_markers = { \".claude\", \".git\" },\n}\n```\n\nAdd `vim.lsp.enable(\"skill-language-server\")`\n\nto init.lua. (Or from a clone: `{ dir = \"/path/to/skill-language-server/ext/nvim\" }`\n\nin lazy.nvim.)\n\nCommand palette → `zed: install dev extension`\n\n→ select `ext/zed/`\n\nfrom a clone. After server updates: `editor: restart language server`\n\n.\n\n```\ngit clone https://github.com/CyrusNuevoDia/skill-language-server\ncd skill-language-server\nmise trust && mise install && bun install\njust build-vscode\ncode --install-extension dist/skill-language-server.vsix\n```\n\n(Marketplace listing pending — the .vsix bundles the server.)\n\n```\nmise trust && mise install   # bun, just (rust only for the Zed wasm)\nbun install\njust bin                     # → ~/.local/bin/skill-language-server\n```\n\nThe server's world is the folder your editor opened — it never reads outside it. A rename touches exactly the tree you have open, never another checkout or your home directory. Open `~/.claude`\n\nitself as a workspace to refactor your global library.\n\n**Skills**= any`**/skills/<name>/SKILL.md`\n\n. Folder name is canonical; a disagreeing frontmatter`name:`\n\nis an error, not an alias**References** are scanned in`.md`\n\nfiles under`.claude/`\n\n,`.agents/`\n\n,`.codex/`\n\n, or`skills/`\n\n, plus every`CLAUDE.md`\n\n/`AGENTS.md`\n\n. Markdown elsewhere is never touched**Live index** where the editor supports LSP file watching; open buffers beat disk. Without watching, the index catches up on file open or restart(gitignore syntax, workspace root) excludes paths from everything`.skillignore`\n\n- Multi-root workspaces: only the first folder is indexed\n\nCross-workspace renames are a deliberate two-step: rename where the skill lives, then open the other workspace — stale references surface as hints/warnings there. Blind spots: `$`\n\nstragglers stay silent, and an old name that doubles as a built-in command reads as the built-in.\n\nChecked against client source as of 2026-07: VS Code, Zed, Helix, and Neovim all apply the folder `RenameFile`\n\n.\n\n- Neovim never sends\n`willRenameFiles`\n\n— explorer-drag renames don't rewrite references there; rename from a token or the frontmatter instead - File watching: VS Code and Zed yes; Neovim yes except off by default on Linux; Helix only sees its own edits — reopen the file or restart the server after external changes\n\n```\njust check   # tsc (server + VS Code extension) + ultracite lint\nbun test     # protocol-level tests against a fixture workspace\njust build   # everything into dist/ — binary, .vsix, Zed wasm (wasm needs rust)\njust fmt     # ultracite fix --unsafe\n```\n\nThe test suite is the contract: `tests/harness.ts`\n\nboots the real server over in-memory streams; `tests/corpus.ts`\n\nis the ground-truth reference set. Done = `just check`\n\n+ `bun test`\n\ngreen.\n\nThree layers in `src/`\n\n: `parse.ts`\n\n(token grammar), `workspace.ts`\n\n(index), `server.ts`\n\n(LSP wiring). Editor shims in `ext/{vscode,zed,nvim}`\n\n.\n\nReleases via [changesets](https://github.com/changesets/changesets): `bun changeset`\n\nwith your change, merge to main, CI publishes.\n\nMIT", "url": "https://wpnews.pro/news/show-hn-skill-language-server-a-language-server-for-agent-skills", "canonical_source": "https://github.com/CyrusNuevoDia/skill-language-server", "published_at": "2026-07-27 06:15:54+00:00", "updated_at": "2026-07-27 06:52:50.117740+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "artificial-intelligence"], "entities": ["CyrusNuevoDia", "skill-language-server", "VS Code", "Zed", "Neovim", "Helix"], "alternates": {"html": "https://wpnews.pro/news/show-hn-skill-language-server-a-language-server-for-agent-skills", "markdown": "https://wpnews.pro/news/show-hn-skill-language-server-a-language-server-for-agent-skills.md", "text": "https://wpnews.pro/news/show-hn-skill-language-server-a-language-server-for-agent-skills.txt", "jsonld": "https://wpnews.pro/news/show-hn-skill-language-server-a-language-server-for-agent-skills.jsonld"}}