claude-skills/pcb-ai-engineer/SKILL.md

name, description

name

description

pcb-ai-engineer

Code-driven schematic and PCB design using Python. Primary backend: circuit-synth (pip install circuit-synth) with KiCad output. Covers full EE workflow: schematic capture as code, MCU integration (STM32, ESP32, nRF, RP2040, any MCU via extensible DB), power supply design, peripheral wiring, BOM generation, DRC/ERC checklists, and schematic review. Also supports SKiDL as alternative backend. Use this skill whenever the user mentions PCB design, circuit board, schematic, KiCad, Altium, EDA, hardware design, circuit-synth, SKiDL, component selection, BOM, DRC, ERC, power supply design, decoupling, voltage regulator, MCU pin assignment, or wants to describe electronics in Python code. Even if the user just names a chip (e.g. "STM32F407", "ESP32-S3", "nRF52840") in a hardware context — use this skill.

PCB AI Engineer Skill

Design electronics as code with Python, using circuit-synth as the primary backend and KiCad as the output format. Altium Designer can serve as a downstream editor for production-grade layouts.

Cross-reference: For firmware-level concerns (GPIO policy, watchdog strategy, brown-out testing, NASA/JPL Power of Ten rules), read the embedded-firmware-engineer skill. PCB design and firmware constraints are tightly coupled — always consider both.

1. Backend Libraries

Primary: circuit-synth (recommended)

pip install circuit-synth
# or: uv add circuit-synth

Current stable version: 0.12.x. Key features:

• @circuit decorator for hierarchical subcircuit composition
• Component(symbol=..., ref=..., footprint=..., value=...) with KiCad symbol library lookup
• Net(name) for named electrical nets; += operator for connections
• generate_kicad_project(output_dir) produces .kicad_pro, .kicad_sch, .kicad_pcb
• generate_bom() for bill of materials export
• Bidirectional KiCad sync (Python ↔ KiCad, KiCad remains source of truth)
• JLCPCB / DigiKey component search integration
• FMEA analysis built-in

API pattern (current, v0.12+):

from circuit_synth import circuit, Component, Net

@circuit(name="my_subcircuit")
def my_subcircuit():
    vcc = Net("VCC_3V3")
    gnd = Net("GND")

    mcu = Component(
        symbol="RF_Module:ESP32-S3-MINI-1",
        ref="U",
        footprint="RF_Module:ESP32-S2-MINI-1",
    )

    cap = Component(
        symbol="Device:C",
        ref="C",
        value="10uF",
        footprint="Capacitor_SMD:C_0603_1608Metric",
    )

    vcc += mcu["VDD"], cap[1]
    gnd += mcu["GND"], cap[2]

result = my_subcircuit()
result.generate_kicad_project("output/my_board")

Alternative: SKiDL

Use SKiDL when the user explicitly asks for it, or for legacy projects. SKiDL has stronger ERC and SPICE integration but weaker KiCad 8 schematic output.

from skidl import Part, Net, generate_netlist
r1 = Part("Device", "R", value="1K", footprint="Resistor_SMD:R_0805_2012Metric")

Backend selection rule

Signal	Backend
User says "circuit-synth" or no preference	circuit-synth
User says "SKiDL" or "skidl"	SKiDL
Existing project uses one of them	Match existing
User needs SPICE simulation	SKiDL
User needs KiCad 8 native schematic	circuit-synth

2. Project Structure

Recommended layout for a circuit-synth project:

project_root/
├── main.py                 # Top-level board assembly
├── mcu.py                  # MCU core + pin assignment
├── power.py                # Power supply subsystem
├── peripherals.py          # UART, I2C, SPI, USB, CAN blocks
├── connectors.py           # Board-level connectors, test points
├── sensors.py              # Sensor circuits (optional)
├── mcu_db.py               # MCU database (family → package → pinmap)
├── pyproject.toml          # Project metadata, circuit-synth dependency
├── requirements.txt        # circuit-synth~=0.12
└── out/
    └── kicad_project/      # Generated KiCad files

One file per logical subsystem. Each file exports a @circuit-decorated function. main.py composes them all into the final board.

3. MCU Database: Generic, Extensible

The MCU database (mcu_db.py) is a Python dict with the schema:

vendor → family → package → {
    description, pin_count,
    pinmap: { pin_number: {signal, roles: [...], alternate_functions: [...]} },
    capabilities: { peripheral_counts, features },
    voltage_profiles: [ {id, vcore, vio, vbat} ],
}

This is not a replacement for datasheets — it is a structured summary that the skill uses to generate skeleton circuits. The user fills in real data for their specific part number.

See references/mcu_db_schema.md for the full schema definition and examples for STM32F4, ESP32-S3, and a blank template.

Adding a new MCU

1. Find the datasheet for your target MCU.
2. Copy the blank template from references/mcu_db_schema.md.
3. Fill in pin assignments from the datasheet pinout table.
4. Add capability flags (USB, ETH, CAN, ADC count, etc.).
5. Register voltage profiles from the "Electrical Characteristics" section.

4. Design Workflow

Phase 1: Requirements → Architecture

1. Clarify requirements: What interfaces are needed? Power budget? Form factor?
2. Select MCU: Based on peripheral needs, check mcu_db.py or suggest additions.
3. Define power tree: Input source → regulators → rails → consumers.
4. Sketch block diagram: MCU, power, peripherals, connectors. (Can use Mermaid.)

Phase 2: Python → KiCad

1. Create mcu_db.py entry (or verify existing).
2. Write power.py — power supply subcircuit(s).
3. Write mcu.py — MCU core with decoupling, reset, boot, clock.
4. Write peripherals.py — UART, I2C, SPI, USB, CAN, ADC blocks.
5. Write main.py — compose everything, call generate_kicad_project().
6. Run python main.py — inspect generated KiCad project.

Phase 3: Review & Verify

Run the Schematic Review Checklist (see references/review_checklists.md):

• Power integrity: decoupling on every VDD pin, bulk caps, correct voltage rails
• Signal integrity: series resistors on high-speed lines, proper termination
• Connectivity: no floating inputs, all GND pins connected, ESD protection
• Mechanical: mounting holes, connector placement, keep-out zones

Run the BOM Review (see references/review_checklists.md):

• All components have valid footprints
• No DNP (Do Not Place) without justification
• Supplier availability verified (JLCPCB basic parts preferred)

Phase 4: KiCad → Production

1. Open generated .kicad_pro in KiCad.
2. Assign footprints (if not already set in Python).
3. Layout PCB, run DRC in KiCad.
4. Generate Gerber, BOM, CPL files for fabrication.
5. (Optional) Import into Altium for advanced layout / team collaboration.

5. Power Supply Design Guide

Read references/power_design.md for:

• Topology selection (LDO vs. Buck vs. Buck+LDO chain vs. Boost)
• Input protection (TVS, fuse, reverse polarity)
• Decoupling strategy (bulk + HF per rail, local per IC)
• Thermal considerations
• Reference circuits for common topologies

6. Handling User Requests

When the skill activates:

"Design a board for [MCU/application]":

1. Clarify: which MCU family? What peripherals? Power source? Form factor?
2. Check/create mcu_db.py entry.
3. Propose module structure (which .py files).
4. Generate code file by file, explain design decisions.
5. Remind about review checklists.

"Add [peripheral] to existing design":

1. Read existing code structure.
2. Add peripheral block function.
3. Wire into main.py.
4. Run review checklist for the changed subsystem.

"Review my schematic / find problems":

1. Read the Python circuit code.
2. Walk through references/review_checklists.md systematically.
3. Report findings with severity (critical / warning / suggestion).

"Generate BOM":

1. Use result.generate_bom() from circuit-synth.
2. Cross-check with JLCPCB/DigiKey availability if user requests.

7. Reference Files

In references/ directory:

• mcu_db_schema.md — MCU database schema, examples (STM32F4, ESP32-S3), blank template
• power_design.md — Power supply topology guide with reference circuits
• review_checklists.md — Schematic review, DRC, BOM review checklists

In scripts/ directory:

• validate_mcu_db.py — Validates mcu_db.py structure against schema
• bom_check.py — Parses BOM output, checks for missing footprints/values

8. Common Pitfalls

These mistakes appear repeatedly in AI-generated PCB designs. Be vigilant:

• Missing decoupling caps: Every VDD/AVDD pin needs its own 100nF cap, placed close. Bulk 10µF per power rail. VDDA gets a separate ferrite bead + cap.
• Floating inputs: Unused MCU inputs must be tied high/low or configured as output. Boot/mode pins especially — always have explicit pull-up/down.
• USB without ESD: Always add ESD protection diodes on USB D+/D- lines.
• I2C without pull-ups: External pull-ups are mandatory; internal pull-ups are too weak for most applications. 4.7kΩ to VCC is the safe default.
• Wrong crystal load caps: Calculate from crystal datasheet; don't guess 22pF.
• Power sequencing: Multi-rail designs may require sequencing (e.g., 1.8V core before 3.3V I/O).
• Thermal pad not connected: QFN/DFN exposed pads must connect to GND with thermal vias. ESP32 modules (MINI-1, WROOM) also have an exposed GND pad on the bottom.
• USB-C missing CC pull-downs: USB-C device mode requires 5.1kΩ pull-downs on CC1/CC2. Without them, a USB-C host will not provide VBUS power.
• ESP32 strapping pins: IO0, IO3, IO45, IO46 have boot-mode significance on ESP32-S3. Do not connect peripherals to strapping pins without understanding boot implications.
• STM32 VCAP pin missing cap: STM32F4/F7/H7 have VCAP pins for the internal voltage regulator. Each needs a 2.2µF (or 4.7µF) ceramic to GND per datasheet.
• LDO output cap too small: AMS1117 requires minimum 22µF low-ESR on output. Generic LDOs vary — always check the regulator datasheet for minimum Cout and ESR range.
• SPI CS# floating at boot: Add pull-ups (10kΩ) on all SPI chip-select lines to prevent unintended device selection during MCU reset/boot.

---