/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. File-only operations such as `flip_component` proceed only when KiCad does not hold the target board open. 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; flips mirror supported geometry and swap front/back layers. A reachable KiCad rejection stays closed instead of racing the editor.

`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. 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, set_design_rules, set_predefined_sizes, check_clearance

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 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, symbol metadata, instance overrides, or pad nets. Always call it first with `dry_run: true`; apply only with `dry_run: false` and the exact returned `expected_plan_revision`. The requested board must be open in live KiCad, one apply is one undo entry, and unsupported or stale content returns a non-mutating conflict instead of silently dropping it. 4. **Place components** — position all footprints 5. **Route traces** — connect all nets 6. **Copper pour** — add ground/power zones last 7. **DRC** — run design rule check 8. **Save** — `save_project`

Do NOT add copper pours before routing is complete — they interfere with interactive routing.

---

Placement

Strategy

• Group components by functional block (power, digital, analog, connectors)
• Place ICs first, then their associated passives
• Decoupling caps: within 2mm of their IC power pins, on same layer
• Cable/EMI filter caps: on the connector's own pins,