bom · diff

git:20260427.3649179 to git:20260710.9da1c93

9 added, 3 removed. Audit A to A.

---

name: bom

- description: "BOM (Bill of Materials) management for electronics projects — the primary orchestrator skill that coordinates DigiKey, Mouser, LCSC, element14, JLCPCB, PCBWay, and KiCad skills into a unified workflow. Create, update, and maintain BOMs with part numbers, costs, quantities stored as KiCad symbol properties. ALWAYS trigger this skill for any task involving component sourcing, pricing, ordering, distributor searches, BOM export, or fabrication preparation — even if the user names a specific distributor or fab house (e.g. \"search DigiKey for...\", \"generate JLCPCB BOM\", \"order from Mouser\"). This skill decides which distributor/fab skills to invoke and in what order. Also trigger on phrases like \"what parts do I need\", \"order components\", \"how much will this cost\", \"export for JLCPCB\", \"find parts for this board\", \"cost estimate\", \"compare pricing\", or \"check stock\"."

+ description: >

+ Manage an electronics bill of materials across distributors and fabricators: part

+ selection, stock, pricing, alternates, ordering, KiCad properties, and BOM/CPL export.

+ Use for distributor-neutral sourcing, cost comparison, order preparation, or requests

+ such as "what parts do I need" and "export for JLCPCB". Do not take over schematic

+ analysis or a complete new-design workflow unless the requested task is specifically

+ its sourcing/manufacturing stage.

---

# BOM Management

- > **Disambiguation:** This skill handles BOM sourcing, pricing, and ordering. For *schematic analysis* (tracing nets, reviewing designs, checking ERC), use `/kicad`. For *creating new designs from scratch*, use `/circuit-weaver`.

+ > **Disambiguation:** This skill handles BOM sourcing, pricing, and ordering. For schematic analysis use `kicad`; for a complete new design use `circuit-weaver`.

BOM data lives in **KiCad schematic symbol properties** as the single source of truth. This skill orchestrates the full lifecycle: analyze the schematic, search distributors, validate parts, write properties back, export tracking CSVs, and generate order files.

## Related Skills

| Skill | Purpose |

|-------|---------|

| `kicad` | Read/analyze schematics, PCB, footprints |

| `digikey` | Search DigiKey, download datasheets (primary prototype source) |

| `mouser` | Search Mouser (secondary prototype source) |

| `lcsc` | Search LCSC (production/JLCPCB parts) |

| `element14` | Search Newark/Farnell/element14 (international) |

| `jlcpcb` | PCB fabrication & assembly ordering |

| `pcbway` | Alternative PCB fab & assembly |

## Scripts

Use `<skill-path>` to reference the BOM skill directory.

```bash

# Analyze schematic (JSON output, recursive sub-sheets)

python <skill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive

# Export BOM tracking CSV (creates new or merges with existing)

python <skill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive

# Generate per-distributor order files (5 boards + 2 spares/line)

python <skill-path>/scripts/bom_manager.py order bom/bom.csv --boards 5 --spares 2

# Quick single-distributor order (bypasses Chosen_Distributor column)

python <skill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey

# Write properties to schematic (dry-run first, then apply)

echo '{"R1": {"MPN": "RC0805FR-0710KL", "Manufacturer": "Yageo"}}' \

| python <skill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch --dry-run

# Sync datasheet URLs from index.json back into schematic Datasheet properties

python <skill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive --dry-run

```

## Workflow

Skip steps that don't apply. Common shortcuts:

- **"Add Mouser PNs"** — search Mouser by MPN for each part → validate → write to schematic → update CSV

- **"Fill in the gaps"** — run analyzer with `--gaps-only`, address each missing field

- **"Update datasheet URLs"** — run `sync_datasheet_urls.py` to backfill empty Datasheet fields from index.json

- **"Prepare for production"** — ensure every part has an LCSC number, check stock, set Chosen_Distributor to LCSC

### Step 1: Understand the Project

```bash

python <skill-path>/scripts/bom_manager.py analyze path/to/schematic.kicad_sch --json --recursive

```

The output tells you the project's field naming convention, which distributors are populated, what's missing, and the preferred distributor. Also look for an existing BOM tracking CSV in the project directory or `bom/` folder.

The script covers common patterns, but some projects use internal key systems or parametric fields. See `references/part-number-conventions.md` for the full catalog. Read the schematic if something seems off.

### Step 2: Sync Datasheets

**Do this immediately.** Datasheets are essential context for validation and part selection. Run the preferred distributor's sync first; if some fail, try others — they share the same `datasheets/` directory and skip already-downloaded parts.

```bash

python <digikey-skill-path>/scripts/sync_datasheets_digikey.py path/to/schematic.kicad_sch --recursive

python <lcsc-skill-path>/scripts/sync_datasheets_lcsc.py path/to/schematic.kicad_sch --recursive

python <element14-skill-path>/scripts/sync_datasheets_element14.py path/to/schematic.kicad_sch --recursive

```

DigiKey is best (direct PDF URLs). element14 is reliable (no bot protection). LCSC works for LCSC-only parts. Mouser is a last resort (often blocks downloads).

**Tell the user where datasheets are** (e.g., `hardware/<project>/datasheets/`). They'll reference them often.

**Cross-revision projects:** Use a single shared datasheets directory at the project level rather than per-revision. The same MPN's datasheet doesn't change between revisions.

Re-sync after writing new MPNs (Step 5) — the scripts are idempotent. Then backfill Datasheet URLs into the schematic:

```bash

python <skill-path>/scripts/sync_datasheet_urls.py path/to/schematic.kicad_sch --recursive

```

This reads `datasheets/index.json` and writes discovered datasheet URLs into empty schematic `Datasheet` properties. Opportunistic — only fills blanks. If a schematic already has a different URL, it warns about the mismatch without overwriting (use `--overwrite` to replace). Run with `--dry-run` first to preview.

### Step 3: Gather Part Information

**Watch for comma-separated MPNs.** Some symbols track multiple physical parts (e.g., battery holder + clip). Split on commas and search each MPN independently — searching the combined string matches the wrong product.

Search strategy based on what's available:

- Has MPN → search distributors by MPN to get their PNs and stock

- Has distributor PN but no MPN → search that distributor, get MPN, then search others

- Has only Value + Footprint → search by description (e.g., "100nF 0402 X7R 16V")

Use the project's preferred distributor first, then alternates. Prototype: DigiKey primary, Mouser secondary. Production: LCSC.

### Step 4: Validate Matches

**Don't assume existing PNs are correct** — distributor PNs go stale (discontinued, renumbered). Verify existing PNs resolve against the API. If a PN returns 404, flag it for replacement.

For every match, verify:

1. **Package** matches the schematic footprint (see cross-reference table below)

2. **Specs** match (capacitance, resistance, voltage, tolerance)

3. **Description** makes sense (a resistor ref should get a resistor)

4. **Lifecycle** — not obsolete or EOL

5. **Datasheet URL** is a direct PDF link (not a product page)

If ambiguous, ask the user. A wrong part is worse than a missing part.

### Step 5: Update the Schematic

**KiCad coexistence.** The script detects KiCad's lock file and warns but proceeds. KiCad doesn't auto-detect external changes — it keeps its in-memory copy. If KiCad is open, tell the user: *"Close and reopen the schematic (File → Open Recent) to see the changes. Don't save from KiCad first."*

If unsaved KiCad work exists, ask them to save first (Ctrl+S), then run the script, then reopen.

```bash

echo '{"R1": {"MPN": "RC0805FR-0710KL", "Manufacturer": "Yageo", "DigiKey": "311-10.0KCRCT-ND"}}' \

| python <skill-path>/scripts/edit_properties.py path/to/schematic.kicad_sch

```

**Backups:** By default, no `.bak` file is created (git tracks changes). Pass `--backup` if the schematic is not in a git repo or has uncommitted changes the user wants to preserve.

**Respect the project's convention.** Write to `"Digi-Key_PN"` if that's what exists, not `"DigiKey"`. Use canonical names only for new projects.

**Always write Manufacturer alongside MPN** — every API returns it, it's free data.

### Step 6: Update the BOM Tracking CSV

```bash

python <skill-path>/scripts/bom_manager.py export path/to/schematic.kicad_sch -o bom/bom.csv --recursive

```

CSV columns are dynamic — only distributors the project uses get columns. Base columns: Reference, Qty, Value, Footprint, MPN, Manufacturer. Each active distributor gets a PN column + stock column. Tail columns: Chosen_Distributor, Datasheet, Validated, DNP, Notes.

**Merge behavior:** Re-exporting preserves user-managed columns (stock, Chosen_Distributor, Validated, Notes) while updating schematic-derived columns.

### Step 7: Check Stock

For each part with a distributor PN, query current stock via the corresponding distributor skill. Update stock columns in the CSV. Stock data goes stale — note the date and re-check before ordering.

If the chosen distributor is out of stock, flag it and suggest the alternate.

### Step 8: Set Chosen Distributor

Factors: stock availability, price at order qty, minimum order/multiples, lead time, shipping consolidation (fewer distributors = fewer shipments).

For prototypes, consolidate to 1-2 distributors (DigiKey + Mouser). For production, LCSC/JLCPCB is cheapest.

### Step 9: Re-Sync Datasheets & URLs

Re-run Step 2 (download + URL backfill) to pick up parts added in Steps 3-5. Fast — already-downloaded files are skipped.

### Step 10: Validate Datasheets Against Design

Read downloaded datasheets and verify parts are functionally correct for the circuit. This catches wrong-part-number errors that Step 4 might miss.

**What to check by type:**

- **Passives** — voltage rating vs rail voltage, temperature coefficient, power dissipation

- **Regulators** — Vin range, Vout, max current, quiescent current

- **MCUs/ICs** — supply voltage, I/O levels, peripherals, pinout

- **Connectors** — pin count, pitch, current/voltage rating

- **MOSFETs** — Vds, Rds(on), gate threshold, thermal dissipation

- **Diodes** — Vf, Vr, current rating, recovery time

For large BOMs (50+ parts), focus on power components, critical signal paths, and anything the user flagged. Commodity passives usually don't need deep review.

### Step 11: Generate Order Files

**Ask how many boards** if not already known — this sets the `--boards` multiplier.

**Pre-flight:** verify no gaps, CSV is current, Chosen_Distributor is set (or use `--distributor` flag), stock is fresh.

```bash

# Using Chosen_Distributor column, 5 boards + 2 spares

python <skill-path>/scripts/bom_manager.py order bom/bom.csv -o bom/orders/ --boards 5 --spares 2

# Or quick single-distributor order

python <skill-path>/scripts/bom_manager.py order bom/bom.csv --distributor digikey

```

`--boards` multiplies all quantities. `--spares` adds a flat extra per line after multiplication. `--distributor` bypasses Chosen_Distributor — generates an order for all parts with that distributor's PN.

Comma-separated PNs (accessories) are auto-split into separate order lines. DNP parts excluded. The script produces one file per distributor in the correct upload format (see `references/ordering-and-fabrication.md` for format details).

Present the order summary and let the user review/edit before ordering.

**Cost estimate:** After generating order files, query pricing from distributor APIs at the order quantity and present a total per distributor. See `references/ordering-and-fabrication.md` for the cost summary template.

## Package/Footprint Cross-Reference

| Imperial | Metric | KiCad Footprint |

|----------|--------|----------------|

| 0201 | 0603 | `R_0201_0603Metric` |

| 0402 | 1005 | `R_0402_1005Metric` |

| 0603 | 1608 | `R_0603_1608Metric` |

| 0805 | 2012 | `R_0805_2012Metric` |

| 1206 | 3216 | `R_1206_3216Metric` |

Replace `R_` with `C_` or `L_` as appropriate. Prefix with `Resistor_SMD:`, `Capacitor_SMD:`, etc.

## BOM Diffing

When the schematic changes between revisions, compare the old and new BOM to identify added, removed, and changed parts. Highlight which new parts need sourcing.

## Interactive BOM (ibom)

Generates an HTML page showing component locations on the PCB — essential for hand-assembly.

```bash

pip install InteractiveHtmlBom

generate_interactive_bom board.kicad_pcb \

--dest-dir bom/ --name-format "%f_ibom_%r" \

--extra-fields "MPN,Manufacturer,DigiKey,Mouser,LCSC" \

--group-fields "Value,Footprint,MPN" \

--checkboxes "Sourced,Placed" --dnp-field "DNP" --no-browser

```

## Reference Files

Read these when you need detailed lookup data:

- `references/kicad-fields.md` — field definitions, aliases, S-expression format, part number patterns

- `references/ordering-and-fabrication.md` — distributor paste formats, gerber export, CPL, cost templates

- `references/part-number-conventions.md` — detailed analysis of naming patterns across 56+ real projects

## Production Readiness Checklist

- [ ] All parts have MPN and LCSC numbers (for JLCPCB) or MPN (for PCBWay)

- [ ] No obsolete or EOL parts

- [ ] Stock verified, basic vs extended parts identified

- [ ] BOM and CPL exported in correct format

- [ ] Gerbers exported and verified

- [ ] Design rules meet manufacturer minimums (see `jlcpcb` or `pcbway` skill)

- [ ] Prototype fully tested

## Generated Files & Cleanup

The BOM and distributor skills create files in the project tree. Know what they are so you can clean up or `.gitignore` them.

### Files created in the project directory

|----------|-----------|---------|--------------|

| `bom/orders/*.csv` | `bom_manager.py order` | Per-distributor order upload files | No — regenerated before each order |

The `kicad` skill also creates analyzer JSON and design review markdown reports with user-chosen filenames — see its "Generated Files" section for tracking and cleanup guidance.

### Temporary files (outside project)

| File | Location | Purpose |

|------|----------|---------|

| `digikey_token_cache.json` | System temp dir | OAuth token cache (9-min TTL, mode 0600) |

| `index.tmp` | `datasheets/` | Atomic write staging — renamed to `index.json`, never persists |

### Cleanup commands

```bash

# Remove downloaded datasheets (re-downloadable)

rm -r datasheets/

# Remove order files (regenerate before ordering)

rm -r bom/orders/

# Remove schematic backups

rm -f *.bak

# Remove KiCad analyzer/report files (filenames vary — check project AGENTS.md or equivalent agent-rules file)

```

### Suggested .gitignore additions

```gitignore

# BOM skill working files

datasheets/

bom/orders/

*.bak

```

Keep `bom/bom.csv` tracked — it contains user-curated data (Chosen_Distributor, Validated, Notes) that can't be regenerated from the schematic alone.

## Tips

- **MPN is the universal key** — populate it first, enables cross-referencing everything

- **Schematic is source of truth** — all BOM data in symbol properties, exported as needed

- **DigiKey first, Mouser second** for prototyping; LCSC for production

- **CSV round-trip** — Edit Symbol Fields > Export/Import CSV for bulk updates

- **Field Name Templates** (KiCad 9+) — pre-define MPN, Manufacturer, LCSC, DigiKey, Mouser

- **DigiKey token reuse** — cached to temp file with 9-minute TTL; no need to re-auth per call

- **Second source** — use `AltMPN` field for critical parts

- **Price at target qty** — prototype pricing != production pricing

## Platform Guidance

- **Claude Code**: Present BOM tables inline with pricing. Use AskUserQuestion for sourcing preferences.

- **Codex/OpenCode**: Present BOM as formatted table, ask user to confirm or modify.

- - **CLI**: `circuit-weaver cost-bom design.yaml --qty 1,10,100` for pricing, `circuit-weaver export-jlcpcb` for assembly export.

+ - **CLI**: Use `circuit-weaver cost-bom design.yaml --qty 1,10,100` for pricing. `circuit-weaver export-jlcpcb design.yaml -o delivery` is BOM-only unless a real reconciled board is supplied with `--pcb board.kicad_pcb`; never treat heuristic placement as CPL data.