/kicad-library

name: kicad-library
description: |
  Library management workflow for KiCAD — creating symbols, footprints, and managing libraries
  via MCP tools. Triggers on: "create a symbol", "make a footprint", "custom component",
  "register library", "find a part", "pin numbering", "new symbol", "new footprint",
  "add to library", "library path", "pad layout".
argument-hint: "[component or library task]"

KiCAD Library Management Workflow

This skill guides Claude through creating and managing KiCAD symbols, footprints, and libraries using Konnect MCP tools. ALL modifications go through MCP tools — never edit .kicad_sym or .kicad_mod files directly.

---

Toolset Loading

load_toolset('library')    # search_symbols, search_footprints, create_symbol, create_footprint,
                           # edit_footprint_pad, set_footprint_graphics, set_footprint_metadata,
                           # set_footprint_models, get_footprint_info, register_symbol_library,
                           # register_footprint_library, get_symbol_info
load_toolset('pcb_components') # update_footprints_from_library for placed instances

Always call `get_active_toolsets()` first to see what is already loaded.

---

Refresh Placed Footprints

Editing a `.kicad_mod` library file does not change copies already embedded on a board. After a library edit, call `update_footprints_from_library`; it is Konnect's MCP equivalent of KiCad **Tools → Update Footprints from Library**.

This operation is not `update_pcb_from_schematic`. Schematic sync updates schematic-owned fields while preserving artwork. Library refresh replaces supported library-owned pads, graphics, attributes, metadata, and 3D models while preserving the placed footprint's reference, value, position, rotation, board side, locked state, KIID, symbol metadata, instance overrides, and pad nets by logical pad number.

Always dry-run first:

update_footprints_from_library(
  board,
  references?,
  library_ids?,
  dry_run,
  expected_plan_revision?
)

• Use `dry_run=true` and review `status`, `coverage`, `changes`, and

`diagnostics`.

• Apply with `dry_run=false` and the exact returned `expected_plan_revision`.
• Keep the requested board open in live KiCad; there is no closed-board file

fallback.

• One successful apply is one KiCad undo entry.
• A stale plan, unresolved library, removed connected pad, or unsupported

library content returns a non-mutating conflict for the whole selection.

---

Search First Principle

**Always search existing libraries before creating custom components.**

search_symbols(query)       # Search all symbol libraries
search_footprints(query)    # Search all footprint libraries

KiCAD ships with extensive libraries. Common parts almost always exist:

• Standard passives (R, C, L) → `Device` library
• Connectors → `Connector_Generic`, `Connector_USB`, `Connector_HDMI`, etc.
• Common ICs (STM32, ATmega, LM7805, NE555) → manufacturer-specific libraries
• Transistors/MOSFETs → `Transistor_FET`, `Transistor_BJT`

Only create a custom symbol/footprint when:

• The part does not exist in any library
• The existing symbol has wrong pin count/arrangement
• You need a proprietary/unusual package

---

Symbol Creation

Pin Numbering — the datasheet decides, not a convention

**There is no safe universal pin-numbering rule for a real part.** Physical lead numbers are defined by the exact manufacturer part number and package suffix. BJT and MOSFET lead order varies between manufacturers, packages and variants; bottom-view, mirrored, socketed and connector drawings reverse it. A symbol can be syntactically valid and still be electrically wrong when its pins and the footprint's pads describe different physical leads.

Even KiCad's own generic symbols do not follow one order — `Device:LED` is **pin 1 = K (cathode), pin 2 = A (anode)**, the opposite of the "pin 1 = anode" rule people expect. Check, do not assume.

Before creating or wiring a package-sensitive part:

1. `search_symbols` / `list_symbols_in_library` first — prefer an existing library symbol over authoring a new one. 2. Confirm the exact manufacturer part number **and** package suffix. 3. Note the drawing view of every datasheet figure (top, bottom, component, solder, mating). An unstated view is the most common source of mirrored parts. 4. Walk the physical leads from the documented key, in the documented direction. 5. Reconcile three counts: datasheet leads, symbol pins, footprint pads. Document any intentional duplicate or mechanical-only pad. 6. Read the result back with `get_symbol_info` and `get_footprint_info` rather than trusting what you just wrote. 7. **Refuse to use the part in a real schematic** while any mirror, reversal, duplicate, missing lead or view ambiguity is unresolved.

Physical pin-map acceptance contract

For every custom or package-sensitive part, complete this record before the symbol and footprint are accepted. "Looks sequential" and a matching pin count are not evidence.

Record the manufacturer, exact MPN and package suffix, datasheet document number/revision, source URL, relevant page numbers, symbol library ID, and footprint library ID. Then add one row for **every physical lead**:

| Datasheet lead | Function | Symbol pin / name / type | Footprint pad | X/Y (mm) | Drawing view / direction | Evidence | |---|---|---|---|---|---|---| | 1 | Example only | 1 / NAME / passive | 1 | 0.00 / 0.00 | bottom view, clockwise from key | datasheet p. N, figure M |

Apply these rules to the table:

• Walk from the datasheet's documented key, notch, dot, flat, bevel, or other

datum in the stated direction. State top, bottom, component, solder, pin, or mating view in every row; never silently translate between views.

• Give repeated physical leads separate rows even when they share one

electrical function. List exposed pads, shields, mounting tabs, and mechanical holes separately and state whet