rpicarrierboard/.claude/skills/kicad-port/SKILL.md

name, description

name

description

kicad-port

Project skill for porting the Raspberry Pi CM5IO reference design into this custom CM5 carrier board. Use this skill on EVERY schematic/PCB task in this repo: editing .kicad_sch, defining or changing pinouts and nets, adding/removing circuit blocks, or verifying a design change. It encodes the source-of-truth for CM5 pins, the s-expression editing rules, and the MANDATORY verify loop (kicad-cli ERC + kicad-happy analyzer + diff-vs-reference). Always consult this skill before editing any KiCad file here, and run the verify loop after.

CM5 Carrier — Port Workflow

We are building a custom Raspberry Pi CM5 carrier board by porting the official CM5IO reference design. Work is currently in the schematic / pinout phase.

This is a diff-from-reference project: every change starts from a known-good reference and must stay electrically defensible against it. Claude is the editor (surgical s-expr text edits); the tooling below is the verifier. Never edit without verifying.

Source of truth (consult before any pin/net decision)

1. cm5-datasheet.pdf — authoritative CM5 module pinout, power sequencing, pin reservations.
2. CM5_Carrier_Pinout_BOM.md / CM5_Carrier_Design.md — this board's intended pin map and BOM.
3. refs/CM5IO.kicad_sch (+ CM5_GPIO, CM5_HighSpeed, PCIe-M2 sub-sheets) — the reference schematic we port FROM. Hierarchical design; sub-sheets are referenced by UUID.

If a pin assignment disagrees between the datasheet and any other doc, the datasheet wins — flag the discrepancy, don't silently pick one.

S-expression editing rules (footguns)

KiCad .kicad_sch / .kicad_pcb files are s-expression text — readable and Edit-able. But:

• NEVER hand-edit or hand-invent UUIDs. Copy-pasting a symbol/sheet block as text and reusing its UUID corrupts the schematic (KiCad treats duplicates as the same object). If you need a new instance, generate a fresh UUID: python3 -c "import uuid; print(uuid.uuid4())"
• Hierarchical nets: a net can carry multiple labels across sheets (the analyzer's LB-001 finding). Prefer one canonical label style per cross-sheet net; don't rename one half.
• Power nets need a driver: every power rail needs a power symbol or PWR_FLAG, or ERC fails.
• After ANY structural edit, re-run the verify loop below. A passing Edit is not a passing design.
• Coordinate edits through git. Another (context-free) agent may touch these files; commit small, review diffs, never blind-overwrite a sheet you didn't just read.

The verify loop (MANDATORY after every schematic change)

python3 here is Homebrew 3.14 (the kicad-happy scripts require Python ≥ 3.10). Scripts live under ~/.claude/skills/kicad/scripts/ (symlinked from kicad-happy/).

SCH=path/to/your.kicad_sch          # the file you changed
KSCR=~/.claude/skills/kicad/scripts

# 1. KiCad's own ERC (the hard gate — must be clean before commit)
kicad-cli sch erc --exit-code-violations --output /tmp/erc.json --format json "$SCH"
#    non-zero exit => fix or revert before proceeding.

# 2. kicad-happy structural review (catches what ERC won't: decoupling gaps,
#    connector ground ratios, protocol/voltage mismatches, multi-label nets)
python3 $KSCR/analyze_schematic.py "$SCH" --text          # human-readable
python3 $KSCR/analyze_schematic.py "$SCH" -o /tmp/head.json   # machine-readable

# 3. Diff against the committed reference baseline to see what your change moved
python3 $KSCR/diff_analysis.py analysis/baseline/cm5io.json /tmp/head.json --text

Treat new WARN/ERROR findings in step 2/3 as regressions to justify or fix — not noise.

Optional deeper checks

• SPICE (spice skill): validates analog subcircuits (regulator feedback dividers, RC/LC filters, crystal load caps). Requires a simulator on PATH — ngspice IS installed (/opt/homebrew/bin/ngspice) and the loop is validated end-to-end on the reference (8 subcircuits pass, incl. the 5V→3.3V buck feedback divider). Run after the analyzer: python3 ~/.claude/skills/spice/scripts/simulate_subcircuits.py <analysis.json> -o sim.json.
• Datasheets (datasheets skill): extract CM5 / IC specs from PDFs so analyzer findings are datasheet-backed rather than heuristic. Start with cm5-datasheet.pdf.

Schematic hygiene checklist (before declaring a sheet done)

• All nets named — no auto-generated Net-(R1-Pad1) names in the final design
• Power rails ALL_CAPS (+3V3, +5V, GND); active-low uses n prefix (nRESET, nCS)
• PWR_FLAG on every power net with no explicit driver
• No-connect markers on all intentionally unconnected pins
• Hierarchical port names match the nets they carry
• Reference designators follow convention (U/R/C/L/D/Q/J/SW/F/TP/BT), annotated by block
• Title block filled (project, rev, date, author, one-line description)
• Design notes added for non-obvious choices (pull-up values, protection ratings, placement)
• ERC passes with zero errors (step 1 above)

Reference shelf (not wired into the loop)

• MCP-KiCad/ — MCP server over pcbnew (SWIG). PCB/fabrication only, Linux/flatpak-first. Ignore until layout phase, and even then prefer kicad-cli pcb over it.
• kicad-claude-toolkit/ — greenfield "circuit-as-Python → PCB" generator + IPC bridge. Built for new designs, not porting. Only its schematic-hygiene guidance (folded in above) is relevant now.