productofamerica/mcp-server-kicad/schematic-design

<CRITICAL-RULE> NEVER use the Read, Write, or Edit tools on KiCad files (.kicad_sch, .kicad_pcb, .kicad_sym, .kicad_mod, .kicad_pro, .kicad_prl). ALL KiCad file manipulation MUST go through the kicad MCP tools. NEVER run kicad-cli commands via Bash. If an MCP tool returns an error, try different parameters — do NOT fall back to manual file editing.

EVERY KiCad operation has a corresponding MCP tool. Do NOT claim a tool does not exist without first listing all available tools. Key tools that MUST be used instead of file writes:

• add_symbol — create custom symbol definitions in .kicad_sym files
• create_symbol_library — create new .kicad_sym library files
• create_schematic — create new .kicad_sch files
• create_project — create new .kicad_pro project files

If you find yourself thinking "there's no MCP tool for this," you are wrong. Check the tool list again. </CRITICAL-RULE>

KiCad Schematic Design — Plan Executor

This skill executes schematic plans mechanically. All intelligence (component selection, coordinate calculation, wiring decisions) happened in prior phases. This skill reads a plan and executes it.

Response Format

When this skill activates, announce the mode:

• Plan mode: Print exactly: "Using schematic-design to execute

the placement plan."

• Modification mode: Print exactly: "Using schematic-design to

modify the existing schematic."

Then proceed directly to the pre-flight checks for the appropriate mode. Do not ask the user what to do — the plan or user instructions are the input. Report progress as each placement/wiring step completes, but keep updates brief (one line per step).

Two Modes

Plan Mode (new designs)

Reads specs/schematic-plan.md and executes mechanically. The plan file is the sole source of truth — ignore prior conversation context about how the plan was created. Read the plan, execute the plan.

Pre-flight checks:

1. Verify specs/schematic-plan.md exists and its reviewer returned

APPROVED

1. Read page size from plan, call set_page_size immediately if

not A4

1. Verify project/schematic files exist (create if needed)
2. If plan references custom symbol library, verify it exists via

list_lib_symbols

Execution order:

1. Project setup (create_project, create_schematic, etc.)
2. Set page size (if plan specifies non-A4)
3. Register symbol libraries (create_sym_lib_table)
4. Create custom symbols (add_symbol)
5. Place all components (place_component per coordinate table)
6. Wire all connections per wiring table — group all pins for the

same net into a single wire_pins_to_net call

1. Add no-connect flags
2. Add power flags
3. Add hierarchical sheets (if applicable)
4. Annotate — run annotate_schematic to assign reference designators.

For hierarchical designs, pass project_path to avoid cross-sheet ref conflicts.

1. Validate hierarchy — run validate_hierarchy from root to check

for orphaned labels, direction mismatches, duplicate refs, junctions and bus entry ends left inside wires, and flags and wire ends left off the pins of mirrored, rotated parts; for each issue with a repair, make that call (one with a note instead: see the verification skill).

1. Run ERC

Modification Mode (existing schematics)

No plan artifact required. User instructions serve as the plan.

Pre-flight checks:

1. Verify the schematic file exists
2. List current components via list_schematic_components
3. For each new component to be added, call list_lib_symbols to

verify its lib_id exists before placement

Follow existing spacing/wiring/naming conventions in the schematic.

Error Handling — Escalate, Don't Improvise

wire_pins_to_net refusals

A refused call writes nothing and lists every refused pin with a bracketed code, the obstacle and a remedy. Fix the cause and call again with the same pins. Never work around a refusal with add_label or add_wires: they check none of this, so they can merge nets silently.

When auto_place_decoupling_cap meets one of these after placing the cap, its error says what it left on disk and the calls that remove it; any library symbol it copied into the file stays, and no net depends on it.

Checklist (Plan Mode)

IMPORTANT: Use TodoWrite to create todos for EACH checklist item below.

• [ ] Verify specs/schematic-plan.md exists and is APPROVED
• [ ] Pre-flight: verify project/schematic files exist
• [ ] Set page size (if non-A4)
• [ ] Register symbol libraries
• [ ] Create custom symbols (if needed)
• [ ] Place all components per coordinate table
• [ ] Wire all connections per wiring table
• [ ] Add no-connect flags
• [ ] Add power flags and PWR_FLAG symbols
• [ ] Annotate schematic — no ? refs remaining
• [ ] Validate hierarchy — no orphaned labels or duplicate refs
• [ ] Run ERC — must show zero violations

Rationalization Prevention

Exit Gate

Run run_erc. Zero violations → proceed to pcb-layout. Violations → invoke verification skill.

Commit strategy: Commit after schematic-design completes and ERC passes (not after each chunk). If ERC fails, fix violations via verification skill, then commit the clean state. Do not commit intermediate broken states.

Placement Spacing Reference

All coordinates are on the 1.27mm grid (auto-snapped by the tools).

Minimum spacing (for modification mode and plan verification):

• Vertical between components: 10.16mm (8 grid units)
• Horizontal between passives in a row: 12.7mm (10 grid units)
• IC to its supporting passives: 25.4mm (20 grid units) horizontal
• Between functional stages: 25.4–50.8mm gap

Title block clearance: ~108x32mm at bottom-right corner. On A4 landscape (297x210mm), keep components within X < 180mm and Y < 175mm.

Wiring Strategy Reference

Use `connect_pins` (direct Manhattan wire) when:

• Two pins are within ~25mm of each other
• The wire path is visually obvious (one L-shaped segment)

Use `wire_pins_to_net` (batch: multiple pins to one net label) when:

• A net connects 3 or more components that are not all adjacent
• The net spans across functional stages
• Power and ground rails — always use net labels, never daisy-chain

What wire_pins_to_net writes: a short stub away from each pin with the label at its end, or the label on the pin end when the stub would touch something. It never writes a junction, and a pin already on the net is left alone. Read the result's notes: "new local net" means nothing on this sheet carried that name, so a power symbol or global label of that name elsewhere does not join it (use add_power_symbol or add_global_label to reach those); on a sheet used more than once, the wiring lands in every instance, and the note names each one.

Power and Ground

• Use add_power_symbol for VCC, GND, and named power rails
• Use wire_pins_to_net for custom power nets (VIN_PROT, 5V_REL, etc.)
• Place decoupling capacitors visually adjacent to the IC they serve
• Add PWR_FLAG on every power net that would otherwise trigger

"power pin not driven" ERC errors

• No tool places a PWR_FLAG for you, because only you know which nets have a

source ERC cannot see. Place one with add_power_symbol (lib_id power:PWR_FLAG), once per net that needs it

• PWR_FLAG is only needed on nets with power_in pins and NO power_out/output pins.

Do not add one to a net that already has a driver or a flag: ERC then reports two power outputs connected

Naming

• Use uppercase descriptive names for nets: VIN_PROT, 5V_REL,

SPI_MOSI

• Active-low signals: suffix with _N (e.g., RESET_N, CS_N)
• Do not use generic names like NET1 or WIRE3

MCP Tools for This Skill

Reading / inspection:

• get_schematic_summary — get item counts for a sheet
• list_schematic_components — list symbols on a sheet
• list_schematic_labels — list net labels on a sheet
• list_schematic_wires — list wires on a sheet
• list_schematic_global_labels — list global labels on a sheet
• list_schematic_hierarchical_labels — list hierarchical labels on a sheet
• list_schematic_sheets — list hierarchical sheet blocks on a sheet
• list_schematic_junctions — list junctions on a sheet
• list_schematic_no_connects — list no-connect flags on a sheet
• list_schematic_bus_entries — list bus entries on a sheet
• get_symbol_pins — get pin names and types for a placed symbol
• get_pin_positions — get placed pin coordinates (for wiring)
• get_net_connections — trace a net to see what's connected
• list_unconnected_pins — find pins that need wiring or no-connect