Skip to content

hashgraph-online/awesome-codex-plugins / plugins/aklofas/kicad-happy/skills/kicad

Analyze KiCad projects and PDF schematics: schematics, PCB layouts, Gerbers, footprints, symbols, netlists, and design rules. Reviews designs for bugs, traces nets, cross-references schematic to PCB, extracts BOM data, checks DRC/ERC, DFM, power trees, and regulator circuits. Every finding carries a confidence label and evidence source with trust_summary rollup. Analyzes PDF schematics from dev boards, reference designs, eval kits, and datasheets. Supports KiCad 5–10. Use whenever the user mentions .kicad_sch, .kicad_pcb, .kicad_pro, PCB design review, schematic analysis, PDF schematics, reference designs, Gerber files, DRC/ERC, netlist issues, BOM extraction, signal tracing, power budget, DFM, or wants to understand, debug, compare, or review any hardware design. Also for "check my board", "review before fab", "what's wrong with my schematic", "is this ready to order", "check my power supply", "verify this circuit", OSHWA certification readiness, or any electronics/PCB design question.

FileKindSize
SKILL.mdskill md79.1 KB
references/config-reference.mdmarkdown19.1 KB
references/datasheet-verification.mdmarkdown16.5 KB
references/deep-review.mdmarkdown9.7 KB
references/design-intent.mdmarkdown5.6 KB
references/diff-analysis.mdmarkdown17.6 KB
references/file-formats.mdmarkdown15.1 KB
references/gerber-parsing.mdmarkdown33.5 KB
references/manual-gerber-parsing.mdmarkdown24.5 KB
references/manual-pcb-parsing.mdmarkdown17.2 KB
references/manual-schematic-parsing.mdmarkdown12.8 KB
references/net-tracing.mdmarkdown12.0 KB
references/oshwa-certification.mdmarkdown4.5 KB
references/output-schema.mdmarkdown33.4 KB
references/pcb-layout-analysis.mdmarkdown27.3 KB
references/pdf-schematic-extraction.mdmarkdown15.2 KB
references/report-generation.mdmarkdown56.3 KB
references/schematic-analysis.mdmarkdown63.9 KB
references/standards-compliance.mdmarkdown33.5 KB
references/supplementary-data-sources.mdmarkdown12.5 KB
references/what-if.mdmarkdown19.5 KB
review/README.mdmarkdown4.1 KB
review/fixtures/deep_review.example.jsonconfig1.2 KB
review/fixtures/design_context.example.jsonconfig388 B
review/fixtures/review_annotations.example.jsonconfig707 B
review/prompts/design_context.mdmarkdown4.9 KB
review/schemas/deep_review.schema.jsonconfig3.3 KB
review/schemas/design_context.schema.jsonconfig2.2 KB
review/schemas/review_annotations.schema.jsonconfig1.9 KB
review/scripts/_mini_jsonschema.pyscript6.6 KB
review/scripts/build_review_plan.pyscript2.3 KB
review/scripts/deep_review_gate.pyscript27.3 KB
review/scripts/merge_annotations.pyscript7.0 KB
review/scripts/validate_review.pyscript2.6 KB
scripts/.gitignoreother13 B
scripts/README.mdmarkdown23.4 KB
scripts/analysis_cache.pyscript42.1 KB
scripts/analyze_gerbers.pyscript90.9 KB
scripts/analyze_pcb.pyscript7.4 KB
scripts/analyze_schematic.pyscript6.7 KB
scripts/analyze_thermal.pyscript48.5 KB
scripts/analyzer_envelope.pyscript15.5 KB
scripts/capability_mode.pyscript10.2 KB
scripts/check_report_sections.pyscript10.6 KB
scripts/cross_analysis.pyscript69.4 KB
scripts/cross_verify.pyscript23.1 KB
scripts/design_intent.pyscript13.5 KB
scripts/detection_schema.pyscript26.0 KB
scripts/detector_helpers.pyscript15.2 KB
scripts/diff_analysis.pyscript23.5 KB
scripts/diff_engine.pyscript47.2 KB
scripts/domain_detectors.pyscript260.5 KB
scripts/envelopes/__init__.pyscript0 B
scripts/envelopes/cross_analysis.pyscript5.9 KB
scripts/envelopes/gerber.pyscript16.1 KB
scripts/envelopes/pcb.pyscript25.9 KB
scripts/envelopes/schematic.pyscript23.1 KB
scripts/envelopes/thermal.pyscript7.4 KB
scripts/export_issues.pyscript27.6 KB
scripts/fab_release_gate.pyscript29.8 KB
scripts/finding_schema.pyscript25.7 KB
scripts/gen_output_schema_md.pyscript9.2 KB
scripts/inputs_builder.pyscript4.0 KB
scripts/kicad_core/__init__.pyscript0 B
scripts/kicad_core/classify.pyscript32.5 KB
scripts/kicad_core/cli.pyscript4.2 KB
scripts/kicad_core/coords.pyscript2.0 KB
scripts/kicad_core/diagnostics.pyscript1.9 KB
scripts/kicad_core/executables.pyscript1.0 KB
scripts/kicad_core/fields.pyscript5.9 KB
scripts/kicad_core/fileio.pyscript5.4 KB
scripts/kicad_core/hotloop.pyscript3.1 KB
scripts/kicad_core/instances.pyscript5.7 KB
scripts/kicad_core/model.pyscript4.8 KB
scripts/kicad_core/netnames.pyscript19.1 KB
scripts/kicad_core/netquery.pyscript6.7 KB
scripts/kicad_core/pairing.pyscript1.9 KB
scripts/kicad_core/parts.pyscript28.9 KB
scripts/kicad_core/passives.pyscript10.0 KB
scripts/kicad_core/pdn.pyscript1011 B
scripts/kicad_core/project.pyscript43.2 KB
scripts/kicad_core/render.pyscript2.7 KB
scripts/kicad_core/sexp.pyscript12.6 KB
scripts/kicad_core/textvars.pyscript5.4 KB
scripts/kicad_core/token_cache.pyscript2.2 KB
scripts/kicad_core/values.pyscript14.1 KB
scripts/kicad_types.pyscript15.1 KB
scripts/lifecycle_audit.pyscript6.7 KB
scripts/lifecycle_engine.pyscript52.8 KB
scripts/lookup_detectors.pyscript29.9 KB
scripts/lookup_helpers.pyscript3.0 KB
scripts/methodology_gerbers.mdmarkdown23.1 KB
scripts/methodology_pcb.mdmarkdown22.2 KB
scripts/methodology_schematic.mdmarkdown43.1 KB
scripts/netlist_queries.pyscript4.2 KB
scripts/output_filters.pyscript16.8 KB
scripts/output_io.pyscript5.3 KB
scripts/pcb/__init__.pyscript0 B
scripts/pcb/assembly.pyscript58.3 KB
scripts/pcb/connectivity.pyscript27.7 KB
scripts/pcb/copper.pyscript61.0 KB
scripts/pcb/dfm.pyscript56.9 KB
scripts/pcb/geometry.pyscript59.5 KB
scripts/pcb/pipeline.pyscript30.3 KB
scripts/pcb/presentation.pyscript24.3 KB
scripts/pcb/reader.pyscript87.1 KB
scripts/pcb/routing.pyscript53.5 KB
scripts/project_config.pyscript23.1 KB
scripts/risk_summary.pyscript3.1 KB
scripts/run_id.pyscript1.7 KB
scripts/schema_codec.pyscript5.0 KB
scripts/schematic/__init__.pyscript0 B
scripts/schematic/audits.pyscript56.0 KB
scripts/schematic/bom_stats.pyscript6.1 KB
scripts/schematic/connectivity.pyscript62.9 KB
scripts/schematic/erc_pins.pyscript8.4 KB
scripts/schematic/hierarchy.pyscript21.5 KB
scripts/schematic/ic_analysis.pyscript21.4 KB
scripts/schematic/legacy_reader.pyscript49.4 KB
scripts/schematic/net_analysis.pyscript75.5 KB
scripts/schematic/pipeline.pyscript72.2 KB
scripts/schematic/presentation.pyscript20.9 KB
scripts/schematic/reader.pyscript64.7 KB
scripts/schematic/system_analyses.pyscript126.9 KB
scripts/signal_detectors.pyscript248.0 KB
scripts/summarize_findings.pyexecutablescript17.4 KB
scripts/validation_detectors.pyscript75.3 KB
scripts/what_if.pyscript68.4 KB

references/supplementary-data-sources.md

View on GitHub
# Supplementary Data Sources

When `analyze_schematic.py` returns incomplete data — typically for legacy KiCad 5 `.sch` projects where some `.lib` files are missing from the repo — use these additional project files to recover full analysis capability.

For analyzing external PDF schematics (manufacturer reference designs, eval boards, application notes) as a primary input source, see `pdf-schematic-extraction.md`.

## Table of Contents

1. [When You Need Supplementary Data](#when-you-need-supplementary-data)
2. [Netlist File (.net)](#netlist-file-net)
3. [Cache Library (-cache.lib)](#cache-library--cachelib)
4. [PCB Cross-Reference](#pcb-cross-reference)
5. [PDF Schematic Exports](#pdf-schematic-exports)
6. [Combined Workflow for Legacy Designs](#combined-workflow-for-legacy-designs)

---

## When You Need Supplementary Data

The schematic analyzer supports both formats with pin-level analysis:

| Format | Components | Nets | Pin-to-Net | Signal Analysis | Subcircuits |
|--------|-----------|------|-----------|----------------|-------------|
| Modern `.kicad_sch` (KiCad 6+) | Full | Full | Full | Full | Full |
| Legacy `.sch` (KiCad 4/5) | Full | Full | Near-full* | Near-full* | Near-full* |

\* The legacy analyzer parses `.lib` files (cache libraries, project libs, and built-in fallbacks for common symbols) to populate pin data. Coverage is typically 92–100% depending on which `.lib` files are available in the repo. Components whose `.lib` files are missing won't have pin data.

**Indicators that you may need supplementary sources:**
- Some components in the output have empty `pins` arrays
- Standard KiCad system library symbols (uncommon symbols from `power`, `device`, `conn` beyond R/C/L/D/LED/transistors) lack pin data
- Component inventory looks complete but specific ICs are missing from signal analysis

---

## Netlist File (`.net`)

**The most valuable supplementary source when `.lib` files are incomplete.** A KiCad 5 netlist export provides explicit pin-to-net mapping for all components, filling gaps where `.lib` files are missing from the repo.

### Finding the Netlist

Look for a `.net` file in the project directory, named after the project (e.g., `myboard.net`). Generated via KiCad 5's `Tools → Generate Netlist`. Not all projects have one — it's an optional export step.

### Netlist Structure

```
(export (version D)
  (components
    (comp (ref U1)
      (value STM32F407ZGTx)
      (footprint Package_QFP:LQFP-144_20x20mm_P0.5mm)
      (libsource (lib MCU_ST_STM32F4) (part STM32F407ZGTx) (description "..."))
      (sheetpath (names /) (tstamps /))
      (tstamp HEXID)
    )
    ...
  )
  (nets
    (net (code 1) (name GND)
      (node (ref U1) (pin 12))
      (node (ref C1) (pin 2))
      (node (ref R5) (pin 1))
    )
    (net (code 2) (name +3V3)
      (node (ref U1) (pin 100))
      (node (ref U1) (pin 28))
      (node (ref C3) (pin 1))
    )
    ...
  )
)
```

### What the Netlist Provides

| Data | How to Extract | Analysis Use |
|------|---------------|-------------|
| Pin-to-net mapping | `(node (ref U1) (pin 12))` in each `(net ...)` | Which pin of which component connects to which net |
| Complete net list | All `(net (code N) (name "..."))` entries | Every named and unnamed net in the design |
| Pin-level connectivity | All `(node ...)` entries per net | Full connectivity graph for subcircuit detection |
| Component verification | `(comp ...)` entries with ref, value, footprint | Cross-check against schematic analyzer output |

### Parsing the Netlist

The netlist is S-expression format — use the skill's `kicad_core/sexp.py`:

```python
from kicad_core.sexp import parse_file, find_all, find_first, get_value

tree = parse_file('project.net')
export = tree  # Root is the (export ...) node

# Extract component list
components = find_all(find_first(export, 'components'), 'comp')
for comp in components:
    ref = get_value(comp, 'ref')
    value = get_value(comp, 'value')
    footprint = get_value(comp, 'footprint')

# Build pin-to-net map
nets = find_all(find_first(export, 'nets'), 'net')
pin_net_map = {}  # (ref, pin) -> net_name
for net in nets:
    net_name = get_value(net, 'name')
    for node in find_all(net, 'node'):
        ref = get_value(node, 'ref')
        pin = get_value(node, 'pin')
        pin_net_map[(ref, pin)] = net_name
```

With this map, you can perform the same subcircuit detection as the modern analyzer: find voltage dividers by checking shared nets between resistor pairs, identify regulator topologies by tracing VIN/VOUT/FB pin connections, etc.

### Limitations

- Netlist files are snapshots — they may be stale if the schematic was edited after the last export
- Pin numbers in the netlist use the **symbol** pin numbering, which may not match physical pad numbering if the symbol library has errors
- Unnamed nets get auto-generated names like `Net-(U1-Pad12)` that differ between exports

---

## Cache Library (`-cache.lib`)

KiCad 5 projects include a `-cache.lib` file containing embedded copies of all symbol definitions used in the project. **The analyzer now parses cache libraries automatically** — this section documents the format for cases where you need to manually inspect or supplement the data.

### Finding the Cache Library

Look for `<project-name>-cache.lib` in the project directory. It's auto-generated by KiCad 5 and should always exist alongside a `.sch` file. The analyzer checks for this file first and uses it as the preferred source of pin data.

### Cache Library Structure

```
EESchema-LIBRARY Version 2.4
#
# STM32F407ZGTx
#
DEF STM32F407ZGTx U 0 20 Y Y 9 L N
F0 "U" ... reference
F1 "STM32F407ZGTx" ... value
F2 "Package_QFP:LQFP-144_20x20mm_P0.5mm" ... footprint
DRAW
...graphics...
X PA0 34 -1600 900 200 R 50 50 1 1 B      ; Pin definition
X PA1 35 -1600 800 200 R 50 50 1 1 B      ; X name number x y length orient sizeN sizeP unit convert type
...
ENDDRAW
ENDDEF
```

### Pin Definition Fields

The `X` lines define each pin:

```
X <name> <number> <x> <y> <length> <orientation> <sizeN> <sizeP> <unit> <convert> <type>
```

| Field | Example | Meaning |
|-------|---------|---------|
| name | `PA0`, `VDD`, `BOOT0` | Pin function name |
| number | `34`, `100` | Physical pin number (should match footprint pad) |
| unit | `1`-`N` | Which unit of a multi-unit symbol |
| type | `B`, `I`, `O`, `P`, `W`, `w`, `U` | Electrical type |

**Pin electrical types:**
| Code | Type | Description |
|------|------|-------------|
| `I` | Input | Logic input |
| `O` | Output | Logic output |
| `B` | Bidirectional | I/O, GPIO |
| `T` | Tri-state | Tri-state output |
| `P` | Passive | Resistor, capacitor |
| `W` | Power input | VDD, GND (power consumer) |
| `w` | Power output | Regulator output |
| `U` | Unspecified | Unknown function |
| `C` | Open collector | Requires pull-up |
| `E` | Open emitter | Requires pull-down |
| `N` | Not connected | NC pin |

### Analysis Uses

1. **Verify pin definitions**: Cross-reference pin numbers and names against the IC datasheet. Library pin mapping errors (symbol pin numbers not matching physical footprint pads) are a common source of manufacturing defects.

2. **Identify pin functions**: Pin names like `VIN`, `VOUT`, `FB`, `EN`, `SW`, `SDA`, `SCL` help classify component functions when the analyzer can't auto-detect them.

3. **Multi-unit verification**: Count `X` lines per unit number to verify all units of multi-unit symbols (quad op-amps, MCU pin banks) have the correct pins.

4. **Power pin identification**: Pins with type `W` (power input) tell you which pins need decoupling caps. Pins with type `w` (power output) identify regulator output pins.

---

## PCB Cross-Reference

When schematic analysis is incomplete, the PCB file provides an independent source of truth for net assignments — because PCB footprints use the physical pad numbering from the datasheet.

### Cross-Reference Workflow

1. Run `analyze_pcb.py` on the `.kicad_pcb` file
2. For each component, compare the PCB's pad-to-net assignments against:
   - The schematic analyzer's component list (same refs, same values?)
   - The netlist file's pin-to-net map (same pin→net associations?)
   - The cache library's pin definitions (pin numbers match pad numbers?)

### What Mismatches Reveal

| PCB Data | Schematic Data | Problem |
|----------|---------------|---------|
| Pad 3 = `+3V3` | Pin 3 = `GND` | **Library pin mapping error** — symbol pin numbers don't match footprint pads |
| Pad exists, net assigned | Component missing from schematic | Schematic out of sync with PCB |
| Component on PCB | Component has `(dnp yes)` in schematic | DNP not cleaned up, or intentional |
| Pad has net | Pin appears unconnected in netlist | Netlist is stale |

### Key PCB Fields for Cross-Reference

From `analyze_pcb.py` output, each footprint includes:
- `reference` — component designator (should match schematic)
- `value` — component value (should match schematic)
- `pad_nets` — dict keyed by pad number (the physical pin number from the datasheet); each value is `{net}`, plus `pin` (the pad's pin function) when the footprint names one
- `connected_nets` — deduplicated list of nets touching the footprint
- `sch_path` — UUID linking back to the schematic symbol
- `sheetname` / `sheetfile` — source schematic sheet

### Library Error Detection Pattern

The most dangerous bugs are library pin mapping errors. Detect them by:

1. From the cache library: build map of `(pin_name, pin_number)` for each component
2. From the netlist: build map of `(ref, pin_number) → net_name`
3. From the PCB: build map of `(ref, pad_number) → net_name`
4. For each component, verify that the netlist's pin_number→net matches the PCB's pad_number→net for the same physical pin

If pin N in the netlist connects to net A, but pad N in the PCB connects to net B, the symbol library has a pin mapping error.

---

## PDF Schematic Exports

If the project includes a PDF export of the schematic (or if you can visually compare against KiCad's schematic viewer), use it for visual verification of circuit topology.

### When PDF Helps

- **Confirming connections**: When the analyzer output is ambiguous about how components connect, the visual schematic makes it clear
- **Tracing signal paths**: Follow wires visually from IC pin to passive component to connector
- **Verifying design intent**: Designer annotations, notes, and layout on the schematic reveal what the circuit is supposed to do
- **Catching parser errors**: If the analyzer reports something that looks wrong, the PDF shows whether the schematic actually has that connection

### How to Use

Read the PDF pages (using page range selection if available), then correlate visual observations with the analyzer output. Focus on:
1. Key IC connections (power, signal, control pins)
2. Subcircuit boundaries (which passives belong to which IC)
3. Net labels and power symbols
4. Any designer annotations or notes

For comprehensive PDF schematic analysis techniques (when the PDF is the primary input, not just a supplement), see `pdf-schematic-extraction.md`.

---

## Combined Workflow for Legacy Designs

When working with a KiCad 5 legacy project, the analyzer handles most of the work automatically:

### Step 1: Run the schematic analyzer

```bash
python3 <skill-path>/scripts/analyze_schematic.py project.sch
```

The analyzer automatically parses `.lib` files (cache libraries and project libs), populates pin data, builds pin-to-net mapping, runs signal analysis, and detects subcircuits. Check the output for components with empty `pins` arrays — these are the ones missing `.lib` data.

### Step 2: Parse the netlist (if needed)

If some components lack pin data (their `.lib` files aren't in the repo), look for `project.net` in the project directory. Parse it to get explicit pin-to-net mapping for those components (see parsing instructions above).

### Step 3: Cross-reference with PCB

Run `analyze_pcb.py` on the `.kicad_pcb` file. Compare pad-to-net assignments against the analyzer's pin-to-net data to catch library pin mapping errors.

### Step 4: Visual verification (optional)

If a PDF export exists, use it to spot-check critical connections and verify your understanding of the circuit topology.

### Data Recovery Matrix

| Supplementary Source | What It Recovers | Priority |
|---------------------|-----------------|----------|
| Netlist (`.net`) | Pin-to-net mapping for components missing `.lib` data | **Highest** — fills remaining gaps |
| PCB (`.kicad_pcb`) | Pad-to-net verification, library error detection | Medium — cross-check, not primary source |
| PDF export | Visual circuit topology verification | Low — supplement, not data source |
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall