/kicad-pcb

name: kicad-pcb
description: |
  Workflow skill for KiCAD PCB layout and routing via MCP tools. Triggers on: "layout the board",
  "route traces", "PCB", "place footprints", "copper pour", "board outline", "differential pair",
  "board setup", "track width", "via", "zone", "design rules", "stackup", "silkscreen".
argument-hint: "[layout task]"

KiCAD PCB Layout Workflow

This skill guides Claude to perform PCB layout using Konnect MCP tools. ALL modifications go through MCP tools — never edit .kicad_pcb files directly.

---

Prerequisites

Most PCB layout operations require KiCAD to be running with the board file open. The IPC connection communicates with the running KiCAD instance in real-time.

Some board-construction and component tools have guarded closed-board paths. IPC-first tools fall back to the file only when the transport is unreachable and the target board has not been observed live during this server session. These paths use revision-aware atomic writes: placement preserves pads, graphics, attributes, and models; moves preserve the existing angle; rotations update the footprint and its child angles; the closed-board flip fallback mirrors supported geometry and swaps front/back layers, refusing any 3D model whose offset/rotation it cannot transform. On KiCad 10.0.6+, `flip_component` prefers KiCad's own native FlipItems IPC command instead, which handles that 3D-model transform correctly — the file fallback only applies when no live KiCad holds the board. A reachable KiCad that predates 10.0.6 returns the structured error **unsupported_capability**; every reachable rejection stays closed instead of racing the editor with a file edit.

`unsafe_file_fallback` is a stop condition. It means Konnect reached this board live earlier in the current server session but IPC is now unreachable, so the saved file may be older than lost editor state. Pause mutation work, tell the user that Konnect left the file unchanged, and ask them to reopen/recover, reconcile, and save the board in KiCad. A read-only tool taking `board_source` can return the same kind, where nothing was going to be written: reporting the saved file as current would be the unsafe act. There, `board_source: "saved"` inspects that snapshot deliberately and says what it excludes — offer it instead of retrying the default. Continue through live IPC afterward. Preserve the guard: do not retry-loop, restart Konnect automatically, or edit `.kicad_pcb` directly. If the user confirms a clean close and an authoritative saved file, they may restart Konnect to deliberately begin a new closed-board session.

If connection fails:

• Tell the user to open KiCAD and load the project
• The board (.kicad_pcb) must be open in the PCB editor
• KiCAD's IPC API must be enabled (default in KiCAD 8+)

---

Toolset Loading

Before any PCB work, load the required toolsets:

load_toolset('pcb_board')        # board outline, layers, setup, stackup
load_toolset('pcb_components')   # place, refresh, move, rotate, align footprints
load_toolset('pcb_routing')      # traces, vias, differential pairs
load_toolset('sch_export')       # update PCB from the saved schematic hierarchy

Zones (`pcb_board`: add_zone; `pcb_routing`: add_copper_pour), component/net queries (`pcb_components`: find_component, get_component_list; `pcb_board`: get_board_info), and bulk placement (`pcb_components`: place_component_array, align_components, duplicate_component) are already covered by the toolsets loaded above.

Load additional toolsets as needed:

load_toolset('config')           # design rule storage: add_design_rule, list_design_rules
load_toolset('verification')     # run_drc, rules/sizes, check_clearance (explicit anchor/courtyard mode)

Always call `get_active_toolsets()` first to see what is already loaded.

References by decision

• Read [`references/layer-reference.md`](references/layer-reference.md) when

selecting a copper, fabrication, user, or mechanical layer or deciding which side owns an item.

• Read [`references/trace-width-table.md`](references/trace-width-table.md) when

sizing a current-carrying trace, via, or controlled-impedance route. It defines the required calculation inputs and acceptance record; it is not a lookup table.

• Read [`references/design-rules.md`](references/design-rules.md) when creating

netclasses, configuring project constraints, or adjudicating DRC results.

---

Layout Order

Follow this sequence for a clean PCB workflow:

1. **Board outline** — `set_board_size` or draw Edge.Cuts geometry. Both outline tools append, so resize with `delete_graphics(layer='Edge.Cuts')` first — a second call without it leaves two overlapping outlines and a DRC failure. 2. **Update from schematic** — call `update_pcb_from_schematic` first with `dry_run: true`. Review `status`, `coverage`, `diagnostics`, and staged positions. Apply only with `dry_run: false` and the exact returned `expected_plan_revision` value. The saved schematic hierarchy must be closed in the schematic editor, and the target board must be open in KiCad. A conflict is non-mutating; resolve it and rerun the dry run. A diagnostic about a library footprint names that footprint and every part that needs it: when the footprint cannot be placed (custom-shape pads are not supported), assign those parts a footprint without them; when the schematic connects a pad the footprint does not have, fix the symbol or the footprint choice. A successful apply is one KiCad undo entry, so Ctrl-Z reverses the whole update. 3. **Refresh changed libraries** — when a linked footprint library changed, use `update_footprints_from_library`, the MCP equivalent of KiCad **Tools → Update Footprints from Library**. This is distinct from `update_pcb_from_schematic`: it refreshes supported library-owned pads, graphics, attributes, metadata, and 3D models without changing references, placement, side, rotation, KIID, symbo