Content
# SKiDL IntelliSense - VS Code Extension
[](https://github.com/ashergarland/skidl-vscode/actions/workflows/ci.yml)
[](https://github.com/ashergarland/skidl-vscode/releases)
[](https://marketplace.visualstudio.com/items?itemName=ashergarland.skidl-lsp)
**Design a PCB without being an electronics engineer.** This extension gives AI agents the tools to generate validated schematics, optimize pin assignments, auto-place components, and verify power integrity — turning a plain-English description into a manufacturing-ready board layout.
```
"I need an I2C sensor breakout with pull-ups and decoupling"
↓ AI agent writes SKiDL code
↓ validate_skidl_code → catches errors before running
↓ parse_netlist → understands the circuit
↓ analyze_crossings → eliminates trace conflicts
↓ suggest_placement → positions components optimally
↓ validate_power_traces → confirms current-carrying capacity
↓ Output: placement-optimized, validated PCB design
```
The extension works in two modes: **as a traditional VS Code language server** (autocomplete, diagnostics, hover docs for humans writing SKiDL) and **as an MCP server** (19 tools that let AI agents design PCBs end-to-end).
---
## End-to-End Demo: AI Agent Designs a PCB
Here's what happens when you ask an AI agent to design a board with this extension active:
### Step 1: Agent writes the schematic
The agent generates SKiDL Python code and validates it in real-time:
```python
from skidl import Part, Net, generate_netlist
# Components
j_host = Part("Connector", "Conn_01x04_Male", footprint="Connector_PinHeader_2.54mm:PinHeader_1x04_P2.54mm_Vertical", value="HOST")
j_device = Part("Connector", "Conn_01x04_Male", footprint="Connector_PinHeader_2.54mm:PinHeader_1x04_P2.54mm_Vertical", value="DEVICE")
r_sda = Part("Device", "R", footprint="Resistor_SMD:R_0805_2012Metric", value="4.7k")
r_scl = Part("Device", "R", footprint="Resistor_SMD:R_0805_2012Metric", value="4.7k")
c_decoupling = Part("Device", "C", footprint="Capacitor_SMD:C_0805_2012Metric", value="100n")
```
```
Tool: validate_skidl_code({ source: "..." })
→ [] (no errors — all library names, symbols, footprints, and pins are valid)
```
### Step 2: Agent inspects the netlist
```
Tool: parse_netlist({ netlist: "<.net file content>" })
→ {
"components": {"J1": {...}, "J2": {...}, "R1": {...}, "R2": {...}, "C1": {...}},
"nets": {"SDA": [{"ref":"J1","pin":"1"}, {"ref":"J2","pin":"3"}, {"ref":"R1","pin":"1"}], ...},
"summary": {"component_count": 5, "net_count": 4}
}
```
### Step 3: Agent optimizes pin assignments
```
Tool: suggest_crossing_layers({ netlist: "..." })
→ { "suggested_layers": "J1 | R1,R2,C1 | J2", "reorderable_candidates": ["J2"] }
Tool: analyze_crossings({ netlist: "...", layers: "J1 | R1,R2,C1 | J2", reorderable: ["J2"] })
→ { "total_crossings_before": 3, "total_crossings_after": 0,
"reorderings": {"J2": {"original": ["1","2","3","4"], "optimized": ["3","4","1","2"]}} }
```
The agent now knows J2's pins should be reordered to eliminate all trace crossings.
### Step 4: Agent places components on the board
```
Tool: suggest_placement({
netlist: "...",
board_width_mm: 35, board_height_mm: 25,
fixed_positions: [{"ref": "J1", "x": 2, "y": 12}],
current_budget: {"VCC": 0.3, "GND": 0.3}
})
→ {
"board": {"width_mm": 35, "height_mm": 25},
"positions": {
"J1": {"x": 2.0, "y": 12.0, "rotation": 0, "layer": "F.Cu"},
"J2": {"x": 30.5, "y": 12.0, "rotation": 0, "layer": "F.Cu"},
"R1": {"x": 16.2, "y": 7.3, "rotation": 90, "layer": "F.Cu"},
"R2": {"x": 19.8, "y": 7.3, "rotation": 90, "layer": "F.Cu"},
"C1": {"x": 16.5, "y": 18.1, "rotation": 0, "layer": "F.Cu"}
},
"metrics": {"total_wire_length_mm": 38.2, "overlap_count": 0},
"decoupling_issues": [],
"power_violations": []
}
```
### Result
From a single English sentence, the AI agent produced:
- A validated schematic with correct part names, footprints, and pin connections
- Optimized pin ordering with zero trace crossings
- Component placement with no overlaps, proper decoupling, and validated power traces
- EDA-agnostic JSON output that can be applied to KiCad, Altium, or any PCB tool
**The user's only remaining step: open KiCad, apply the placement, run the auto-router, and generate Gerbers.**
---
## Why This Matters
Traditional PCB design requires years of expertise: choosing the right components, assigning pins to avoid routing conflicts, placing components for signal integrity, and sizing traces for current capacity. This extension collapses that expertise into a set of tools that any AI agent can use.
| Traditional workflow | With this extension |
|---------------------|-------------------|
| Learn electronics + KiCad (months) | Describe what you want in English |
| Manually check every part name, pin, footprint | `validate_skidl_code` catches everything |
| Trial-and-error pin assignment | `analyze_crossings` finds the optimal order |
| Manual component placement | `suggest_placement` computes positions |
| Hope your power traces are wide enough | `validate_power_traces` tells you |
---
## Features
### For Humans (VS Code Language Server)
- **Diagnostics**: Real-time error squiggles for invalid library names, symbols, footprints, and pins
- **Autocomplete**: Context-aware suggestions for libraries, symbols, footprints, and pin names
- **Hover docs**: Symbol descriptions, pin lists, and footprint details on hover
- **Quick-fix**: "Did you mean?" suggestions powered by fuzzy matching
- **BOM generation**: Generate a Bill of Materials from Part() calls
- **Cached index**: KiCad library index cached to disk (~1s startup after first load)
### For AI Agents (MCP Server — 19 Tools)
| Category | Tools |
|----------|-------|
| **Validation** | `validate_skidl_code` |
| **Library browsing** | `list_libraries`, `list_symbols`, `get_symbol_info`, `list_footprint_libraries`, `list_footprints`, `get_footprint_info` |
| **Search** | `search_symbols`, `search_footprints` |
| **Code intelligence** | `get_completions`, `get_documentation_at` |
| **BOM** | `generate_bom` |
| **Netlist analysis** | `parse_netlist`, `suggest_crossing_layers` |
| **Crossing optimization** | `analyze_crossings`, `plan_footprint` |
| **Placement** | `suggest_placement` |
| **Power validation** | `validate_power_traces` |
| **Admin** | `rebuild_index` |
All tools accept plain strings/dicts and return JSON — designed for AI consumption.
---
## Installation
### From VS Code Marketplace
Search for **"SKiDL IntelliSense"** in the Extensions panel, or install from the [Marketplace page](https://marketplace.visualstudio.com/items?itemName=ashergarland.skidl-lsp).
### From GitHub Releases
1. Download the latest `.vsix` from [Releases](https://github.com/ashergarland/skidl-vscode/releases)
2. In VS Code: Extensions → `...` menu → "Install from VSIX..."
### Requirements
- VS Code 1.85+
- Python 3.10+
- KiCad 7, 8, 9, or 10 (for the symbol/footprint libraries)
- SKiDL itself is **not** required — the extension parses KiCad library files directly
The extension auto-installs Python dependencies (`pygls`, `lsprotocol`, `mcp`, `pcb-crossing-optimizer`) on first activation.
---
## MCP Setup (AI Agent Access)
The MCP server is what connects AI agents to your KiCad libraries and the optimization engine.
**VS Code (automatic):** The extension registers the MCP server via the VS Code API. It appears in your MCP server list with no configuration needed.
**Claude Desktop / other MCP clients:**
1. Open Command Palette → **SKiDL: Enable MCP Integration**
2. Choose your target (Claude Desktop or clipboard)
3. The command auto-detects your Python path and writes the config
**Manual setup:**
```json
{
"mcpServers": {
"skidl": {
"command": "python",
"args": ["/path/to/skidl-vscode/mcp_server/server.py"]
}
}
}
```
**Environment overrides:**
| Variable | Description |
|----------|-------------|
| `SKIDL_KICAD_SYMBOL_DIR` | Override auto-detected symbol library path |
| `SKIDL_KICAD_FOOTPRINT_DIR` | Override auto-detected footprint library path |
---
## Quick Start for AI Agents
Give your AI agent this context to get started:
> You have access to the SKiDL MCP server. It validates SKiDL Python code against locally installed KiCad libraries and provides PCB design optimization. Use `validate_skidl_code` to check schematics, `parse_netlist` to understand circuits, `analyze_crossings` to optimize pin assignments, `suggest_placement` to auto-place components, and `validate_power_traces` to verify power delivery. All output is JSON.
The agent's typical workflow:
1. **Write** SKiDL code → validate with `validate_skidl_code`
2. **Generate** the netlist → inspect with `parse_netlist`
3. **Optimize** pin ordering → `suggest_crossing_layers` + `analyze_crossings`
4. **Place** components → `suggest_placement`
5. **Verify** power traces → `validate_power_traces`
---
## Configuration
| Setting | Default | Description |
|---------|---------|-------------|
| `skidl.kicadSymbolDir` | `""` (auto-detect) | Override path to KiCad symbol libraries |
| `skidl.kicadFootprintDir` | `""` (auto-detect) | Override path to KiCad footprint libraries |
| `skidl.enableDiagnostics` | `true` | Enable/disable error squiggles |
| `skidl.enableAutocomplete` | `true` | Enable/disable completions |
| `skidl.enableHover` | `true` | Enable/disable hover docs |
| `skidl.pythonPath` | `""` (auto-detect) | Path to Python interpreter |
---
## Commands
| Command | Description |
|---------|-------------|
| `SKiDL: Refresh KiCad Library Index` | Reload the library index (uses cache if valid) |
| `SKiDL: Force Rebuild KiCad Library Index` | Full rebuild, ignoring cache |
| `SKiDL: Enable MCP Integration` | Configure MCP server for Claude Desktop or clipboard |
| `SKiDL: Browse Components` | Search and browse KiCad symbols |
| `SKiDL: Browse Footprints` | Search and browse KiCad footprints |
| `SKiDL: Generate BOM` | Generate Bill of Materials from active file |
| `SKiDL: Validate Design` | Full validation of active file |
| `SKiDL: Analyze Crossings` | Analyze trace crossings in a netlist |
---
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ VS Code Extension (TypeScript) │
│ - LSP client, status bar, commands │
└────────────────────────┬────────────────────────────────────┘
│ stdio
┌────────────────────────▼────────────────────────────────────┐
│ Python Server │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ LSP Server │ │ MCP Server │ │ Core Engine │ │
│ │ (pygls) │ │ (FastMCP) │ │ │ │
│ │ │ │ │ │ - analyzer.py │ │
│ │ Diagnostics │ │ 19 tools │ │ - indexer.py │ │
│ │ Completions │ │ for AI agents│ │ - diagnostics.py │ │
│ │ Hover │ │ │ │ - completions.py │ │
│ └──────────────┘ └──────────────┘ │ - crossing.py │ │
│ │ - placement.py │ │
│ │ - bom.py │ │
│ └──────────────────┘ │
└────────────────────────┬────────────────────────────────────┘
│
┌────────────────────────▼────────────────────────────────────┐
│ KiCad Libraries (local) pcb-crossing-optimizer (PyPI) │
│ .kicad_sym, .kicad_mod Crossing, placement, power │
└─────────────────────────────────────────────────────────────┘
```
| Directory | Purpose |
|-----------|---------|
| `vscode_extension/` | TypeScript LSP client |
| `core/` | Pure Python analysis, validation, optimization |
| `lsp_server/` | pygls language server |
| `mcp_server/` | FastMCP server (AI agent interface) |
| `tests/` | pytest test suite |
---
## Development
### Setup
```bash
npm install
pip install -e . # or: pip install pygls lsprotocol mcp pcb-crossing-optimizer pytest
```
### Build & Test
```bash
npm run build # compile TypeScript + package VSIX
npm test # run Python server tests
```
### Release
Pushing a `v*` tag triggers CI which runs tests, builds the VSIX, publishes to the VS Code Marketplace, and creates a GitHub Release.
---
## Powered By
- **[SKiDL](https://github.com/devbisme/skidl)** — Python DSL for electronic circuit design
- **[pcb-crossing-optimizer](https://github.com/ashergarland/pcb-crossing-optimizer)** — Crossing minimization, placement, and power validation algorithms
- **[KiCad](https://www.kicad.org/)** — Open-source EDA suite (provides the component libraries)
- **[MCP](https://modelcontextprotocol.io/)** — Model Context Protocol for AI tool integration
## License
MIT
