--- name: kicad-schematic description: | Workflow skill for KiCAD schematic design via MCP tools. Triggers on: "design a circuit", "add a component", "wire up", "connect pins", "build schematic", "place resistor", "place cap", "place IC", "schematic", "add symbol", "net label", "power rail". argument-hint: "[circuit description or task]" --- # KiCAD Schematic Design Workflow This skill guides Claude to design schematics using Konnect MCP tools. ALL modifications go through MCP tools — never edit .kicad_sch files directly. --- ## Toolset Loading Before any schematic work, load the required toolsets: ``` load_toolset('sch_components') # place, move, rotate, delete symbols load_toolset('sch_wiring') # wires, net labels, power symbols, connections load_toolset('sch_analysis') # connection validation, short and orphan checks load_toolset('sch_export') # direct ERC and rendered schematic evidence load_toolset('project') # save_project before formal checks ``` Load additional toolsets as needed: ``` load_toolset('library') # search_symbols, get_symbol_info, list_symbol_libraries load_toolset('sch_batch') # batch operations for 3+ items ``` Always call `get_active_toolsets()` first to see what is already loaded. --- ## Component Placement Read [`references/common-lib-ids.md`](references/common-lib-ids.md) when choosing a common generic KiCad symbol. It is a quick-start index, not an allowlist; search the active libraries when the required part is absent or package-specific. ### Workflow 1. Search the library first: use `search_symbols` to find the correct lib_id 2. Get pin info: use `get_symbol_info` to see pin names, numbers, and positions 3. Place on the 1.27mm grid (KiCAD default schematic grid) 4. Verify placement with `list_schematic_components` ### Package-sensitive and custom parts Before placing or wiring a custom symbol, a manufacturer-specific discrete, or any package whose view can be mirrored, require the `kicad-library` skill's **accepted physical pin map** for the exact MPN and package suffix. The map must join each datasheet lead to the symbol pin and footprint pad, identify the drawing view/direction, reconcile duplicate and mechanical pads, and include query-back plus disposable rendered inspection. `get_symbol_info` proves the library data that exists; it does not prove that data matches the package. If the accepted physical pin map is missing, incomplete, based on a different suffix, or ambiguous about top/bottom/mating view, stop before real schematic placement. Do not infer physical numbering from a generic symbol name or from the order pins appear on screen. ### Common Library IDs | Component | lib_id | |-----------------|--------------------------------| | Resistor | `Device:R` | | Capacitor | `Device:C` | | Capacitor Polar | `Device:C_Polarized` | | Inductor | `Device:L` | | LED | `Device:LED` | | Diode | `Device:D` | | Zener | `Device:D_Zener` | | NPN Transistor | `Transistor_BJT:Q_NPN_BEC` | | PNP Transistor | `Transistor_BJT:Q_PNP_BEC` | | N-MOSFET | `Transistor_FET:Q_NMOS_GDS` | | P-MOSFET | `Transistor_FET:Q_PMOS_GDS` | | 2-pin Connector | `Connector_Generic:Conn_01x02` | | 4-pin Connector | `Connector_Generic:Conn_01x04` | | Ground | `power:GND` | | +3.3V | `power:+3V3` | | +5V | `power:+5V` | | VCC | `power:VCC` | | VDD | `power:VDD` | ### Rotation Conventions - 0 degrees: default orientation (pins left/right) - 90 degrees: rotated CCW (useful for vertical components) - 180 degrees: flipped horizontally - 270 degrees: rotated CW Power symbols: GND uses 0 (arrow points down), VCC/VDD/+3V3/+5V use 0 (arrow points up). ### Spacing Guidelines - Between ICs: 30-50mm horizontal, 20-30mm vertical - Between passive components: 10-15mm - Between a decoupling cap and its IC: 5-10mm - Leave room for wiring: minimum 5mm between component pins and other elements --- ## Wiring Read [`references/wiring-patterns.md`](references/wiring-patterns.md) when choosing between direct wires and labels or when building one of its common subcircuits. Verify every named pin against the placed symbol before applying a pattern. ### Connection Methods — Decision Table | Scenario | Method | Why | |-----------------------------------------|-------------------------|------------------------------------------| | Two pins physically close (<30mm) | `connect_pins` | Direct wire, auto-routed | | Named signal (SDA, MOSI, EN, etc.) | `connect_to_net` | Stub wire + net label, cleaner | | Power rail (VCC, GND, +3V3) | `add_power_symbol` | Proper power symbol, global net | | Bus signals (D0-D7) | `connect_to_net` | Net labels with bus naming | | Cross-sheet signal | Global label | Connects across schematic sheets | | Multiple pins to same net (3+) | `batch_connect_to_net` | Efficient bulk operation | ### connect_pins Use for direct pin-to-pin connections. The tool auto-routes with L-bends. ``` connect_pins(schematic, ref1, pin1, ref2, pin2) ``` - Specify pins by pin number (from get_schematic_pin_locations) - Works best when pins are nearby and facing each other - Automatically creates wire segments with proper bends ### connect_to_net Use for named nets. Creates a short stub wire and attaches a net label. ``` connect_to_net(schematic, reference, pin_number, net) ``` - Preferred for signals that connect to 3+ pins - Preferred for named buses and control signals - Keeps schematic clean and readable - Net name must be consistent across all connections - Name the pin rather than passing `pin_x`/`pin_y`: the stub then points away from the symbol body on its own, instead of the label text running back across the pin names. Override with `direction` only to fix a layout clash. - `batch_connect_to_net` does the same for many pins in one read/write, and places its labels directly on the pin endpoints without stubs. - Placing a label by hand with `add_schematic_net_label` instead? Take its rotation from `orientation_degrees` in `get_schematic_pin_locations`, or the text reads back across the symbol's pin names. ### add_power_symbol Use for all power connections, in preference to labelling a pin with the rail name. ``` add_power_symbol(schematic, power_net, x, y, rotation?) ``` - Takes coordinates, not a reference and pin number. Place it on the pin endpoint (from `get_schematic_pin_locations`) — a power symbol carries its pin at its own origin, so the two coinciding is the connection. - `power_net` is loaded as `power:`, so it must name a symbol in KiCad's power library: `+3V3` and `+12V`, never `3V3` or `12V`. A miss is an error and nothing is placed. - `rotation` defaults to 0 — see Rotation Conventions above. - A power pin landing mid-segment on a wire gets its junction dot automatically, in either order: symbol onto an existing wire, or a wire routed across an already-placed symbol. --- ## Batch Operations Load `sch_batch` toolset when placing 3 or more components or making bulk connections. ### batch_place_components Place multiple components in one call. Provide `schematic` and a `components` array of `{lib_id, x, y, rotation?, reference?, value?, unit?}` objects. Pass `reference` explicitly for each component -- it is not auto-assigned. ### batch_connect_to_net Connect multiple pins to the same net in one call. Ideal for: - Connecting all VCC pins on an IC - Connecting all GND pins - Bus signals across multiple ICs ### batch_edit_schematic_components Bulk-modify component properties (values, footprints, fields) across multiple components. ### When to Use Batch vs Individual - 1-2 components: individual calls - 3+ components: batch operations - Mixed operations (place + wire): do placement batch first, then wiring batch --- ## Common Patterns ### Decoupling Capacitor Place 100nF cap (Device:C) within 5mm of IC power pin. Connect one pin to VCC via power symbol, other pin to GND via power symbol. One cap per VCC/VDD pin. ### Pull-up Resistor Place resistor (Device:R) vertically. Connect one pin to the signal net via `connect_to_net`, other pin to VCC via `add_power_symbol`. Typical values: 4.7k for I2C, 10k for general. ### Voltage Divider Two resistors in series, vertically aligned. Top to input net, middle junction to output net, bottom to GND. Use `connect_to_net` for input/output, `add_power_symbol` for GND. ### LED with Current-Limiting Resistor Resistor in series with LED. Connect resistor to signal/power, resistor to LED anode, LED cathode to GND. R = (Vsupply - Vf) / If. Typical: 330R for 3.3V, 470R for 5V. ### Bypass/Decoupling Filter For analog circuits: 100nF ceramic + 10uF electrolytic in parallel, close to power pins. Place ceramic closest to IC. ### Crystal Oscillator Crystal (Device:Crystal) between XI and XO pins. Two load capacitors from each crystal pin to GND. Typical load caps: 12-22pF. Optional 1M feedback resistor across crystal. --- ## Post-Placement Verification After placing components and wiring, always run these checks: ### annotate_schematic Assigns reference designators (R1, C1, U1, etc.) to all unannotated components. Run after all placement is complete. ### validate_wire_connections Checks that all wires connect properly to pins. Reports: - Dangling wire ends - Wires that miss pins - Overlapping wires ### validate_component_connections Verifies that components have the expected connections. Reports: - Unconnected pins that should be connected - Missing power connections ### find_orphan_items Finds floating wires, labels, and symbols that are not connected to anything. ### Verification Workflow 1. Place and wire complete functional blocks. 2. Run `annotate_schematic`, then save with `save_project`. 3. Run `validate_wire_connections` and `validate_component_connections`. 4. Run `find_shorted_nets`; reconcile each finding against the intended nets. 5. Run `find_orphan_items` as a heuristic and corroborate its findings. 6. Run direct KiCad ERC with `run_erc` and classify every violation. 7. Run `render_schematic_png` with inline output and inspect the actual image. 8. Fix findings and repeat every check invalidated by the edits. --- ## Visual feedback loop The agent can see its own schematic. After meaningful edits: 1. `render_schematic_png` — rasterize the sheet (pass `inline` true to get the image back as base64 and actually look at it). 2. `set_visual_baseline` — capture the known-good render before a batch of edits (stored under the project's own state directory with the source hash and renderer identity). 3. `compare_visual_baseline` — after edits: PASS/DRIFT against a 2% content threshold with the changed region's bounding box. "No baseline stored" is a normal state, and a baseline from an older renderer is flagged rather than silently trusted. Use the loop to catch what connectivity checks cannot. Completion requires coherent functional grouping, label-inclusive overlap inspection, clear signal flow, and page-boundary acceptance for every symbol, label, and note. Inspect the image itself; a successful render command is not visual acceptance. ## Evidence and completion gate Apply this order when evidence disagrees: 1. Exact requirements and manufacturer datasheets. 2. Direct KiCad ERC and saved/exported connectivity. 3. Direct net, short, pin, and component evidence from Konnect. 4. Aggregate review results. 5. Heuristic orphan, single-pin, decoupling, and best-practice findings. A weaker heuristic may raise a question but does not override stronger direct evidence. If any required check did not run, failed structurally, returned impossible coverage, or contradicts stronger evidence without resolution, the result is `INCOMPLETE`. Report the blocked evidence and stop short of a clean or production-ready claim. ## Rules 1. **Never edit .kicad_sch files directly** — all changes go through MCP tools 2. **Never guess pin numbers** — always use `get_schematic_pin_locations` or `get_symbol_info` to look up pin numbers before connecting 3. **Always verify after changes** — run validation tools after placing and wiring 4. **Use the grid** — all placements on 1.27mm grid 5. **Search before placing** — use `search_symbols` to confirm lib_id exists 6. **Power symbols for power** — use `add_power_symbol` for rails, not net labels 7. **Net labels for named signals** — keeps schematics readable 8. **Save frequently** — call `save_project` after major operations 9. **Load toolsets first** — check `get_active_toolsets()` and load what you need before starting 10. **Batch for bulk** — use batch toolset for 3+ repetitive operations