English · 中文
Describe the board you want. Get back a KiCad project and a fab-ready Gerber package — with every part checked against live distributor stock, and every stage cleared by scripts, SPICE and DRC rather than by the model's own say-so.
Under the hood: a multi-project PCB workspace built on KiCad 10, where ten skills drive a Phase 0–5 pipeline covering the full chain from topology discussion to Gerber shipout.
You: I need an isolated 400 V DC-bus voltage sensor — 0–3.3 V out to an MCU ADC.
/circuit-design topology fixed: isolated amplifier + staged HV divider, anchor parts named
/component-selecting-* 3 live candidates per part — all in stock, all with a ready KiCad library
/component-preparing datasheets fetched, symbols + footprints + 3D vendored, BOM locked
/draw-schematic .kicad_sch generated from Python source, ERC clean
/check-schematic divider ratio re-simulated in SPICE, every pin cross-checked vs datasheet
/draw-pcb HV/LV zones split, isolation barrier held, GND poured, DRC clean
/check-pcb 44 EMC rules + thermal + parasitics + schematic↔PCB netlist diff
/release Gerber + CPL + production BOM + ORDER_GUIDE.md, zipped for the fab
You are never locked into that sequence — every step is a toolbox you can run, redo, hand-edit or skip.
- macOS + KiCad 10. The skills call
kicad-cliand KiCad's bundledpcbnewPython API directly, so the pipeline is macOS-only today. - Part selection ships for two locales — Japan and mainland China. That is Phase 2 alone; every other
phase is locale-neutral and runs anywhere. Elsewhere you either adapt one of the two shipped selection
skills to your distributors (they are thin shells over a shared engine) or pick parts by hand and feed the
list to
component-preparing. The pipeline never silently falls back to another region's skill. Details in First-time setup.
Runtime — Claude Code only.
CLAUDE.md(auto-loaded every session) plus the skills under.claude/skills/are Claude Code-native conventions, so it runs with zero config — and nothing else is wired up here.SKILL.mdis an open format, so porting is possible; see Using another agent.Just cloned this? Open the folder in Claude Code and run
/setup. It opens with one short question, then walks you through locale, toolchain and your profile in your own language. It stops firing onceUSER.mdexists.
PCB-Agent-Teams/
├── README.md ← this file (English)
├── README.zh-CN.md ← Chinese version (keep in sync with README.md)
├── CLAUDE.md ← routing table (auto-loaded by Claude Code every session)
├── LICENSE.md ← PolyForm Noncommercial 1.0.0
├── THIRD_PARTY_NOTICES.md ← MIT notices for vendored/derived third-party code
├── USER.md.example ← user-profile template (copy to USER.md)
├── USER.md ← your profile: hardware on hand / locale / skills / preferences (gitignored)
├── requirements.txt ← Python dependencies
├── assets/ ← images used by the READMEs (tracked; `docs/` is local-only and gitignored)
├── .claude/
│ ├── skills/ ← 10 skills + `setup` (first-run guide)
│ └── references/ ← workspace meta-protocols (protocols.md)
├── lib_external/ ← shared component library (starts empty; component-preparing vendors symbols/footprints/3D here)
├── lib_cache/sources/ ← read-only cache of external libs (pre-filter pool)
├── Projects/<name>/ ← project directory (generated by project-init)
│ ├── CLAUDE.md ← project static compass
│ ├── STATUS.md ← live progress / artifact index
│ ├── .gitignore ← project-local ignore rules
│ ├── datasheets/ ← datasheet PDFs + evidence JSON + BOM gate sentinel + procurement BOM
│ ├── kicad/ ← circuit-synth .py + generated .kicad_sch / .kicad_pcb
│ ├── reference_designs/← vendor reference material
│ ├── layout/ ← placement / layout working material
│ ├── docs/ ← BOM / documentation
│ ├── analysis/ ← analyzer JSON / simulation artifacts (created by the check gates)
│ ├── _artifacts/ ← shortlist JSON + 4-axis sourcing prefs (written by selecting, read by release)
│ └── release/<ts>/ ← Gerber + production BOM + CPL (created by release)
├── logs/ ← run logs
├── .venv/ ← Python 3.12 venv (gitignored)
├── .env.example ← API-key template (copy to .env)
└── .env ← your API keys (gitignored)
Three gates built around "the things people trust least when an AI draws a PCB."
Every part number comes off a live distributor API. The model never gets to invent one.
- Distributor APIs are mandatory — no MPN comes from memory. The JP locale queries DigiKey / Mouser / LCSC in three parallel lanes, so one component gets N candidates compared side by side; the CN locale runs a single key-free LCSC lane
- Hard filters: stock active/nrnd + an existing component library available + spec match; anything with zero stock or no ready library is dropped
- Fast search: a short list comes back in seconds based on hard metrics (footprint / tolerance / temperature grade / voltage grade, etc.)
- The whole BOM is worked in a single pass; it only stops to ask when a spec has no answer on the market
Worried the AI skips ahead and starts drawing? An entry gate stops it.
- Before the candidate list is finalized, datasheets are fetched up front plus the component library (footprint symbol / 3D model / schematic symbol)
- Four-point fidelity check: MPN vs the locked BOM / footprint class (through-hole vs SMD) vs the datasheet / generic-symbol masquerading as a real IC / pin count vs the part's actual pin count — one mismatch flips the gate to fail
- Part numbers are auto-injected into schematic properties, avoiding manual-entry errors during drawing
- The drawing entrance stays locked until the assets are ready — there is no way around it
No number is trusted on a single reading. Every key quantity is verified by two independent layers, and failing any stage rolls the pipeline back — it never routes around.
Schematic stage (check-schematic):
- ERC triage + analyzer rule IDs, and datasheet pin-level cross-check (the
total_errors == 0raw-output gate that prevents a "zero errors" false pass runs one stage earlier, indraw-schematic) - SPICE subcircuit simulation (not just connectivity — actual dynamic behavior)
- Design review report — AI-generated analysis written for a human to sign off on, not an auto-pass
PCB stage (check-pcb):
- DRC design rule check
- EMC pre-compliance analysis — 44 rules across 18 categories (ground-plane integrity / decoupling / I-O interface filtering / switching-regulator EMC / clock routing …)
- Thermal analysis (power dissipation / temperature rise)
- Parasitic simulation (R/L/C back-extracted from the PCB, re-running SPICE)
- Schematic ↔ PCB netlist cross-check: the "which pin connects to which pin" list from the schematic is matched item by item against the actual PCB routing, looking for missing, wrong, or shorted connections
Shipout stage (release):
- Four-axis sourcing-preference gate: channel / brand / price-vs-stock / blacklist must be on record before a release is built — the recommended order path in
ORDER_GUIDE.mdis driven entirely by them, so the builder stops and asks instead of guessing - Procurement BOM vs production BOM kept on separate tracks: the purchasing list and the assembly list are generated independently to avoid wrong orders or missing parts
Each skill is a standalone toolbox, not a mandatory pipeline. At any stage you can: use a skill / do it by hand / skip it. Multi-step skills also support mid-run human review (render / DRC / simulation); roll back if unsatisfied.
| Phase | Skill | Responsibility |
|---|---|---|
| 0 Skeleton | project-init |
Scaffold the project: 5 subdirs (datasheets / kicad / reference_designs / layout / docs) + CLAUDE.md (9-section compass) + STATUS.md + .gitignore |
| 1 Topology | circuit-design |
Lock the circuit topology, fix anchor components, write the 9-section project compass |
| 2 Selection gate | component-selecting-* |
Route by locale (locale → vendor), produce shortlist JSON |
| 2.5 Asset prep + BOM gate | component-preparing |
Applicability-review each top pick against its circuit role, then fetch datasheets, populate the library, write evidence, drop the BOM gate sentinel + procurement BOM CSV |
| 3 Schematic gen | draw-schematic |
Source-driven generation of .kicad_sch + ERC clean + visual verification |
| 3.5 Schematic check gate | check-schematic |
ERC triage + analyzer + SPICE subcircuit simulation + datasheet pin-level cross-check + design review |
| 4 PCB gen | draw-pcb |
Zoned layout + GND zone + DRC + visual PDF, optional auto-routing |
| 4.5 PCB check gate | check-pcb |
DRC + EMC + thermal + parasitic SPICE + sch↔pcb cross-ref + gerber audit |
| 5 Shipout | release |
Gerber / CPL / production BOM + documentation PDF + fab decision + packaging |
Locale routing:
component-selectingis a phase name; the concrete skill is chosen byUSER.md §0locale. Two locales are implemented:component-selecting-JP(DigiKey JP + Mouser JP + LCSC, needs a free DigiKey key) andcomponent-selecting-CN(LCSC jlcsearch + jlcparts data shards — zero API keys). The US variant is not yet built. For any other locale, do not silently fall back — tell the user the matching skill is missing.
Any gate that fails: roll back, do not bypass. See the detailed Phase table in CLAUDE.md.
Plus one non-pipeline skill:
setup— the first-run guide. It is gated onUSER.mdbeing absent, so it runs once on a fresh clone and never again.
[empty dir]
│
▼ /project-init
[project skeleton]
│
▼ /circuit-design ← topology + anchor parts
▼ /component-selecting-* ← shortlist
▼ /component-preparing ← datasheet + library + BOM
▼ /draw-schematic ← .kicad_sch + ERC
▼ /check-schematic ← ERC + analyzer + SPICE + datasheet cross-check
▼ /draw-pcb ← .kicad_pcb + DRC
▼ /check-pcb ← DRC + EMC + thermal + parasitics + cross-ref
▼ /release ← Gerber + production BOM
[release/<ts>/ + release_<ts>.zip]
| File | Role |
|---|---|
CLAUDE.md (workspace root) |
Skill routing table; no domain knowledge |
Projects/<name>/CLAUDE.md |
Project static compass: design intent, parameters, BOM anchors |
Projects/<name>/STATUS.md |
Project live dashboard: current phase, artifact index, change log |
.claude/skills/<skill>/SKILL.md |
Skill manual: cross-project constraints, commands, failure modes |
| BOM type | Written by | Purpose |
|---|---|---|
| Procurement BOM | component-preparing |
Order parts from distributors |
| Production BOM / CPL | release |
Fab-house assembly / placement |
Upstream of both sits a third file, the selection-evidence CSV (bom_v01.csv, written by component-selecting) — it records vendor evidence per MPN for later gates, and is never used to order or assemble.
Details in component-preparing/references/bom_lifecycle.md.
Guided path (recommended). Open the folder in Claude Code and run
/setup. It opens with one short question, then handles the rest below in your own language — locale routing, toolchain check,USER.md, and keys only if your locale needs them. It is gated onUSER.mdbeing absent, so it runs on a fresh clone and never again. The manual steps below are the same thing, by hand.
Locale support. As flagged up top, Phase 2 (component selection) is the only locale-bound stage — every other phase is locale-neutral and runs unchanged. Set yours in
USER.md §0:
- China mainland — supported out of the box via
component-selecting-CN: LCSC jlcsearch + jlcparts data shards, no API keys at all (lifecycle is honestly labeledunverifiedsince LCSC carries no NRND data).- Japan — the original
component-selecting-JP(DigiKey JP + Mouser JP + LCSC; needs a free DigiKey key).- Anywhere else — either (a) adapt one of the two shipped skills into a variant for your region (both are thin shells over a shared locale-driven engine — add a locale block to
locale_mapping.yamland mirror the CN skill's structure), or (b) pick parts by hand and feed the list tocomponent-preparing. The pipeline deliberately never falls back to another locale's skill silently.
- macOS with KiCad 10 installed — skills call
kicad-cliand KiCad's bundledpcbnewPython API (no MCP). Default install is/Applications/KiCad/KiCad.app; if KiCad lives elsewhere, just make surekicad-cliis onPATH(scripts probe the standard install paths first, then fall back toPATH). (KICAD_ROOTis unrelated — it overrides the project workspace root, not the KiCad install location.) - Python 3.12 (3.13 / 3.14 are not supported).
- ngspice on
PATH—check-schematic's subcircuit simulation is ngspice-only (brew install ngspice);check-pcb's parasitic / PDN SPICE also accepts LTspice or Xyce, auto-detected. Without a simulator neither fails — the SPICE steps are skipped and marked as such in the report. - API keys — locale-dependent: the Japan pipeline needs at minimum a free DigiKey developer account; the China-mainland pipeline needs no keys at all. See External APIs for the full list of services and what each does.
Two things ship as source only — build or fetch them on demand:
- The Rust grid router (
draw-pcb/.../rust_router/) ships as Rust source; the compiled library is gitignored. Build it withpython3 build_router.pyindraw-pcb/scripts/vendor/KiCadRoutingTools/(needs a Rust toolchain) — only the optional auto-routing phase needs it.lib_cache/sources/(the external KiCad library pool used as a pre-filter) is gitignored and ships empty. Re-clone the upstream libraries into it on demand; until thencomponent-selectingruns without the local pool.
# 1. Create the Python environment and install dependencies
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/playwright install chromium # one-time browser download — DigiKey page probing / datasheet fetch needs it
# 2. Configure API keys
cp .env.example .env
# then edit .env: fill in DIGIKEY_CLIENT_ID / DIGIKEY_CLIENT_SECRET
# (required for the Japan locale only — the China-mainland locale needs no keys, skip this step)
# other keys (Mouser / element14 / Firecrawl) are optional — see "External APIs" below
# 3. Create your user profile
cp USER.md.example USER.md
# then edit USER.md: §0 locale drives which component-selecting skill runs
# (§0 ships as [待填] — no default, you must fill it; Japan and mainland
# China are both implemented, and an empty locale never silently falls back). Fill the
# [待填] fields as they come up; skills read this before recommending any part,
# so they never suggest hardware you cannot test or a package you cannot solder.- Claude Code: open this folder — the root
CLAUDE.mdloads automatically, and the skills under.claude/skills/are available via/<skill-name>. On a fresh clone, start with/setup. - Another agent: not set up here. See Using another agent.
- Plain shell: load the keys first with
set -a && source .env && set +a, then run any skill script as.venv/bin/python .claude/skills/<skill>/scripts/<script>.py.
.env(your real keys) and.venv/are gitignored and are never committed — keep your keys out of git.Projects/ships empty;project-initscaffolds a new board directory there on first run.- Shared library naming conventions:
lib_external/CONVENTIONS.md.
This repo ships Claude Code-only. Nothing here is wired for Codex, Copilot, Cursor or Gemini, and none of it is tested on them. Porting is possible — the file formats are open standards — but it is a change you make in your fork, not something the repo does for you. Two things are Claude Code conventions and both have to be re-pointed:
1. The instruction file. Claude Code auto-loads CLAUDE.md at the repo root; that file is the routing
table this whole workspace runs on. Almost every other agent reads AGENTS.md instead. Fix it either way:
ln -s CLAUDE.md AGENTS.md # symlink, one file, stays in sync
# or, if your agent dislikes symlinks, an AGENTS.md containing just: @CLAUDE.md2. The skills directory. The SKILL.md format is a portable open standard; the directory is not —
each agent scans only its own path and ignores the others.
| Agent | Instruction file | Skills directory | Invocation |
|---|---|---|---|
| Claude Code | CLAUDE.md |
.claude/skills/ |
/<name> |
| Codex | AGENTS.md |
.agents/skills/ |
$<name> |
| GitHub Copilot | .github/copilot-instructions.md |
.github/skills/ |
— |
| Gemini CLI | GEMINI.md |
.gemini/skills/ |
— |
So expose the same folder under the name your agent scans — one symlink, no duplication, and new skills are picked up automatically:
mkdir -p .agents && ln -s ../.claude/skills .agents/skills # Codex; adjust path per the tableNote .gitignore deliberately excludes AGENTS.md and .agents/ to keep foreign scaffolding out of the
upstream repo — drop those two lines in your fork or the symlinks will not be committed.
What to expect. Skill discovery ports cleanly: with the symlink above, Codex lists all eleven skills (the ten pipeline skills plus setup).
Skill execution is a different question and is untested — the skills shell out to kicad-cli, the
project venv and distributor REST APIs, and agents differ in how they sandbox commands and network access.
Also note the pipeline itself is macOS-only (KiCad paths), and symlinks need Developer Mode on Windows.
Treat a port as your own experiment; issues filed against non-Claude-Code runtimes will be closed.
The keys below only apply to the Japan locale (
component-selecting-JPqueries DigiKey JP + Mouser JP + LCSC in three parallel lanes, with DigiKey as the primary buyable gate; Mouser / element14 keys are also read bycheck-pcb's lifecycle audit andcomponent-preparing's distributor query). The China-mainland pipeline (component-selecting-CN) is fully key-free — LCSC jlcsearch + jlcparts public data, nothing to sign up for. The US locale variant is not yet built.
| Service | What it does | Needed? | Env var | Get a key |
|---|---|---|---|---|
| DigiKey | Primary buyable-gate — live stock / price / lifecycle (NRND/EOL) for the JP warehouse; drives the part shortlist | ✅ Required | DIGIKEY_CLIENT_ID, DIGIKEY_CLIENT_SECRET |
developer.digikey.com — free, OAuth |
| Mouser | Second equal source — cross-check stock/price + pull datasheet links | ⭐ Recommended | MOUSER_SEARCH_API_KEY, MOUSER_PART_API_KEY |
mouser.com/api-hub |
| element14 / Farnell | Extra distributor source for stock + specs + lifecycle audit | ○ Optional | ELEMENT14_API_KEY |
partner.element14.com |
| LCSC / JLCPCB | China warehouse that ships to Japan (parts can co-order with the JLCPCB fab run), so it stays a valid third source for the JP pipeline + KiCad library fetch via easyeda2kicad |
— No key (public) | — | — |
| Firecrawl | Datasheet web-scrape fallback when a distributor exposes no direct PDF | ○ Optional | FIRECRAWL_API_KEY |
firecrawl.dev |
All keys go in .env (copied from .env.example). For the JP locale, DigiKey is the primary source; everything else widens coverage or adds a feature. Note the scripts do not abort on a missing key — they warn, and that vendor's queries come back as fetch_error, so a keyless JP run silently loses its main buyable gate. For the CN locale, skip this section entirely — no keys needed. Set the optional DigiKey locale vars (DIGIKEY_LOCALE_SITE=JP etc.) if you want non-default region/currency.
| I want to… | Go to |
|---|---|
| Set up a fresh clone | run /setup in Claude Code, or .claude/skills/setup/SKILL.md |
| Understand the overall routing | CLAUDE.md |
| Learn a specific skill | .claude/skills/<skill>/SKILL.md |
| See cross-project electrical invariants | .claude/skills/circuit-design/references/electrical_invariants.md |
| See shared library naming conventions | lib_external/CONVENTIONS.md |
| See workspace meta-protocols (plan-first / sub-agent split / monitoring) | .claude/references/protocols.md |
This workspace stands on excellent open-source work. Sincere thanks to these projects and their maintainers:
- KiCad — the EDA foundation of the entire pipeline. Every schematic, board, ERC/DRC check, render, and Gerber goes through
kicad-cliand thepcbnewPython API, on top of the official KiCad symbol / footprint / 3D libraries. - ngspice — powers every SPICE check: subcircuit simulation in
check-schematicand parasitic re-simulation incheck-pcb. - kicad-happy by aklofas — AI-agent skills for KiCad; the
check-pcbanalysis suite (EMC / thermal / lifecycle audit / project config / issue export) builds on it. - circuit-synth — Python-source-driven
.kicad_schgeneration, the engine ofdraw-schematic. - kicad-sch-api — programmatic schematic post-processing (label fixing, PWR_FLAG insertion, BOM verification).
- easyeda2kicad — converts LCSC / EasyEDA parts into KiCad symbols / footprints / 3D models for
component-preparing. - KiCadRoutingTools by drandyhaas — the optional auto-routing phase, including its Rust grid router (MIT, vendored under
.claude/skills/draw-pcb/scripts/vendor/). - jlcsearch by tscircuit — the public LCSC search API: third sourcing channel for the JP pipeline, primary (and key-free) lane for the CN pipeline.
- jlcparts by yaqwsx — published parametric data shards of the JLC catalogue; powers the CN pipeline's offline parametric discovery for categories jlcsearch lacks (inductors, ferrite beads).
- Playwright — headless-browser probing of distributor pages and datasheet fetching.
- And the Python ecosystem this runs on: NumPy, SciPy, Shapely, Matplotlib, Pillow, ReportLab, odfpy, python-docx, Jinja2, Requests, PyYAML, psutil, pytest.
If this project helps you, consider starring / supporting those upstream projects too.
Source-available under the PolyForm Noncommercial License 1.0.0. Free to use, modify, and share for noncommercial purposes (personal, research, education). Commercial use requires a separate license — contact the author. © 2026 zhang zheng.
Third-party components (kicad-happy-derived analyzers, vendored KiCadRoutingTools) remain under their original MIT licenses — see THIRD_PARTY_NOTICES.md.