Kicad project

Skill AvatarSD/KiSkill/skills/kicad-project

Agent skills + headless Python engine giving an AI coding agent full control of KiCad — edit, verify, review & fabricate schematics and PCBs, no GUI.

Install

npx -y skills add AvatarSD/KiSkill --skill kicad-project

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

What its author says it does

Copied from the file, not written here

Open, inspect, and safely manipulate any KiCad project through the CLEAN→PROBED→STAGED→VERIFIED→RENDERED→REVIEWED→COMMITTED state machine. Use when starting any KiCad work session, setting up lib tables, or when unsure whether it is safe to write to a project.

SKILL.md

3.9 KB, as published. Nobody here has run it

KiCad project state machine

Repo: $(kx root) (engine + design docs).

Session entry protocol (always)

kx env PROJECT_DIR — one call: kicad-cli (+nightly) version, lock files (tilde = literal filename prefix), IPC socket/aliveness, recommended backend. If backends.file.writable_now is false, KiCad has the project OPEN: do not write; ask the user to close/reload, or work on a scratch copy. kx = ~/.local/bin/kx → repo bin/kx (self-sets PYTHONPATH; works from any cwd). Python API instead: run with PYTHONPATH=$(kx root) (no pip install). kicad-cli is resolved by kicad_lib/kcli.py: KX_KICAD_CLI env → native on PATH → flatpak → nightly. VERSION-SKEW RULE: evidence (ERC/render/netlist) must come from the same engine that writes the files — if the user edits with the v11 nightly, set KX_KICAD_CLI=kicad-cli-nightly for the session; a stable CLI may misread nightly-saved files and the diff/ERC evidence silently lies.
Git: checkpoint-commit the project BEFORE the first modification.
kx probe FILE — inventory (uuid, paper, symbols/refs, labels, sheets, cached libs).

State machine (DESIGN.md §3)

CLEAN → PROBED → STAGED → VERIFIED (geometric verifier 0 violations) → RENDERED (svg→png, ERC run) → REVIEWED (pixel+semantic+ERC diff judged against rule canon) → COMMITTED. Never skip a state; never write a file that has not passed VERIFIED; never commit one that has not been REVIEWED.

Live IPC against the v11 nightly (validated 10.99.0 build 87de73b)

Enable once (KiCad closed): set api.enable_server: true in ~/.config/kicad/10.99/kicad_common.json.
Launch on a SCRATCH COPY (the nightly upgrades file formats on save): DISPLAY=:1 sh -c '. /usr/share/kicad-nightly/kicad-nightly.env && /usr/lib/kicad-nightly/bin/eeschema COPY.kicad_sch' in background. GUI needs X11 — pick the DISPLAY where xset q answers. Kill it later with pkill; then rm stale ~*.lck files.
Socket appears at /tmp/kicad/api.sock within ~1 s; verify with kx env → ipc_alive: true, open_documents lists the schematic.
kipy MASTER is required (PyPI 0.7.1's schematic module is broken against its own protos). Bootstrap: tools/bootstrap_kipy.sh (protoc 29.x in ~/.local + protol; .pth-installs .tools/kicad-python).
HANDLER MAP (each frame registers its own handlers in-process):
- standalone eeschema HANDLES: get_open_documents, get_schematic, get_items/symbols/lines/labels/text, begin/push commit, create_items, remove_items — full live editing, undoable in GUI.
- standalone eeschema LACKS (ApiError "no handler"): ping, get_version, save, save_as, revert, run_action — the agent CANNOT persist from IPC; the USER saves (Ctrl+S), or do at-rest edits via the file backend instead.
- kicad PM process handles ONLY ping + get_version (no frames). Opening eeschema FROM the PM should merge both sets — needs one GUI click (no xdotool on this box). Re-test on newer nightlies: tests/test_live_ipc.py prints the gap map and flags improvements.
live.py's ipc_ping treats a structured ApiError as alive (transport answered). kicad-cli-nightly (wrapper in /usr/bin) is the only way to run the nightly CLI — the raw binary fails on LD_LIBRARY_PATH.

Project hygiene

References are global across ALL sheets — collision-check project-wide.
Preserve root uuid and per-sheet uuids; instance paths depend on them.
sym-lib-table / fp-lib-table: project-local libs use ${KIPRJMOD} URIs.
Scratch outputs (svg_out/, *.rpt, *.net, *.png) never get committed.