Agent skills + headless Python engine giving an AI coding agent full control of KiCad — edit, verify, review & fabricate schematics and PCBs, no GUI.
Overview
KiSkill is a pack of Claude Code skills plus a pure-Python engine (kx) that lets an agent read, edit, verify, review, and fabricate KiCad schematics and PCBs — no GUI, no mouse, every change checked before it lands. Built on a lossless s-expression parser (byte-identical round-trips on real 2 MB boards), a geometric verifier that runs before every write, and visual diffs fed back to the agent so it can see what it changed. Targets KiCad 9/10 (file-based), plus LIVE board editing in an open KiCad 10 PCB editor over IPC (kx live pcb, also on a remote host via an ssh socket forward); live schematic editing rides the same adapter on KiCad 11. On KiCad 10 a GENERATED schematic updates in the operator's open editor (kx live sch regen: save, regenerate, revert through the editor window). The core engine is stdlib-only; live mode needs kicad-python in the repo .venv (python3 -m venv .venv && .venv/bin/pip install kicad-python==0.8.0). (Claude Code, or any agent that reads ~/.
README
KiSkill — agent skills for KiCad
Give your coding agent full, headless control of any KiCad project.
KiSkill is a pack of Claude Code skills plus
a pure-Python engine (kx) that lets an agent read, edit, verify, review, and
fabricate KiCad schematics and PCBs — no GUI, no mouse, every change checked
before it lands.
Built on a lossless s-expression parser (byte-identical round-trips on real 2 MB boards), a geometric verifier that runs before every write, and visual diffs fed back to the agent so it can see what it changed.
Targets KiCad 9/10 (file-based), plus LIVE board editing in an open KiCad 10 PCB editor over IPC (
kx live pcb, also on a remote host via an ssh socket forward); live schematic editing rides the same adapter on KiCad 11. On KiCad 10 a GENERATED schematic updates in the operator’s open editor (kx live sch regen: save, regenerate, revert through the editor window). The core engine is stdlib-only; live mode needskicad-pythonin the repo.venv(python3 -m venv .venv && .venv/bin/pip install kicad-python==0.8.0).
Install
Tell your agent (Claude Code, or any agent that reads ~/.claude/skills/):
Clone https://github.com/AvatarSD/KiSkill and run its
install.shto set up the KiCad skills, then verify withkx root.
Or do it yourself — one clone, one script, no pip:
git clone https://github.com/AvatarSD/KiSkill.git
cd KiSkill
./install.sh # symlinks skills → ~/.claude/skills, kx → ~/.local/bin
install.sh is idempotent (re-run after git pull) and reversible
(./install.sh --uninstall). The engine is pure Python stdlib, so there’s
nothing to compile. KiCad itself (for ERC / render / fab) is resolved
automatically: native kicad-cli on PATH first, then the org.kicad.KiCad
flatpak, then the nightly. Override with KX_KICAD_CLI — e.g. set it to
kicad-cli-nightly when you edit with the v11 nightly, so verification
evidence comes from the same engine that writes your files.
Then just ask:
“Use the kicad-project skill to open
~/boards/widget/widget.kicad_pro, add a 3V3 LDO block to the schematic, and show me a diff.”
The skills
| skill | what it does |
|---|---|
| kicad-project | Session state machine (CLEAN→PROBED→…→COMMITTED), backend/lock detection, lib tables, git hygiene. Start here. |
| kicad-component | Find parts in local + official libs; fetch missing ones (LCSC via easyeda2kicad, SnapEDA/UltraLibrarian zips); register lib tables. |
| kicad-schematic | Generate & edit .kicad_sch/.kicad_pcb programmatically with a geometric verifier, headless ERC, and rendered visual checks. |
| kicad-pcb | Stage footprints so Update-PCB-from-Schematic adopts them without dupes; probe geometry; run DRC; render layers. |
| kicad-layout | Schematic → placed + routed board via freerouting (DSN/SES loop), gated on DRC. |
| kicad-review | Pixel diff, semantic tree diff, ERC/DRC set-diff vs a baseline, and a forum-distilled rule canon. Run before every commit. |
| kicad-fab | Grouped engineering BOM, JLCPCB BOM + CPL, gerbers, drill — ready for the fab house. |
| kicad-emsim | Electromagnetic field sim via gerber2ems + openEMS (dockerized): S-parameters, impedance, E-field PNGs. |
| kicad-improve | Self-improvement loop: each tick researches forums, tests against fixtures, and folds lessons back into the skills. |
Every skill is one self-contained SKILL.md. The shared engine lives in
kicad_lib/ and is reachable from anywhere via the kx CLI (kx root prints
the repo so skills stay portable no matter where you cloned).
Why it’s safe to let an agent drive
- Lossless parser — token-equal round-trips proven on multi-MB boards;
byte-identical for
.kicad_sch/.kicad_sym/.kicad_mod. - Verify-before-write — a geometric verifier (pins, overlaps, grid) must pass before any file is saved; nothing commits until a review diff is judged.
- Evidence, not vibes — renders and triple diffs flow back to the agent so decisions are made on what actually changed.
See doc/DESIGN.md for the architecture, state machine, and
the distilled schematic rule canon.
Requirements
- Python 3.10+ (engine is stdlib-only).
- KiCad 9 or 10 — native or flatpak (auto-resolved;
KX_KICAD_CLIto pin) — for ERC, rendering, and fab output. Pure file parsing/editing works without it. - Optional per-skill:
cairosvg/Pillow (render crops), Docker (emsim), a bundled freerouting jar (layout).
Contributing
Issues, fixtures, and PRs welcome — especially real-world boards that stress
the parser and forum-sourced rules worth encoding. Start with
CONTRIBUTING.md and the open items in
doc/BACKLOG.md. The kicad-improve skill is itself a
working example of how the pack grows.
License
MIT © KiSkill contributors.
Recommended Tools
Try a different keyword or remove a filter.
Install
npx skillfish add avatarsd/kiskill