kicad-mcp-pro: Skill for Claude Code

Wired Sub-circuit Design Skill

Use this skill when an agent must produce a schematic that looks like a person drew it — wired functional blocks, conventional power, a clean breakout bus — not just an electrically valid netlist. It is the deliberate, higher-effort path that sch_build_circuit(auto_layout=True, nets=...) cannot reach.

Specific to oaslananka/kicad-mcp-pro. Keep in sync with docs/tools-reference.generated.md. Worked reference: examples/gallery/esp32-c3-wroom-02-breakout.

Why auto layout is not enough

sch_build_circuit with nets uses a collision-safe terminal strategy: every pin endpoint gets a stub plus a same-named global label / power symbol, so nets connect by name and can never short by crossing geometry. That is correct and ERC-clean, but it reads as a machine netlist: every decoupling cap floats between its own +3V3 and GND labels instead of being wired. Showcase quality needs explicit placement and wires. The cosmetic score never measures this — judge the render, not the number.

The one rule that avoids a blank sheet

Build the whole sheet in a single sch_build_circuit pass with explicit symbols (with coordinates), wires, labels and power_symbols — and no nets, no auto_layout. Do not assemble a schematic from scratch with repeated sch_add_symbol calls: a freshly seeded sheet has no root UUID that the reader round-trips, so each incremental add stamps a different instance path and KiCad renders a blank sheet even though the file parses. One pass writes one consistent root UUID, so every symbol lands on the root sheet.

Compute exact pin coordinates up front with get_pin_positions(lib, sym, x, y, rot) (pure geometry — no placement needed), then wire pin-tip to pin-tip.

Design pattern

1. Anchor the main part (MCU / module) in the center.
2. Wire the sub-circuit islands. Decoupling, reset, boot-strap, status LED, regulators — draw each as a real wired block ending in power symbols. This is what separates a showcase from auto output; do not let these become floating labelled pins.
3. Label bus for the breakout. Route general IO to a header with matched local labels. Generate the part-side and header-side labels from one source list so the two label sets are identical by construction — this eliminates the whole isolated_pin_label / label_dangling class, not just the ones you happen to see.
4. Conventional power. +3V3 up, GND down; put exactly one PWR_FLAG on each supply net so ERC sees the rails driven.
5. Place each sub-circuit in its own x-column below the anchor, and keep decoupling clear of the anchor's stub fan — most first-pass ERC errors (multiple_net_names) come from a power symbol landing on a neighbouring label.
6. Fill the title block with sch_set_title_block_info.