KiCad Skills
AI-agent skills and scripts for working with KiCad schematic and PCB design files.
Skills
kicad-tool
Single CLI (kicad-tool) that owns every read and write on .kicad_sch / .kicad_pcb files. Agents must route all query, edit, render, inspect, ERC/DRC, netlist, and validate operations through this tool instead of Read/cat/grep/Edit (raw access blows context and corrupts UUIDs / lib_symbols).
kicad-workflow
Stage-1 functional editing process. Plans, sequences, and validates structural changes — adding/removing/modifying symbols, wires, labels, footprints — including dry-run, baseline diff, ERC, netlist, and DRC. Pairs with kicad-tool for the actual commands.
kicad-sch-cleanup-loop
Stage-2 visual cleanup loop. Iteratively improves a schematic sheet's sch inspect score (collisions, wire bends, symbol clearance) without changing connectivity. Subagents edit one cluster at a time; the main loop scores and plans.
Install
In Claude Code:
/plugin marketplace add mash/kicad-skills
/plugin install kicad-skills@kicad-skills
The skill installs the kicad-tool CLI itself on first use, picking the method (pipx / uv / venv pip / …) that fits your Python environment. The kiutils fork is pulled in transitively — never pip install kiutils by hand (upstream lacks API used here).
To skip bootstrap, install git+https://github.com/mash/kicad-skills.git yourself however you like.
Example prompts
After import, drive the skills with prompts like:
Use the KiCad skills to inspect this schematic sheet and summarize the current ERC/netlist status.
Use the KiCad workflow skill to make this schematic edit safely, including dry-run, validation, and a concise report.
Use the KiCad schematic cleanup loop to improve the visual score of this sheet without changing connectivity.
What net is U3.7 on? Use kicad-tool.
Render the area around U1 on sheet power.kicad_sch so I can see the decoupling layout.
kicad-tool command reference
Entrypoint: kicad-tool <domain> <command> .... Text output by default; pass --format json for structured payloads. <schematic> / <board> are always the first positional. Coordinates are X,Y (bbox: X1,Y1,X2,Y2). KICAD_CLI overrides the KiCad executable.
Schematic — top-level operations
| Command | Purpose |
|---|
sch render-region <sheet> <X1,Y1,X2,Y2> | Cropped PNG of a sheet bbox (mm). Take the bbox wide to include neighbors/labels. -o/--output (default tmp/region.png) |
sch inspect <sheet> | Layout score + collisions; --only-text <regex>, --margin |
sch erc <top> | Hierarchical ERC; -o/--output |
sch netlist <top> | Netlist export; -o/--output |
sch validate <top> | erc + netlist + inspect in one call; --sheet <edited>, --save-baseline DIR, --baseline DIR |
Schematic — query (read-only)
| Command | Purpose |
|---|
sch query symbol <sch> <REF> | Symbol position, properties (Value/MPN/LCSC/Footprint), pin map |
sch query pin <sch> <REF.PIN> [--netlist PATH] | Pin coords, orientation, and (with netlist) net |
sch query net <sch> <NAME_OR_REF.PIN> --netlist PATH | Members and labels of a net |
sch query region <sch> <X1,Y1,X2,Y2> | All elements inside a bbox |
sch query wire <sch> (--uuid U | --at X,Y | --through X,Y) | Locate a wire |
sch query label <sch> (--name N | --uuid U) | Locate labels |
sch query lib-symbol <sch> <LIB_ID> | Library symbol pins/units |
sch query list <sch> <KIND> [--netlist PATH] | KIND ∈ symbols/labels/wires/junctions/nets (nets requires --netlist) |
Schematic — edit (mutations; --dry-run supported)
