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

---
name: pcb-ai-engineer
description: >
  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)

```bash
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+):

```python
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.

```python
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:

```text
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
- `altium_celestial_library_setup.md` — Windows setup guide for the Celestial
  Altium Library (212k-component free DbLib): portal registration, Git LFS clone,
  SQLNCLI11/MSOLEDBSQL driver install via direct Microsoft MSIs (no Store / no
  winget msstore), network routing for `db.altiumlibrary.com:1433`, Altium
  Designer configuration, full troubleshooting

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.

---