<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

Placing components:

• place_component — place a symbol instance on the schematic
• move_component: move or turn a placed component. Its fields travel with it, wires stay put and the result names the pins whose connections changed; called at the symbol's own position it turns the symbol in place. Place and move parts before wiring, and after a move reconnect the pins the result names.
• remove_component — delete a placed component
• set_component_property — change reference, value, footprint, etc.
• set_page_size — resize the schematic sheet
• add_lib_symbol — load a symbol from a library into the schematic

Wiring and connectivity:

• connect_pins — direct Manhattan wire between two pins
• wire_pins_to_net — connect multiple pins to a named net label
• add_wires — add raw wire segments by coordinate
• add_label — place a net label
• add_global_label — place a global (cross-sheet) label
• add_junctions — add junction dots at wire intersections
• no_connect_pin — mark a pin as intentionally unconnected (idempotent)
• remove_no_connect — clear no-connect flag(s) from a pin
• remove_label / remove_wire / remove_junction — cleanup (labels and global labels)

Power and decoupling:

• add_power_symbol — place VCC, GND, +3V3, PWR_FLAG, etc.
• auto_place_decoupling_cap — auto-place a decoupling cap near an IC

Annotations and hierarchy:

• add_text — add text annotations to the sheet
• add_hierarchical_label — add a hierarchical label for sheet-to-sheet connections
• remove_hierarchical_label — remove a hierarchical label by name or UUID
• modify_hierarchical_label — modify text, shape, or position of a hierarchical label
• annotate_schematic — auto-assign reference designators (project server)
• remove_text — remove text annotations by position or content

Hierarchy management (project server):

• add_hierarchical_sheet / remove_hierarchical_sheet — create/remove sub-sheet blocks
• modify_hierarchical_sheet — change sheet name, file, dimensions (pins, fields and the wires

on pins follow a resize; a size below what the pins need is refused)

• add_sheet_pin / remove_sheet_pin — manage pins on sheet blocks
• validate_hierarchy — check for orphaned labels/pins, direction mismatches

and junctions and bus entry ends left inside wires, and flags and wire ends left off the pins of mirrored, rotated parts, with the call that repairs each where a tool can

• list_hierarchy / get_sheet_info — inspect hierarchy structure
• is_root_schematic — check if a schematic is root or sub-sheet
• move_hierarchical_sheet — reposition a sheet block on the canvas
• reorder_sheet_pages: change the page numbers, and so the page order, of hierarchical sheets

(call it on the root schematic)

• duplicate_sheet: create a copy of a sheet with new UUIDs and its own part references

(a sheet that has sub-sheets of its own is refused)

• flatten_hierarchy: write a single flat schematic whose netlist is the hierarchy's; it

refuses, writing nothing, where it could not keep that (bus names on sheet pins or in sub-sheets, for one)

• trace_hierarchical_net — trace a net across the hierarchy for debugging
• export_hierarchical_netlist — export netlist with hierarchy info

(use instead of export_netlist for hierarchical designs)

Hierarchy Workflow Sequences

Sequence: Setting up a hierarchical design

1. add_hierarchical_sheet — create the sub-sheet block on the parent
2. add_sheet_pin — add pins to the sheet block for each signal crossing the boundary

(an edge with no free slot is refused with the height that fits; grow the sheet with modify_hierarchical_sheet first)

1. In the child schematic: add_hierarchical_label for each pin
2. validate_hierarchy — verify pins match labels, no orphans

Sequence: Duplicating a channel (e.g., 4 identical sensor channels)

1. Design the first channel as a sub-sheet
2. duplicate_sheet: creates a copy with new UUIDs, a new file and its own part references

(the first free number of each prefix), so the copy needs no annotation

1. Repeat for each additional channel
2. validate_hierarchy from the root: confirms no reference is shared across the copies

Sequence: Pre-ERC annotation and validation

1. annotate_schematic with project_path — assign refs to all ? components
2. validate_hierarchy from root — check for duplicates, orphans, mismatches
3. If duplicates: set_component_property to reset to X?, then re-annotate
4. run_erc — only after validate_hierarchy is clean

Sequence: Debugging cross-sheet connectivity

1. trace_hierarchical_net — follow the net across sheet boundaries
2. get_net_connections — check connections on each sheet
3. list_cross_sheet_nets — see all nets crossing boundaries
4. Fix with add_sheet_pin, add_hierarchical_label, or connect_pins

Sequence: Restructuring hierarchy

1. flatten_hierarchy: merge all sheets into one new file whose netlist is the hierarchy's; the

hierarchy is left alone, and a design it cannot flatten faithfully is refused

1. OR move_hierarchical_sheet — reposition sheet blocks on the parent
2. OR reorder_sheet_pages on the root: change the page numbers the sheets are ordered by
3. validate_hierarchy — verify structure is still valid

Sequence: Cleaning up after modifications

1. remove_text — delete temporary text annotations
2. validate_hierarchy — check for new orphaned labels or direction mismatches
3. annotate_schematic — reassign any ? refs introduced during modifications

Verification and export:

• run_erc — run electrical rules check
• export_schematic — export schematic as PDF/SVG
• export_netlist — generate a netlist file (PCB import itself is update_pcb_from_schematic on the PCB server)
• export_bom — export bill of materials

Symbol authoring (when a part isn't in KiCad's libraries):

• create_symbol_library — create a project-local .kicad_sym file
• add_symbol — define a custom symbol with pins, footprint, datasheet
• list_lib_symbols / get_symbol_info — browse available symbols

Custom Symbols

When a part is not in KiCad's built-in libraries, create a custom symbol using MCP tools — NEVER by writing .kicad_sym files directly:

1. create_symbol_library — create a project-local .kicad_sym file

(if it doesn't exist yet)

1. add_symbol — define the symbol with pin names, pin types, pin

numbers, footprint, and datasheet

1. add_lib_symbol — load the custom symbol into the schematic

Verification

After completing placement and wiring:

1. Run run_erc to check for violations
2. Fix "power pin not driven" with PWR_FLAG symbols
3. Fix unconnected pins with wire_pins_to_net or no_connect_pin

3.5. If components have ? references, run annotate_schematic with project_path before re-running ERC.

1. Re-run ERC until clean