A multi-project PCB design workspace orchestrated around KiCad 10. Ten skills drive a Phase 0–5 pipeline that covers the full chain, from topology discussion to Gerber shipout.
Runtime — Claude Code only. This workspace targets Claude Code and nothing else. It is driven by
CLAUDE.md(a routing table Claude Code auto-loads every session) plus a team of ten skills under.claude/skills/, which Claude Code discovers on its own. Both are Claude Code-native conventions, so it runs with zero config — and no other agent is set up here. The skills are plainSKILL.mdfiles, so porting is possible; see Using another agent for exactly what has to change.Just cloned this? Open the folder in Claude Code and run
/setup. It asks 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
├── 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
├── .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
│ ├── kicad/ ← .kicad_sch / .kicad_pcb
│ ├── analysis/ ← analyzer JSON / simulation artifacts
│ ├── docs/ ← BOM / documentation
│ └── release/<ts>/ ← Gerber + production BOM + CPL
├── 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."
Worried the AI invents part numbers? Not possible here.
- Distributor APIs are mandatory (DigiKey / Mouser / LCSC, etc.); data is pulled from multiple sources in parallel and in batch, so one component gets N candidates compared side by side
- 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 runs in one pass; it only stops to ask the user when a spec has no solution on the market
Worried the AI skips steps and starts drawing? An entry gate blocks it.
- Before the candidate list is finalized, datasheets are fetched up front plus the component library (footprint symbol / 3D model / schematic symbol)
- Four-point consistency check: footprint name / 3D model / pin count / value annotation — each verified, one mismatch triggers a rollback
- Part numbers are auto-injected into schematic properties, avoiding manual-entry errors during drawing
- The drawing entrance is locked until assets are ready — no skipping ahead
Worried the AI passes on the surface but hides problems? Every key quantity is checked at least twice; failing any stage rolls back instead of bypassing.
Schematic stage (check-schematic):
- ERC electrical rule check (verified against the parser's raw output, to prevent a "zero errors" false-pass bug)
- SPICE subcircuit simulation (not just connectivity — actual dynamic behavior)
- Design review (human + AI dual review)
PCB stage (check-pcb):
- DRC design rule check
- EMC electromagnetic compatibility analysis (differential chains / power domains / signal integrity)
- 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 process parameter check: board thickness / process / surface finish / color must all be set before Gerbers are generated
- 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 |
Generate the project directory skeleton (CLAUDE.md / 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 |
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 |
analyzer + SPICE subcircuit simulation + design review |
| 4 PCB gen | draw-pcb |
Zoned layout + GND zone + DRC + visual PDF, optional auto-routing |
| 4.5 PCB check gate | check-pcb |
EMC + thermal + parasitic SPICE + cross-ref analysis |
| 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 ← analyzer + SPICE
▼ /draw-pcb ← .kicad_pcb + DRC
▼ /check-pcb ← EMC + thermal + parasitics
▼ /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 |
Details in component-preparing/references/bom_lifecycle.md.
Guided path (recommended). Open the folder in Claude Code and run
/setup. It asks 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.
⚠ Not in Japan? Phase 2 (component selection) is the only locale-bound stage; every other phase is locale-neutral and runs unchanged. Set your locale 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 auto-probe PATH / Homebrew / Snap / Flatpak). (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— required for the SPICE checks incheck-schematic/check-pcb(brew install ngspice). - 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)
# 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
# (template defaults to Japan; mainland China is also implemented). 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.
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 pipeline (
component-selecting-JP, which queries DigiKey JP + Mouser JP + LCSC as three equal sources). 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 only hard requirement; everything else widens coverage or adds a feature. 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 editing (MPN property injection, post-processing).
- 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.