Skip to content

AvatarSD/KiSkill / skills/kicad-pcb

kicad-pcb

Verified

Stage 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)

  1. pcb.netlist(SCH) → comps[ref]["tstamps"] — that uuid IS the link; nets is the connectivity ground truth (assert designed members!). Root-sheet local-label nets are prefixed "/" (/VOUT); power nets (GND, VCC) are not.
  2. pcb.load_footprint(mod_path, "Lib:Name") — renames for the board, strips file headers (.kicad_mod has no top-level uuid; instances do).
  3. 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.
  4. Stage in a grid CLEAR of the outline: pcb.edge_cuts_bbox(board).
  5. Gates: save → reparse → kicad-cli pcb export svg accepts → 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:

situationmode
~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 netlistfile (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 is api-<pid>.sock. A socket FILE proves nothing — kx connect()s; dead files are listed as ipc_stale_sockets.
  • Server off? kx env / kx live status name the kicad_common.json with api.enable_server: false — user turns on Preferences > Plugins > Enable KiCad API. Never edit the user's config yourself.
  • Remote GUI: kx live connect --host book probes the remote with the same discovery code over ssh, then opens ssh -f -N -M -S CTL -o StreamLocalBindUnlink=yes -L LOCAL.sock:REMOTE.sock HOST and makes LOCAL the target until kx live disconnect. Manual equivalent: that ssh line + KICAD_API_SOCKET=LOCAL.sock. Priority: KICAD_API_SOCKET > connect/headless target > local discovery.
  • kipy: the repo .venv with kicad-python==0.8.0 (API 10.0.6) for KiCad 10.0.x; kx live re-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).

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: 198kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall