Explains atopile's Language Server architecture and graph-based IDE features.
Install
mkdir -p .claude/skills/lsp && curl -L -o skill.zip "https://agentskills.codes/api/skills/download/4610" && unzip -o skill.zip -d .claude/skills/lsp && rm skill.zipInstalls to .claude/skills/lsp
Activation
This is the description your AI agent reads to decide when to run this skill — the better it matches your request, the more reliably it fires.
How the atopile Language Server works (pygls), how it builds per-document graphs for completion/hover/defs, and the invariants for keeping it fast and crash-proof.Key capabilities
- →Provide autocomplete for ato files
- →Enable go-to-definition navigation
- →Generate diagnostics for error reporting
- →Maintain per-document graph state
- →Execute partial compilation on incomplete code
How it works
The server uses pygls to manage document state and invokes the atopile compiler in a fault-tolerant mode to generate graphs for each open file. It retains the last successful build result to ensure IDE features remain functional during active editing.
Inputs & outputs
When to use lsp
- →Developing new IDE features for atopile
- →Testing Language Server stability
- →Debugging hover and completion handlers
- →Optimizing per-document build results
About this skill
LSP Module
The lsp module (located in src/atopile/lsp/) implements the Language Server Protocol for atopile. It provides IDE features like autocomplete, go-to-definition, and diagnostics (error reporting) for ato files.
Quick Start
Run the server on stdio (what editors expect):
python -m atopile.lsp.lsp_server
Relevant Files
- Server implementation:
src/atopile/lsp/lsp_server.py- owns global
LSP_SERVER(pyglsLanguageServer) - maintains per-document
DocumentState(graph/typegraph/build_result) - implements completion/hover/definition/diagnostics handlers
- owns global
- Utilities:
src/atopile/lsp/lsp_utils.py - Optional debugging helper:
src/atopile/lsp/_debug_server.py
Dependants (Call Sites)
- VSCode Extension: The designated client for this server.
- Compiler: The LSP invokes the compiler (often in a partial or fault-tolerant mode) to understand the code structure.
How to Work With / Develop / Test
Core Concepts
- Partial Compilation: Unlike the CLI build, the LSP must handle broken or incomplete code without crashing.
- Latency: Features must be fast (<50ms for typing, <200ms for completion).
- Per-document graphs: each open document has an isolated
GraphView+TypeGraphstored inDocumentState. - Keep last good build: the server keeps the last successful
BuildFileResultto power completion/hover even when the current edit has errors.
Development Workflow
- Edit handlers/helpers in
src/atopile/lsp/lsp_server.py. - Run completion tests (fast loop) and verify GraphView cleanup paths.
Testing
- Integration-style tests:
ato dev test --llm test/test_lsp_completion.py -q
Best Practices
- Robustness: Never let the server crash. Catch all exceptions in handlers and log them.
- Debouncing: Don't trigger expensive operations on every keystroke.
Core Invariants (easy to regress)
- Always destroy old graphs on rebuild/reset (
DocumentState.reset_graphcallsGraphView.destroy()). - Do not assume builds succeed; most features must handle:
- syntax errors (ANTLR)
- partial typegraphs
- exceptions from linking/deferred execution
When not to use it
- →When full CLI build results are required instead of partial state
- →When operating outside of a standard editor environment expecting stdio
Prerequisites
Limitations
- →Requires manual cleanup of GraphView instances via DocumentState.reset_graph
- →Must maintain latency under 50ms for typing and 200ms for completion
How it compares
Unlike a standard CLI compiler that expects valid code, this server performs partial compilation to provide feedback on broken or incomplete files without crashing.
Compared to similar skills
lsp side by side with the closest alternatives in the catalog.
| Skill | Installs | Updated | Safety | Difficulty |
|---|---|---|---|---|
| lsp (this skill) | 2 | 5mo | Review | Intermediate |
| python-project-structure | 8 | 6mo | No flags | Beginner |
| graph | 6 | 6mo | No flags | Advanced |
| library | 1 | 5mo | No flags | Intermediate |
Try saying
Example prompts that trigger this skill in your AI assistant.
More by atopile
View all by atopile →You might also like
python-project-structure
wshobson
Python project organization, module architecture, and public API design. Use when setting up new projects, organizing modules, defining public interfaces with __all__, or planning directory layouts.
graph
atopile
How the Zig-backed instance graph works (GraphView/NodeReference/EdgeReference), the real Python API surface, and the invariants around allocation, attributes, and cleanup.
library
atopile
How the Faebryk component library is structured, how `_F.py` is generated, and the conventions/invariants for adding new library modules.
generate-subsystem-skills
llama-farm
Generate specialized skills for each subsystem in the monorepo. Creates shared language skills and subsystem-specific checklists for high-quality AI code generation.
faebryk
atopile
How Faebryk’s TypeGraph works (GraphView + Zig edges), how to traverse/resolve references, and how FabLL types/traits map onto edge types.
tool-renderer
daaain
Implement specialized rendering for Claude Code tools. Use when adding a new tool type (WebSearch, WebFetch, etc.) to the transcript viewer, or when asked to implement tool rendering.