AvatarSD/KiSkill / skills/kicad-pcb
kicad-pcb
VerifiedStage footprints on a KiCad PCB so Update-PCB-from-Schematic adopts them without duplicates, probe board geometry, run DRC, and render layers for inspection, and edit the board LIVE in an open KiCad PCB editor over IPC (summary, move/rotate/flip, placement files, select + zoom, zone refill — one undo step per op). Use when asked to put footprints on the pcb, prepare a board for layout, verify a .kicad_pcb change, or change a board the user has open in KiCad.
PCB footprint staging & board ops
Engine: $(kx root)/kicad_lib/pcb.py
(python API: PYTHONPATH= or cwd=; CLI: kx is on PATH)
(netlist, load_footprint, stage, edge_cuts_bbox,
empty_board_from). Worked example: tests/test_pcb.py.
Staging flow (Update-PCB adopts, no duplicates)
pcb.netlist(SCH)→comps[ref]["tstamps"]— that uuid IS the link;netsis the connectivity ground truth (assert designed members!). Root-sheet local-label nets are prefixed "/" (/VOUT); power nets (GND, VCC) are not.pcb.load_footprint(mod_path, "Lib:Name")— renames for the board, strips file headers (.kicad_mod has no top-level uuid; instances do).pcb.stage(board, fpdef, ref, value, at, tstamps_uuid, sheetfile)— inserts after the layer clause: uuid, at, path "/", sheetname, sheetfile; sets Reference/Value; refreshes EVERY item uuid. Pads stay netless — the sync fills them.- Stage in a grid CLEAR of the outline:
pcb.edge_cuts_bbox(board). - Gates: save → reparse →
kicad-cli pcb export svgaccepts → render PNG → eyeball → commit.
Notes
pcb.empty_board_from(donor)builds a minimal valid board (header + layer stack + setup + net 0) from any existing .kicad_pcb, read-only.- DRC:
kicad-cli pcb drc --output drc.rpt --severity-all BOARD— set-diff vs baseline exactly like ERC (kicad-review skill). - .kicad_pcb round-trips BYTE-IDENTICAL (validated on a 2.3 MB real board): pcb pts dialect (≤5 points inline, then 4-per-line chunks) + token wrap at column 72 — sexp.dumps sniffs the root tag, or pass dialect="pcb" when serializing subtrees. Hand-edits diff zero-noise.
- Update-PCB direction is sch→pcb only; never edit refs on the board.
Live mode: the board is OPEN in the KiCad PCB editor
Live vs file — decide with kx env PROJECT_DIR first:
| situation | mode |
|---|---|
~NAME.kicad_pcb.lck exists (GUI has it open, any host — sshfs too) | live. File writes are REFUSED (sexp.save_file raises HeldByGui): the GUI would overwrite them on its next save, or they clobber unsaved work |
| board closed, scripted/bulk generation, staging from a netlist | file (pcb.py, above) |
| GUI on another host (operator's screen) | live via kx live connect --host H |
Commands (mm, degrees, editor frame: y DOWN, as the status bar shows):
kx live status # which socket, why; probe version
kx live pcb summary # footprints, nets, net classes, layers, zones
kx live pcb fps [REF...] # x y rot side locked per footprint
kx live pcb move REF X Y [ROT] # one undo step, read back
kx live pcb rotate REF DEG # absolute orientation
kx live pcb flip REF # other side (flip_items: pads mirrored)
kx live pcb place FILE # JSON {REF:{x,y,rot,side}} or CSV with header
kx live pcb show REF... # select + zoom so the user sees what you mean
kx live pcb refill # refill all zones (KiCad's own undo step)
kx live pcb undo [N] # take back N steps
kx live pcb save # write the board to disk from the editor
Contract, every op: inputs validated BEFORE anything is sent (unknown or
LOCKED ref refuses the whole op; --force for locked); edits are one
commit; every change is read back (mismatches: [] = landed exactly);
exit 1 on refusal/mismatch. Moves+rotations of any number of parts are
ONE undo step; a side change is ONE MORE (KiCad 10 flip_items commits
on its own; setting the layer does not mirror pads) — the result says
undo_steps, pass it to undo N. Placement CSV columns:
ref/designator, x/posx/mid x, y/posy/mid y, rot/rotation, side/layer.
Do NOT feed a kicad-cli .pos or JLC CPL back unconverted: those are y-UP
from the aux origin.
Tell the user what you changed and offer show; nothing is on disk
until they (or save) save.
Finding the editor
- Socket discovery (
kicad_lib/ipc_discovery.py): flatpak KiCad's socket is~/.var/app/org.kicad.KiCad/cache/tmp/kicad/api.sock(the sandbox's /var/tmp), native$TMPDIR|/tmp/kicad/api.sock; a second instance isapi-<pid>.sock. A socket FILE proves nothing — kx connect()s; dead files are listed asipc_stale_sockets. - Server off?
kx env/kx live statusname the kicad_common.json withapi.enable_server: false— user turns on Preferences > Plugins > Enable KiCad API. Never edit the user's config yourself. - Remote GUI:
kx live connect --host bookprobes the remote with the same discovery code over ssh, then opensssh -f -N -M -S CTL -o StreamLocalBindUnlink=yes -L LOCAL.sock:REMOTE.sock HOSTand makes LOCAL the target untilkx live disconnect. Manual equivalent: that ssh line +KICAD_API_SOCKET=LOCAL.sock. Priority: KICAD_API_SOCKET > connect/headless target > local discovery. - kipy: the repo
.venvwithkicad-python==0.8.0(API 10.0.6) for KiCad 10.0.x;kx livere-execs into it.
Testing without the user's screen: kx live headless
kx live headless start BOARD runs the real flatpak PCB editor on Xvfb
with a scratch KICAD_CONFIG_HOME (API on, first-run wizard pre-answered),
a private sandbox TMPDIR (socket cannot collide with the user's KiCad)
and a private D-Bus (else GTK portal calls stall start-up ~95 s; now
~10 s), and makes it the live target. BOARD must be under $HOME (the
sandbox's /tmp is private). kx live headless stop kills it (unsaved
edits are lost by design), cleans its locks. Xvfb without sudo:
apt-get download xvfb && dpkg -x xvfb_*.deb ~/.local/opt/xvfb.
Tests: tests/test_live_pcb.py (logic, no KiCad) and
.venv/bin/python tests/test_live_pcb_ipc.py (e2e, headless).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |