科研 Skill
KiCad PCB脚本化设计
pcb-engineer
Designs a product’s PCB in KiCad from one JSON spec: outline, footprints, placement, schematic, ERC/DRC, and Gerber/BOM export, scripted and reproducible. Use to lay out a board.
SKILL.md
PCB engineer
This skill turns hw/architecture.md and hw/bom.csv into KiCad boards a named fab can build. Everything comes from one spec file, hw/pcb/board.json. The schematic, the board and every export are regenerated from it, so a change never drifts between files.
Talk to the user in their language. Keep every file in English.
Prerequisites
Run commands from inside this skill's own directory (the folder containing this SKILL.md), since script and reference paths below (such as scripts/foo.py) are written relative to it, not to the project root.
Inputs
hw/architecture.md: blocks, rails, buses and pin assignments.hw/bom.csv: full MPNs, packages,size_max_mm. Only parts withlifecycleactive or new.hw/parts/<MPN>.md: pinouts, land patterns, reference circuits, fromelectronics-researcher.hw/power/rails.json: rail names and voltages, so net names match the power chapter.hw/mech/: the board outline (SVG or polygon), keep-in height per side, magnet/battery/port positions, fromenclosure-engineer.hw/state.json: the fab chosen incost-and-sourcing, if any. Otherwise, design to the common rules inreferences/fab-capabilities.md.
Outputs
| Path | Content |
|---|---|
hw/pcb/board.json | the spec (the only file edited by hand) |
hw/pcb/lib/ | project symbol and footprint library, 3D bodies of generated footprints |
hw/pcb/<board>/ | .kicad_sch, .kicad_pcb, .kicad_pro, erc.json, drc.json, placement-report.json |
hw/pcb/export/ | <board>.glb (and .step), <board>_{top,bottom,iso}.png, pads.json, tex/ |
hw/pcb/fab/<board>/ | <board>_gerbers.zip, <board>_bom.csv, <board>_cpl.csv (JLCPCB columns), stackup.md, order.md, panel-plan.json (+ panel.json for KiKit) |
hw/pcb/build-summary.json | counts from every check, and the result line |
hw/pcb/release-check.json | the ready-to-order gate result, with every missing item |
hw/pcb/pcb.md | the PCB chapter: stack-up, fab, rules, open items, images |
Tools
All scripts are in scripts/. Run python3 scripts/kicad_env.py first. It reports KiCad, its Python, the libraries, Java and Freerouting. If something is missing, run toolchain-setup.
| Script | Runs with | Job |
|---|---|---|
build.py spec [--route] [--step] [--strict] [--release] | system Python | the whole pipeline below, stops at the first failing gate |
pins.py Lib:Symbol [--footprint Lib:Fp], --search, --search-footprint | system Python | pin names and pad numbers, to fill a part's pins |
spec.py spec | system Python | validate the spec |
libgen.py, schgen.py | system Python | library + pin/pad/net cross-check; schematic |
pcbgen.py | KiCad Python | board, outline, legalized placement (real courtyard polygons), planes, keepouts, stack-up |
route.py export | import | run | KiCad Python (+ Java for run) | Freerouting in three steps: DSN out here, route on any machine, SES back here (heavy step off the laptop) |
finish.py dupes | planes | islands | grid | prune | net | KiCad Python | close what the autorouter leaves: duplicate links, plane stitching, island vias, a multi-layer A* router for the last nets |
export.py --what erc,drc,3d,step,fab,render,pads,textures | system Python | checks and outputs |
fabnotes.py | system Python | stackup.md (stack-up and impedance), order.md, panel-plan.json and KiKit panel.json |
release_check.py | system Python | the ready-to-order gate (below); exit 0 only when nothing is missing |
outline.py, stepbox.py | either | outline polygons (circle, rounded rect, polygon, SVG path, smooth union); STEP boxes |
scripts/ runs on KiCad 10.0 with KiCad's bundled Python 3.9; the code is 3.9-compatible on purpose. The example in templates/example/board.json builds end to end: a 20 mm round, 4-layer BLE sensor with an SoC, charger, LDO, accelerometer, chip antenna, dock contacts and magnet keepouts. Copy it as a starting point.
Field reference for the spec: references/spec-format.md.
Procedure
- Read the inputs and write down the board decisions in
hw/decisions.md: how many boards (rigid, flex, rigid + flex with a board-to-board connector), stack-up, thickness, finish, mask color, single- or double-sided assembly, and the target fab. Check each againstreferences/fab-capabilities.md. Ask the user only about what changes the product, such as a flex for touch/LED/mics near the shell, or a second board for the dock contacts. - Get the outline from the enclosure. Use
enclosure-engineer's outline (SVG or polygon) inset by the wall clearance. Never draw a board bigger than the cavity "to fit later". - Write
board.json.- Parts come from
hw/bom.csv. Prefer KiCad standard symbols and footprints (Lib:Name); check them withpins.py. - If a part has no library footprint, generate one from the datasheet's recommended land pattern (not the package drawing), with a
bodyof the datasheet's maximum dimensions. Cite the datasheet figure in the footprintdescription. - Name the pins as the datasheet does. Write every pin: a net, or
nullfor a deliberate no-connect. Usenc_restonly for unused GPIOs. - Copy the reference circuit of every IC (decoupling, crystal load caps, DC/DC inductor, RF matching) from the manufacturer's reference design, and cite it in
description. - Give rough positions in the device frame: origin at the board center, +x right, +y up, seen from the F side. Mark as
fixedthe parts whose position the product decides: connectors, antenna, contacts, sensors under windows, LEDs under light pipes, mics over ports, battery tabs. - Add
keepoutsfor everything the enclosure puts against the board (magnets, battery, screw bosses, ribs, mic ports), on the right side. Addexclusiveareas for the RF corner and for touch electrodes.
- Parts come from
- Build:
python3 scripts/build.py hw/pcb/board.json. Fix every gate at its cause:- library errors (pin without pad, pin without net): fix the spec, never the generated files;
- ERC errors: fix nets or pin types; read each warning;
- placement failure: the report names the part and what it hit. Move it, change side, or grow the board with the enclosure owner. Do not shrink a courtyard or a keepout to make it pass.
- Review the images (
export/<board>_top.png,_bottom.png,_iso.png) before saying anything is done. Check pin 1 marks, part orientation, the RF corner, test point access, and parts under windows. - Feed the 3D model back. Send
export/<board>.glbandexport/pads.jsontoenclosure-engineer, whose assembly validator checks the board against the enclosure. Each collision becomes a keepout or a fixed position in the spec; then rebuild. This loop catches parts placed over magnets, mic ports covered by a stiffener, and connectors taller than the gap. - Route. Hand-route and lock the critical nets first (
references/workflow.md). Autorouting (build.py --route) is a first pass for the rest. It is CPU-heavy: run it on a workstation or cloud VM, never on the laptop that runs the session. - Make it orderable. In the spec:
- fill
lcsc(or markconsign) andmpnfor every part; - set
fab,panelandfiducials; - add
impedanceto the RF and high-speed net classes. Then runbuild.py --step --releaseon the machine with the routed board.
- fill
- Finish. Fix every item
release_check.pylists until it exits 0. Then writehw/pcb/pcb.md(stack-up, fab, rules, images, revision) and updatehw/state.json.
Gate
The PCB stage delivers a board that can be ordered with no further changes. It is done only when python3 scripts/release_check.py hw/pcb/board.json exits 0, which requires all of the following:
- Routed. Freerouting runs as a documented step on a workstation or cloud machine, never on the laptop running the session (
references/workflow.md, "Routing on another machine"). The critical nets are routed by hand first. Zones are then refilled (route.pyand DRC--refill-zonesboth do it). DRC reports 0 unconnected items. - Checks at zero. DRC has 0 errors, 0 schematic-parity issues, and no warnings except silkscreen cosmetics. ERC has 0 errors and no warnings except PWR_FLAG pin-type notes. Both reports are newer than the board file.
- Fab outputs in the chosen fab's format, in
hw/pcb/fab/<board>/:- a Gerber + drill zip with every copper layer, both masks, paste, the outline, and PTH and NPTH drill files;
- BOM and CPL in JLCPCB format, listing the same parts. Every line has an LCSC part number where the assembler stocks it, or is marked
consign.
- Stack-up and impedance notes (
stackup.md), with an impedance line for every controlled-impedance net class, and order notes (order.md). - Assembly minimum size handled. Either the board meets the assembler's minimum (JLCPCB: 70 × 70 mm), or a panel is planned (
panelin the spec: by the fab's service, or KiKit files generated). - Fiducials. At least 2 per assembled side on the board, or 3 on the panel rails.
- Placement clean. No failed part and no fixed-part collision. The assembly validator in
enclosure-engineerpasses with this board's GLB. - Every generated footprint cites its land-pattern source, and every IC's reference circuit is cited in its part
description.
A placed but unrouted board is a placement study, not a PCB. Report it that way, with the release_check failure list.
Taste and pitfalls
- The spec is the source. Regenerate, never hand-edit generated files. A manual fix is lost on the next build.
- Do not bend a footprint to fit a part that does not exist. If the chosen part's package is not orderable, or is "early sampling", change the part (
specs-engineer). Do not draw a smaller footprint. - Size by maximum dimensions. Courtyards and 3D bodies use the datasheet maximum, not the nominal. A 0.25 mm nominal LED that is 0.35 mm max hits the shell.
- Keepouts come from the 3D assembly, and they are permanent. When the validator finds a part over a magnet, add a keepout to the spec so the legalizer can never put it back.
- Netclass clearance must fit the package. A 0.2 mm RF clearance on 0201 parts (0.18 mm pad gap) makes DRC fail on the part itself. Set rules that real packages can meet.
- Real 3D models for anything mechanical. Connectors, springs, switches, batteries and shields use the vendor's STEP (
"models"in the spec). A generic box is only for passives and ICs. - Bottom-port mics need a hole in the board, sealed to the enclosure port. Top-port mics need a port in the shell above them. Read the mic datasheet for which kind it is before placing it.
- Every exposed contact gets ESD protection next to the contact, and test points for SWD/reset/rails go on the side reachable from a fixture.
- Silkscreen on tiny boards is noise. Use
"footprint_silk": "fab"under ~30 mm and put the board revision on a fab layer or in copper. - Black or white solder mask needs a wider mask web (0.13 mm vs 0.10 mm at JLCPCB). Check fine-pitch QFNs before you choose the color.
- Keep local runs light. Generate, ERC, DRC and exports run in under a minute on the example. Autorouting and STEP export are the heavy steps.
- Remove duplicate copper links before routing the last nets (
finish.py dupes). A track that repeats a same-net pour, or a track between two pads that the part connects internally (a 4-pin tactile switch), adds copper that blocks the escape of the remaining nets. - Run DRC inside the board's project folder. On a copy outside it,
kicad-cliloses the project rules, applies 0.2 mm defaults and reports hundreds of false violations. - DRC does not keep a signal out of a QFN pad ring or a via out of a cell contact area. Use rule areas in the spec, or
finish.py net --no-under REF --no-via-circle X,Y,R. - An SMD pad does not anchor a pour island. An island that touches only SMD pads of its net is still unconnected to the plane.
finish.py islandscounts only vias and PTH pads, and never puts a via under a part body. - Pick the Freerouting version for the board. 2.5.0 needs Java 25 and stops after about 19 passes when the score stops improving. 1.9.0 (Java 17+, under
xvfb-runon headless Linux) routed a dense 28 mm 4-layer board further.kicad_env.pychecks the Java a jar needs.
References
references/spec-format.md: every field ofboard.json, with the shortcuts. Read it when writing or changing a spec.references/workflow.md: the loop from spec to fab, what to hand-route, when to autoroute, and how to read the reports.references/fab-capabilities.md: the published limits of large prototype fabs to check against (verified 2026-11-08, re-check before ordering).references/layout-rules.md: antenna, RF, crystal, DC/DC, decoupling, mics, touch, ESD, test points, stack-ups, flex and stiffeners.
示例提示词
帮我从JSON规格用KiCad自动生成这块板的布局和Gerber。
所属插件
安装该插件会一并获得同领域的 63 个 Skill / MCP。
同插件的其他科研 Skill
- ANDES电力系统动态仿真Runs ANDES power-system dynamic studies via PowerMCP: power flow, eigenvalue analysis, and time-domain simulation. Use for damping, stability, or oscillation-mode questions.
- 电池选型与电源预算Builds an evidence-tagged power budget and sizes a manufacturable battery with pouch outline, seals, and derating. Use when sizing runtime, mAh, charging, or supply rails.
- FPGA比特流生成与烧录Generates a Xilinx FPGA bitstream and programs it over JTAG, or burns an MCS image into flash for power-on boot. Use when flashing a board or diagnosing boot failures.
- 硬件项目发布包组装Assembles a hardware release package (fab files, BOM/CPL, carts, assembly guide, hashed manifest) and runs a ready-to-build gate. Use before ordering prototypes.
- 时钟域交叉风险审查Audits clock-domain-crossing risk on an FPGA design and applies the smallest safe synchronizer or constraint fix. Use to resolve CDC violations before sign-off.
- 硬件产品认证合规规划Plans certifications a hardware product needs per target market (FCC, CE/RED, UKCA, battery/radio rules), with cost and lead-time estimates. Use before PCB or enclosure tooling.
- Vivado XDC时序约束编写Authors a Vivado XDC timing constraint set from scratch: clocks, I/O delays, and timing exceptions. Use first, before timing closure, on a design with no or incomplete constraints.
- N-1/N-2应急违规处置Playbook for N-1/N-2 contingency violations: ranks contingencies and proposes preventive and corrective actions. Use after a study shows voltage or thermal problems.
- 潮流计算不收敛诊断Playbook for power-flow convergence failures in PSS/E, PSLF, PowerWorld, pandapower, PyPSA, surge, or OpenDSS. Use when a case diverges or fails to solve.
- 硬件成本核算与采购Prices a hardware product at multiple volumes with one-time vs per-unit cost, landed cost per country, and sourcing leads. Use to estimate unit cost before a pitch.
- RTL仿真覆盖率收敛Measures RTL simulation code coverage and iteratively closes it toward a target by adding testbench stimulus. Use for a sign-off-grade coverage report.
- 配电网DER接纳能力治理Playbook for distribution DER hosting-capacity limits: voltage rise, reverse flow, and thermal limits from PV and storage. Use to estimate how much DER a feeder can host.
- 电子电路设计与审查Designs, audits, or corrects an electronic circuit from a brief, schematic, or netlist, checking power domains, reset sequencing, and ratings. Use for circuit review.
- 硬件可制造性红队审查Red-team audit that fix-loops a hardware project to ready-to-build, re-deriving parts, rails, battery physics, and cost. Use for a reality check before committing to a design.
- 电力系统动态稳定处置Playbook for dynamic stability problems: poor damping, angle instability, or sustained oscillations from eigenvalue or time-domain studies. Use after an unstable study result.
- Egret电力市场调度优化Runs Egret market/operations optimization (DC-OPF, AC-OPF, unit commitment) via PowerMCP. Use for cheapest dispatch, unit commitment, or congestion checks.
- 电子元器件选型核查Researches electronic components against primary sources: part numbers, datasheet limits, lifecycle, stock, and price breaks, one dossier per part. Use to verify or source a BOM.
- EMC电磁兼容预测试Plans grounding, shielding, and filtering for EMC/EMI, and runs an emissions pre-scan with a root-cause fix sequence. Use before a lab test or after a failed EMI scan.
- 产品外壳参数化建模Designs a hardware enclosure as parametric CAD with STEP/STL/GLB output, a DFM check, and Blender assembly validation. Use when designing a case or checking fit.
- 电网频率响应问题处置Playbook for frequency problems: low inertia, high RoCoF, weak primary response, or UFLS risk after loss of the largest unit. Use when a study flags frequency issues.
- FPGA RTL到比特流全流程Drives a Xilinx FPGA design end to end through RTL, simulation, synthesis, implementation, and bitstream, gated at every stage. Use to run the complete build flow in one pass.
- 硬件产品全流程总协调Leads a physical electronic product from idea to a doable design, coordinating specs, parts, battery, PCB, enclosure, render, and cost sub-skills. Use starting a hardware product.
- 硬件原理图与BOM审查Reviews hardware projects: checks schematics against datasheets, pin connections, and firmware-to-hardware alignment across KiCad/Altium files. Use for a design alignment check.
- FPGA ILA在线逻辑调试Inserts an Integrated Logic Analyzer, programs the board, arms a trigger, and reads captured waveforms on real FPGA hardware. Use when sim passes but the board fails.
常见问题
KiCad PCB脚本化设计能做什么?
Designs a product’s PCB in KiCad from one JSON spec: outline, footprints, placement, schematic, ERC/DRC, and Gerber/BOM export, scripted and reproducible. Use to lay out a board。
如何安装KiCad PCB脚本化设计?
在科搭 Codar 左侧点击「插件」,在「组件」页签搜索「KiCad PCB脚本化设计」并安装;在 Claude Code 或 Codex 中可以发送本页的安装提示词,或下载 Skill 包后解压到 ~/.claude/skills 或 ~/.codex/skills。
KiCad PCB脚本化设计需要哪些权限?
该科研 Skill没有声明额外权限;执行具体操作时仍由 Agent 按自身规则请求确认。
KiCad PCB脚本化设计经过官方审核吗?
是。SpeedSkills 收录的每个版本都会记录内容摘要与权限声明,当前版本已通过安全审核。