
hardware-design
Idea to doable hardware: specs, parts, battery, PCB, enclosure, renders, blueprint, costs, certification, roadmap and presentation.
- GitHub stars
- 5
Install
/plugin install hardware-design@hardware-design-toolkitRun it inside Claude Code after adding the marketplace with /plugin marketplace add ctresb/hardware-design-toolkit.
Contents
Discovered from sourceSkills 17
Battery and power
This skill makes the energy side of a product honest. Its job is to stop the most common hardware fantasy: a battery shaped like the leftover space, credited with a phone's energy density, feeding a current nobody has measured.
Talk to the user in their language. Keep every file in English.
Inputs
hw/requirements.md: runtime target, size limits, use pattern (how many hours a day in each mode), environment temperature.hw/architecture.md: power tree, rails, radios, peak loads.hw/bom.csv:supply_rail_v(rail name),key_specs(vdd=lo-hitokens),typ_current_ma,peak_current_ma.hw/mech/: the battery pocket outline (SVG or polygon) and its height, whenenclosure-engineerhas one. Otherwise, the size limits from the requirements.hw/parts/<MPN>.md: current figures with sources, fromelectronics-researcher.
Outputs
| File | Content |
|---|---|
hw/power/budget.input.json | the budget model: modes, duties, parts, rails, comparables, limits. Format: templates/power_budget.example.json |
hw/power/budget.json | results from scripts/power_budget.py |
hw/power/rails.json | shared rail table, owned by this skill (schema below) |
hw/power/battery.json, hw/power/battery.svg | results from scripts/battery_fit.py: outline, thickness, capacity range, top view |
hw/power/power.md | the human-readable power chapter (templates/power.md) |
hw/power/measurements/ | captures and notes, once measured |
Shared rail table: hw/power/rails.json
Each rail gives its voltage either as a range or as nominal ± tolerance in volts, plus its current limit. {"nom": 1.8, "tol": 0.05} spans 1.75–1.85 V.
{
"VSYS": {"min": 3.0, "max": 4.4, "max_ma": 125},
"1V8": {"nom": 1.8, "tol": 0.05, "max_ma": 150}
}
hw/bom.csv→supply_rail_vholds the rail name (1V8). A part on several rails lists them asVSYS|1V8, matched in order tovdd,vdd2, and so on.key_specsholds tokens such asvdd=1.7-3.6; vio=1.8; i2c=0x2C.- The budget input carries the same fields per rail, plus the regulator model (
typedirect|ldo|buck|boost,efficiency,iq_ma,off_modes).power_budget.py --rails-outwrites the table. scripts/check_rails.py hw/bom.csv hw/power/rails.jsonfails any part whose supply range does not contain its rail's full range. It is the toolkit's single rail implementation:specs-engineer'sbom_check.pyandelectronics-researcher'sbom_merge.pyimport it.
Workflow
- Collect the use pattern. Define the modes (for example active, record, stream, sync, idle, ship) and the fraction of a day spent in each. If the user does not know, propose a realistic pattern and log it as an
[assumption]inhw/decisions.md. - Write the budget input. Write
hw/power/budget.input.json, with one entry per part that draws current and one current per mode.- Every current carries an evidence tag (CONVENTIONS §6).
- Use the datasheet figure for the mode the firmware will really use: TX power, sample rate, flash program duty.
- Add comparables. Find 2–3 shipped products in the same category that publish battery capacity and runtime.
electronics-researchercan find them. Put them incomparables. Their average current (capacity × usable fraction / runtime) is the empirical case, and it often is 3–5× the bottom-up baseline. - Run the budget:
python3 ${CLAUDE_SKILL_DIR}/scripts/power_budget.py hw/power/budget.input.json -o hw/power/budget.json --rails-out hw/power/rails.json- It reports four scenarios (optimistic, baseline, pessimistic, empirical), runtime when new and at end of life, the rated capacity needed, the largest contributors, and the peak checks.
- Exit code 2 means a peak limit was exceeded.
- Check the rails:
python3 ${CLAUDE_SKILL_DIR}/scripts/check_rails.py hw/bom.csv hw/power/rails.json. Fix every failure in the architecture (another rail, a different part, a level shifter) and tellspecs-engineerthroughhw/state.json→open_questions. - Size the battery. Read
references/battery-reality.mdfirst.- Look for catalog cells that fit the pocket (§6 of the reference).
- Then run the fit:
python3 ${CLAUDE_SKILL_DIR}/scripts/battery_fit.py --svg hw/mech/battery_pocket.svg --height <mm> --claimed-mah <current claim> --svg-out hw/power/battery.svg --json hw/power/battery.json- Inputs:
--rect W Lor--polygon file.jsoninstead of--svg.--steppedallows one step (custom cells only).--chem pouch-hvselects a high-voltage cell. - Exit code 1 means the claimed capacity is above the realistic range.
- Inputs:
- Show the user
battery.svg. Plan the product on the low end of the capacity range until a vendor quotes it.
- Close the loop. Compare the realistic capacity with the rated capacity each scenario needs. If the pessimistic or empirical case does not fit, present the options as a short table and recommend one:
- less runtime;
- a lower duty cycle or a lower-power mode;
- a different radio or codec;
- a larger product;
- a high-voltage or custom cell.
- Choose the charging method with
references/charging-options.md. Prefer methods that add no opening. Check the charge current against the cell's C-rate, and the charge time against the use pattern. - Plan the measurement with
references/measurement.md: instrument, firmware build, modes to capture, pass criteria. This plan is part of the gate. - Write
hw/power/power.mdfromtemplates/power.md. Add each decision tohw/decisions.mdand each question for the user tohw/state.json.
Gate
The next stage, especially any custom cell, mold or board-size freeze, starts only when all of these hold:
- Every current in the budget has an evidence tag. The four scenarios are reported.
- Every peak is below every limit in the chain: cell, protection, PMIC, regulators, brown-out drop.
-
check_rails.pypasses. - The battery is a shape a vendor makes (catalog, rectangle, or one step). Its capacity is the fit's realistic range, not a claim. The fit is shown as an SVG.
- The planned capacity covers the pessimistic or empirical case at end of life, or the user has accepted a lower runtime in
hw/decisions.md. - A measurement plan exists. Before a custom cell is ordered, a measured average current exists and passes (
references/measurement.md).
Taste and pitfalls
- Never fill leftover space with a blob-shaped cell. Draw a straight-edged rectangle. Consider a step only when the gain is large and the volume justifies a custom cell. If the user sketches an outline, honor its intent with straight segments and say what each curve costs.
- Never size a custom cell before measuring. Freezing the cell first and measuring later is a process inversion. It happened in a real project and forced a lower average current than had ever been shown.
- Do not trust a bottom-up budget alone. Show the empirical case next to it, even when it is uncomfortable.
- Small cells lose a large share to seals. At about 20 mm, seals and tabs take 25–40 % of the outline. Say so with the number.
- Thickness is a max dimension. Subtract the tolerance and the swelling, and never compress the cell.
- Check radio peaks against the PMIC's system-load limit, not only the battery's. One high-power radio can exclude a whole PMIC family.
- Do not promise compatibility with another company's charger or dock. They are proprietary.
- The battery fixes shipping and compliance work: UN38.3 for each cell design, IEC 62133-2, and EU rules on removable batteries (Battery Regulation Article 11, applying from February 2027). Add these as items for
compliance-planner. Do not decide them here. - Use exact, aligned numbers in tables and drawings. Write a range as
55–65 mAh [estimate], never as a bare70 mAh.
Bundled files
scripts/power_budget.py: budget, scenarios, runtime, required capacity, peak chain, rail table.scripts/battery_fit.py: largest straight-edged cell in a pocket (rectangle, JSON polygon or SVG path); conservative capacity range; SVG top view.scripts/check_rails.py: each IC's supply range againstrails.json.templates/power_budget.example.json: example budget input (a fictional BLE voice clip).templates/pocket.example.svg: example pocket outline in mm.templates/power.md: outline of the power chapter.references/battery-reality.md: cell types, densities, pouch anatomy, shapes, sizing, custom-cell economics, vendor RFQ.references/charging-options.md: charging methods, charge rules, peak current chain.references/measurement.md: instruments, procedure, gate, cell testing.
Build package
The toolkit delivers a design that someone can order and build without further design work. This skill collects the outputs of all stages into one release folder. It also runs the gate that decides whether the release is READY TO BUILD. If the gate fails, the release is not ready. Send each failure back to the skill that owns it, fix it there, and run the gate again. Do not patch files inside the release by hand.
Talk to the user in their language. Release files are in English unless the user chose another language.
Inputs
| Path | From | Used for |
|---|---|---|
hw/release/release.json | this skill (you write it) | revision, target level, boards, assembler, build size, enclosure parts, battery, order steps (format: templates/release.example.json, fields in references/release-config.md) |
hw/pcb/<board>/ drc.json, erc.json, .kicad_pcb, .net | pcb-engineer | DRC/ERC = 0, routed board, pin map |
hw/pcb/fab/<board>/ Gerber zip, BOM, CPL | pcb-engineer | fab and assembly files |
hw/bom.csv | specs-engineer, electronics-researcher | orderable MPNs, LCSC numbers, stock dates |
hw/mech/cad/ STEP/STL, hw/mech/dfm.md | enclosure-engineer | enclosure parts |
hw/validation/assembly.json | enclosure-engineer | assembly passes, newer than the CAD |
hw/drawings/ | technical-drawing | the 2D drawing PDF and exploded images |
hw/power/ | battery-and-power | battery spec, power-measurement thresholds |
hw/cost/ | cost-and-sourcing | cost and lead time per order step |
hw/doability/ | doability-review | the overall verdict, and the "Verify on the prototype" list |
Outputs: hw/release/<rev>/
README.md what this release is, its level, how to use it
ORDER.md numbered order steps: where, what to upload, options, cost, lead time, receiver
MANIFEST.json every file with sha256, size and source stage
fab/<board>/ Gerber+drill zip, IPC netlist (if exported), fab-notes.md (stack-up, finish, mask, min features, stiffeners, panel)
assembly/<board>/ BOM and CPL in the assembler's format, stock.md (stock per line with date), consigned.csv, options.md
purchasing/ digikey.csv, mouser.csv (BOM-upload format), mechanical.csv, purchasing.md (quantities with attrition)
mech/ <part>.step, <part>.stl, print-settings.md, drawing PDF, mech-bom.csv
battery/ battery.md (catalog cell + holder, or the custom-cell spec for the vendor)
assembly-guide/ assembly-guide.md and its images
test/ test-plan.md (bring-up, test points, power plan with thresholds, functional tests), verify-on-prototype.md
firmware/ pins.json and pins.h for the MCU (from the netlist), when configured
checks/ copies of the reports the gate used (DRC, ERC, validator, doability) and release-check.json
Procedure
-
Write
hw/release/release.json. Copytemplates/release.example.json, and set the revision (A,B…) and the target level (prototypeorproduction). Fill in the boards, the assembler (JLCPCB first), the build size, the enclosure parts, the battery and the order steps. Take each step's cost and lead time fromhw/cost/, and cite it. -
Write the documents that only this skill owns. Use the templates:
assembly-guide.md(templates/assembly-guide.md): numbered steps, exploded images fromtechnical-drawing, adhesive and cure time, torque, and a QC check after each step;test-plan.md(templates/test-plan.md): bring-up order, test points, the power-measurement plan with pass thresholds frombattery-and-power, and the functional tests;battery.md(templates/battery-spec.md);print-settings.md(templates/print-settings.md).
Put them in
hw/release/src/. Every value comes from a stage file, and you cite its ID or path. Leave no<placeholder>, TBD or TODO. -
Assemble.
python3 ${CLAUDE_SKILL_DIR}/scripts/assemble_release.py hw/ --config hw/release/release.json- It copies the stage outputs into
hw/release/<rev>/. - If
pcb-engineerdid not export them, it builds the assembler BOM and CPL from the KiCad position file andhw/bom.csv, applying the rotation offsets in the config. - It writes the purchase carts with attrition, the pin map,
ORDER.md,README.mdandMANIFEST.json.
- It copies the stage outputs into
-
Gate.
python3 ${CLAUDE_SKILL_DIR}/scripts/release_check.py hw/release/<rev>/ --hw hw/It prints each failure with the owner skill and exits non-zero if the release is not READY TO BUILD (checks in
references/ready-to-build.md§3). Send each failure to its owner. Re-run steps 3–4 until the gate passes. After 3 rounds, stop and show the user the remaining blockers with the exact actions. -
Pre-order review. Go through
references/ready-to-build.md§4 with the release open. Pay attention to rotation and polarity in the assembler's preview, basic vs extended part fees, the panel, clear-part finishing and cell shipping. Record the result inhw/release/<rev>/checks/pre-order.md. -
Hand over. Tell the user the level, the total cost and lead time for the build size, and the first step of
ORDER.md. Ordering spends money: never place an order or upload files for the user without their explicit go-ahead.
Gate
release_check.py exits 0 and the doability verdict is READY TO BUILD (prototype) or
READY TO BUILD (production), matching release.json → target. A release that fails the gate is
labelled NOT READY in its README, with the failure list.
Taste and pitfalls
- "Unrouted" is not "almost done". A board with zero tracks or with unconnected items fails the gate, however good the 3D looks.
- Stock goes stale fast. Re-check the assembler stock and distributor stock within 14 days of ordering. The gate fails older dates.
- Rotation offsets are per footprint and per assembler. Check every polarized part (diodes, LEDs, ICs, connectors) in the assembler's 3D preview before you pay. A mirrored LED or a rotated QFN costs a whole batch.
- One source of truth. The release copies files and never edits them. Fix a wrong value in its stage file, then assemble again.
- The validator must be newer than the CAD. A passing report from before the last CAD change proves nothing.
- Prototype measurements are not blockers, but they need thresholds. "Measure the current" is not a test. "Average current in mode X ≤ 1.5 mA over 10 min, measured on a PPK2 at 3.0 V" is a test.
- Clear parts need a finishing plan. An SLA print is not clear until it is wet-sanded and coated or polished. Write the steps, otherwise the prototype looks foggy.
- Lithium cells ship as dangerous goods. Order them to the assembly location, never in the same box as the boards from a fab that does not ship cells.
Bundled files
scripts/assemble_release.py,scripts/release_check.py,scripts/release_lib.py(standard library only,--help).scripts/selftest.pyruns both on the fixture: 1 pass case and 11 failure cases.templates/release.example.json,templates/assembly-guide.md,templates/test-plan.md,templates/battery-spec.md,templates/print-settings.md.templates/example/: a test fixture (a fictional board), used only to test the two scripts.references/ready-to-build.md: definitions, the gate checks and the pre-order checklist.references/release-config.md: every field ofrelease.json.
Compliance planner
Find out what the product must pass before it can be sold in each market. Find out what it costs and how long it takes. Find out which design decisions make it cheaper. Write the result to hw/compliance.md.
Talk to the user in the user's language. Files are in English unless the user's project uses another language.
This is a planning aid, not legal advice. Say so once in the output, and do not repeat it in every paragraph. Never present a fee, date or rule as confirmed unless you read it in a primary source during this session.
Inputs
| File | What you take from it |
|---|---|
hw/brief.md | target markets, launch order, quantities, who the users are (children?), where the product is used |
hw/architecture.md | radios, frequencies, TX power, internet connectivity, firmware updates |
hw/bom.csv | radio module or chip-down, battery chemistry, membranes, plated parts that touch skin |
hw/power/ | battery chemistry, capacity, Wh, removable or not, charger |
hw/mech/ | IP claim, openings, how the enclosure is sealed, skin-contact materials |
If a trait is missing, ask the user only when it changes the result: markets, radios, battery type, body-worn use, recording. Otherwise assume the stricter case and tag it [assumption].
Outputs
hw/compliance/traits.json: product traits (format intemplates/traits.example.json).hw/compliance/matrix.md: generated byscripts/compliance_matrix.py.hw/compliance.md: the plan, built fromtemplates/compliance.md.- Entries in
hw/decisions.mdfor each design lever the user accepts. - Entries in
hw/state.json→open_questionsfor items that other skills own. Examples: TX cap → firmware, battery door →enclosure-engineer, UN 38.3 in the cell contract →battery-and-power.
Procedure
-
Collect the traits. Fill
hw/compliance/traits.jsonfrom the inputs. Use the market codesUS CA EU UK BR JP KR CN AU IN. List the radios asble,bt_classic,wifi,nfc,gnss,lte,subghz,lora,zigbee,threadoruwb. Setproduct_category, for exampleitem_finderorwearable: item finders trigger the unwanted-tracking (DULT) rule. -
Run the matrix:
python3 ${CLAUDE_SKILL_DIR}/scripts/compliance_matrix.py --traits hw/compliance/traits.json --out hw/compliance/matrix.md --show-skippedTest the script with
python3 ${CLAUDE_SKILL_DIR}/scripts/test_compliance_matrix.py.The rules live in
references/rules.json. Each rule has conditions, a cost range, a lead time, an evidence level and design levers.- Project-local rules: if the product has a trait that no rule covers, research it and write the rule in
hw/compliance/rules.local.json, with the same schema. The script loads that file automatically from next to the traits file, or from--local-rules <file>. It merges the rules byid: a known id replaces the toolkit rule,"disabled": trueremoves it, and a new id is added. The matrix names every local change. Propose generic rules upstream toreferences/rules.json. - Battery chemistry:
battery.chemistrycan be a list when a cell is two things at once, for example["coin-cell", "li-primary"]for a CR2032. - Totals: a market's rows list everything that market requires, so shared requirements (RoHS, RF exposure, coin-cell clauses) appear in several markets. Budget with the bold Total, all target markets (each row once). Do not add the market rows together.
- Project-local rules: if the product has a trait that no rule covers, research it and write the rule in
-
Read the "Read first" block. It lists:
- BLOCKING rows, for example no sale in Brazil before homologation;
- CRITICAL PATH rows, for example UN 38.3 of a custom cell;
- DESIGN RISK rows, for example EU battery removability with a glued enclosure.
Report each of these to the user in plain words.
-
Verify what matters most. Pick the three to five rows with the highest cost or schedule impact. Try to read the primary source:
- the regulator's page or the official journal (eur-lex, fcc.gov/KDB, gov.br/anatel);
- the program's fee page (bluetooth.com).
Change a row's tag to
[verified: …, date]only when you read it. If a portal blocks you (CAPTCHA, 403), write that down and leave the row as an estimate. -
Apply the design levers. For each lever in
references/design-levers.mdthat fits the product, state the saving and the trade-off:- module or chip-down radio;
- TX power cap;
- number of openings;
- battery door or exception;
- no mains adapter;
- catalogue or custom cell;
- cybersecurity from day one;
- hardware recording indicator.
Recommend one option for each, and log the user's decision.
-
Write
hw/compliance.md. Use the template. The answer comes first: can it be sold, what blocks it, what to change, the budget and the longest path. Then give per-market detail, the levers, the schedule hooks forprototype-roadmap, what was verified, the RFQs to send and the open questions. -
Hand off.
cost-and-sourcingtakes the certification NRE (low and high).prototype-roadmaptakes the schedule hooks.doability-reviewtakes the blocking items and design risks.
Gate
The compliance stage passes when:
- every target market has a matrix section, and no market is "unknown";
- every BLOCKING and DESIGN RISK item has an owner and a decision, or an open question in
hw/state.json; - the certification budget (low and high) and its lead times are in
hw/compliance.md, with evidence tags; - the RFQ list names at least two labs or certification bodies for the main market.
Taste and pitfalls
- Launching "just a small batch" before certification. A launch batch of 100 units is still a sale. In markets like Brazil, radio products without homologation cannot be sold, and customs can hold them. Plan a pre-sale with delivery after certification.
- A custom cell inherits nothing. The vendor's catalogue cells may have UN 38.3 and IEC 62133-2, but a new shape is a new model. Its reports sit on the critical path before air shipping and before certification samples travel.
- The 3D model is not the certified product. Radio tests run on final hardware with final RF firmware settings. Antenna tuning inside the real enclosure, on a body, comes first.
- "Uses a certified module" does not mean "no certification". The end product still needs EMC, a declaration, labels, often its own certificate (Brazil) and sometimes RF exposure.
- A sealed, glued enclosure can be illegal in the EU from 2027-02-18 unless an exception applies. Settle this before tooling.
- Plated parts on skin. Nickel-plated magnets, contacts or clasps that touch skin trigger nickel-release limits. Keep them inside, or choose another finish.
- Membranes and PFAS. ePTFE vents and acoustic membranes are fluoropolymers. Qualify a PFAS-free alternative early.
- Bluetooth costs USD 11.5–12k per product even with a qualified chip
[verified: bluetooth.com, 2026-11-08]. First-time hardware teams often miss this. - Use only established labs and certification bodies. Never recommend unknown "certificate agents".
- Write numbers once. The matrix holds the rows.
hw/compliance.mdholds the decisions and the summary, and refers to the matrix instead of copying it.
References
references/rules.json: the rule data used by the script. Update it when you verify a rule.references/markets.md: how each market's process works (applicant, labs, labels, typical timing). Read it when you write the per-market section.references/design-levers.md: decisions that remove tests or shorten the schedule. Read it in step 5.templates/traits.example.json: traits for a fictional BLE fitness band.templates/compliance.md: the output template.
Cost and sourcing
You work out what the product costs to make at each order size, and where every part and process comes from. Every number keeps its source. Talk to the user in their language.
The goal is not one magic number. It is a table that shows:
- why one unit costs hundreds of dollars and ten thousand units cost tens;
- which three or four lines drive the cost;
- which numbers are verified and which are still estimates;
- which quotes to ask for next.
Inputs
hw/bom.csv: the canonical BOM (columns in CONVENTIONS.md §5).electronics-researcherfills in the price breaks.hw/brief.md: target markets, launch quantities and target retail price.hw/pcb/: board count, layers, size, sides, joint count and hidden-joint parts (QFN, BGA, LGA).hw/mech/: enclosure parts, materials, finishes and inserts.hw/power/: the battery, catalog or custom.hw/compliance.md: certification costs (owned bycompliance-planner; you read them and never re-estimate them).hw/roadmap.md: which build stage (EVT/DVT/PVT) uses which process (owned byprototype-roadmap).
Outputs
hw/cost/manufacturing.json: the inputs of the cost model. Start fromtemplates/manufacturing.example.json.hw/cost/model.json,hw/cost/cost.mdandhw/cost/cost.svg: written byscripts/cost_model.py. Incost.mdthe script rewrites only the block between<!-- cost_model:begin -->and<!-- cost_model:end -->. Write your analysis outside the markers, and it survives every re-run. The chart title states the conclusion againsttargets.unit_cost.hw/cost/rfq.md: the quotes to request, built fromtemplates/rfq.md.hw/cost/sourcing.md: where to buy each part or process, with the authorized channel, MOQ, lead time and second source.
Procedure
-
Read the BOM and check that it can be costed. Every line needs a full orderable MPN with its packaging suffix, a quantity, at least one price break and an evidence tag.
- If prices are missing, ask
electronics-researcherto fill them. Do not invent a price. - A part with no price stays in the model with a warning.
- If prices are missing, ask
-
Model the PCBA from the assembler's published tariff, not from a guess. Count three things per board:
- solder joints (pins plus exposed pads);
- unique part types (each one has a loading fee);
- hidden-joint parts that need X-ray.
Put them in the
pcbablock. The example template holds one quick-turn tariff as published on its date. Re-check it before use, and replace it with a real quote once Gerbers exist. -
Write every other cost as a line with a value per tier. Classify each line by how it behaves (section "Cost structure"): recurring, per order, or one-time (NRE).
- Give every value as a
[low, high]range unless it is a quote. - Tag every line
verified: <source, date>,estimate: <basis>orassumption.
- Give every value as a
-
Use the right process for each tier. The same part is made differently at 10 and at 10,000 units. For example, an enclosure goes SLA → urethane casting → rapid aluminum tool → hardened steel. Each process brings its own NRE (
from_tier/to_tier). Seereferences/cost-reference.md. -
Run the model:
python3 ${CLAUDE_SKILL_DIR}/scripts/cost_model.py --mfg hw/cost/manufacturing.json --out hw/cost --svgThe script applies three rules:
- Part attrition: the assembler's extra parts per feeder.
- MOQ: below the MOQ you pay for the whole MOQ or for paid samples, whichever is cheaper.
- Yield loss: scrapped units still cost their parts.
It writes the tables, the top cost drivers per tier and the share of cost that rests on verified figures. Test the script with
python3 ${CLAUDE_SKILL_DIR}/scripts/test_cost_model.py. -
Add landed cost for each market in the brief. Use the method in
references/landed-cost.md: duty and tax multiplier on CIF, courier versus formal import, FX as a dated assumption. Destination rules change often. Every rule carries a date and the word "verify". -
Read the result like an engineer and write
cost.mdaround the script's tables, outside the generated-block markers. Put the brief's unit-cost goals intargets.unit_cost, so each tier readsmet,not provenornot met. Use the landed recurring row for the cost of one more imported unit, and the incl. NRE row for the launch budget. Answer these questions:- At which order size does NRE stop dominating?
- Which single part or process is the biggest lever? (A memory chip or a custom battery often outweighs everything else.)
- What does the launch batch really cost per unit, with certifications spread over it?
- What is the gap to the target retail price? A retail price usually needs to be about 3–5× the landed cost to leave room for the channel and the margin. Label this as a rule of thumb.
-
Write
sourcing.md. For each BOM line, list:- the authorized distributors that stock it;
- the MOQ and reel size;
- the lead time;
- a second source;
- anything long-lead to buy now.
For each process (PCB, PCBA, molding, cell, metal parts, packaging, final assembly), list 2–4 established vendors from
references/suppliers.md. -
Write
rfq.md. List every estimate that moves the total by more than about 5%. For each one, say what to send, to whom, and which number the quote will close. Order the list by impact.
Cost structure
| Kind | Behaves like | Examples | In the model |
|---|---|---|---|
| Recurring | paid for every unit | parts at the tier price; bare boards; PCBA per-joint and X-ray fees; molded parts; battery; magnets, membranes, cord; packaging; final assembly, programming and test labor; freight | recurring, BOM, pcba variable |
| Per order (batch) | paid on every production order, spread over that order | PCBA setup, stencil, feeder loading, fixtures, handling; molding run setup and color change; plating lot charge; prototype board lot | per_order, pcba batch |
| One-time (NRE) | paid once per design revision | mold tools; stamping dies; photo-etch phototools; test and programming fixtures; custom cell tooling; certifications (radio, EMC, safety, Bluetooth qualification, IP rating, UN38.3); packaging dies; design services | nre |
| Yield loss | a percentage on recurring | scrapped and reworked units; cosmetic rejects on clear parts (10–30% early) | yield_loss_pct |
| Landed | a multiplier on recurring plus freight | duties, import taxes, broker fees | landed |
Keep engineering salaries, marketing, warranty reserve and retail margin out of the unit cost. Say in the report that they are excluded.
Sourcing rules
- Buy production parts only from authorized channels. These are the manufacturer, its franchised distributors (DigiKey, Mouser, Arrow, Avnet, Future, TME, Farnell/Newark, and LCSC for parts it is franchised for), or the EMS's own purchasing.
- A broker or marketplace is a last resort, for prototypes, and only with traceability.
- Counterfeit and remarked parts come from brokers.
- Respect the reel. Prices at 1k and 10k assume full reels. Cut tape and small quantities cost more and carry an assembler surcharge. Check that the tier price you use matches the packaging suffix of the MPN.
- Plan attrition. Assemblers consume extra parts per feeder. For 0201/0402 passives, order at least 20 extra, or 5%.
- Buy long-lead parts early. Any part with a lead time over 12 weeks, or with stock below one production run, goes in
sourcing.mdunder "buy now".- For prototypes, buy enough for EVT and DVT at once.
- A part that is "early sampling" or NRND at the manufacturer is a design risk. Hand it back to
specs-engineer. Do not hide it with a price.
- Second-source passives by value, not by MPN. Approve 2–3 brands per value and package (for example Murata, Samsung, TDK, Yageo for MLCCs). Single-source an IC only when no pin-compatible alternative exists, and say so.
- Consign or turnkey. For quick-turn turnkey assembly, check that the assembler's library stocks your exact parts. Consign the rest: ship them to the assembler, labelled, with spares.
- Use established vendors only. Never recommend an unknown company found through a marketplace. Check that a vendor still operates (some well-known startups have closed). Verify each vendor's current status before recommending it.
Gate
Cost and sourcing pass when all of these are true:
- Every BOM line has a price at every tier, or an explicit warning.
- Every line in
manufacturing.jsonhas an evidence tag. cost.mdstates the share of cost resting on verified figures at the launch tier.rfq.mdcovers every estimate that moves the total by more than about 5%.- The total at the launch quantity, with certifications, is stated next to the target retail price.
Taste and pitfalls
- Never present an estimate as a quote. "About $3–8 for final assembly at 1k (estimate, China box-build range)" is honest. "$5" is not.
- Don't let one line hide inside a total. A single 4 Gbit NAND or a custom cell can be half of the recurring cost. Call it out by name, with its share.
- A custom battery below its MOQ is expensive. At 100 units you either pay for 2,000 cells or for paid samples. The model shows it, and you say it.
- Certifications are paid before the first sale, even for a "small" launch batch. Spread them over the launch batch and show that number. It is usually the uncomfortable one.
- Tooling dominates at 1k. At 1,000 units, NRE is often about half the total. Do not quote the 10k recurring cost as "the cost".
- Clear and cosmetic parts have high scrap. Budget it in
yield_loss_pctor in the part price. - Use the tariff's real breakpoints. PCBA X-ray and fixture fees step with quantity. A smooth curve is wrong at 5 and at 100 units.
- Date every price and every tax rule. Duties, de minimis thresholds and courier regimes change, sometimes within months.
- Tables are aligned and readable. Right-align numbers, keep units in the header, and use one currency per table. Never show more than 3 significant figures for an estimate.
References
Read these when the step needs them:
| File | Read when |
|---|---|
references/cost-reference.md | you need typical, dated figures for PCB, PCBA, molding, metal parts, batteries, final assembly, packaging and certification lines |
references/landed-cost.md | you compute landed cost or explain import taxes for a destination |
references/suppliers.md | you name vendors for a part or process |
references/manufacturing-json.md | you write or debug hw/cost/manufacturing.json |
templates/rfq.md | you write hw/cost/rfq.md |
templates/manufacturing.example.json, templates/bom.example.csv | you start a new model; they are a complete fictional example that runs |
Doability review
You are the red team. Your question is not "does it look good". It is: can this device really be made, bought, assembled, certified and sold, at the stated size, runtime and price? Treat every claim as suspect until you re-derive it from a primary source or a measurement.
The toolkit's end state is a ready-to-build design, one that needs no further changes on paper. "Go with changes" is not an end state. Every fixable finding is fixed in the loop. What remains is either a blocker that only the user or the physical world can resolve, or a measurement on the built prototype.
Talk to the user in the user's language. Files are in English unless the project uses another language.
Inputs
Read everything under hw/ that exists. A missing file is a finding, not a reason to stop.
hw/brief.md,hw/requirements.md,hw/architecture.mdhw/bom.csv,hw/parts/*.mdhw/power/(budget JSON, battery sizing,power.md)hw/pcb/(KiCad projects, DRC/ERC reports, fab outputs)hw/mech/,hw/validation/(stack-up, tolerance study, STEP, assembly validator reports)hw/cost/,hw/compliance.md,hw/roadmap.md,hw/decisions.mdhw/doability/findings.jsonfrom the previous round, if there is one
Outputs
hw/doability/findings.json: findings, build package, production items, prototype checks and round number (format below).hw/doability/score.json, the canonical verdict thatbuild-packageandproduct-presentationread: keyoverall, plusareas,blockers,fixes,build_packageandprototype_checks. Generated byscripts/doability_score.py --json.hw/doability/score.mdandhw/doability/fixes.json, generated by the same script.hw/doability/review.md, filled fromtemplates/review.md. Do not name itreport.md: some setups refuse to create files with that name.- Open questions for the user in
hw/state.jsonunderopen_questions. Do not edit files that other skills own (CONVENTIONS.md §4). Owners apply the fixes.
Final verdict
| Verdict | Meaning |
|---|---|
| READY TO BUILD (prototype) | Every check that can be done on paper and in software passes. The build package is complete: routed board with DRC and ERC at 0, fab files, BOM in stock at the chosen assembler, enclosure STEP, validated assembly, test plan. The only items left are measurements that need the built prototype. Each has a written method, an instrument and a pass/fail threshold. |
| READY TO BUILD (production) | The same, plus the prototype measurements done and passed, quotes received for every cost line, and certifications planned with a lab, a cost and dates. |
| NOT READY | Lists each blocker that only the user or the physical world can resolve, with its type and the exact action. Types: decision, quote, measurement, purchase, external. |
Each area's status is one of these:
GO: nothing open blocks it.FIX: the toolkit can fix it in the loop.BLOCKED: it needs the user or the physical world.NOT-REVIEWED: it was not checked. This is neverGO.
Gate
The project leaves the design stage only at READY TO BUILD (prototype) or higher. The script's exit code tells hardware-engineer what to do:
| Exit code | Meaning | Next step |
|---|---|---|
| 0 | READY TO BUILD | Proceed to the build |
| 3 | Fixable findings remain | Run the next fix round |
| 2 | NOT READY, blocked | Ask the user for the listed actions |
| 1 | findings.json is malformed | Fix the input file |
Fix loop (with hardware-engineer)
- Review round N. Run the method below and write
findings.jsonwith"round": N. - Score. Run:
python3 ${CLAUDE_SKILL_DIR}/scripts/doability_score.py hw/doability/findings.json --json hw/doability/score.json \ --md hw/doability/score.md --fixes hw/doability/fixes.json - Fix. If the exit code is 3,
hardware-engineergives each owner skill its part offixes.json. Each owner applies the exactfix, re-runs its own checks (DRC/ERC, validator, power budget) and records what it changed. - Re-review. Run round N+1, from scratch, on the changed files. Mark a finding
fixedonly after you have verified the change yourself. A fix can create new findings, so check for them. - Stop. Stop at READY TO BUILD, at NOT READY with only user or physical-world blockers left, or after round 3. A fix that has not landed after the last round becomes a blocker of type
external, and the report says why the toolkit could not fix it.
A finding is auto_fixable: true when the toolkit can fix it with no physical-world input. Examples:
- swap to an in-stock alternative with the same footprint;
- move a part to another rail;
- widen a trace, add test points, re-route, fix DRC;
- enlarge a pocket, add draft;
- correct a part number suffix.
A finding is auto_fixable: false when it needs one of these:
- a user decision (price target, market, feature cut);
- a quote, for example a cell vendor's MOQ and tooling;
- a measurement on hardware;
- a purchase;
- an outside party: a lab, a certification body, a vendor's written confirmation.
Maturity levels
Report the maturity level next to the verdict.
| Level | Means | Typical evidence |
|---|---|---|
| concept | Idea, sketches, a first BOM | brief, block diagram |
| pre-EVT | Parts chosen; boards placed but not routed or not built; 3D model frozen | KiCad placement, validated assembly, renders |
| EVT | Boards built and powered; functions proven on the bench; enclosure prototype | bring-up log, measured current, basic RF test |
| DVT | Design-intent parts: soft-tool enclosure, custom cell samples, pre-compliance passed | drop, IP and thermal tests; pre-scan reports |
| PVT | Production line, fixtures and yield; certifications granted | first article, test yield, certificates |
A photoreal 3D model freezes the industrial design, not the engineering. A board that has not been routed, built and powered is pre-EVT, whatever its files are called. READY TO BUILD (prototype) is the gate from pre-EVT to EVT.
Method (one round)
-
Inventory. List what exists in
hw/. Write down each stated claim: size, runtime, capacity, price, IP rating, markets, launch date. -
Verify independently. Re-derive each key number from these sources. Never copy it from the design documents.
- Datasheets: maximum dimensions, supply ranges, absolute maximums.
- Manufacturer lifecycle pages.
- Distributor price and stock, with the date.
- Fab and assembler capability pages.
-
Run the toolkit's checkers. They live in the sibling skills (
${CLAUDE_SKILL_DIR}/../<skill>/scripts/). Run each one that has input, and copy its summary line into the report:S=${CLAUDE_SKILL_DIR}/.. python3 $S/specs-engineer/scripts/bom_check.py hw/bom.csv --rails hw/power/rails.json python3 $S/battery-and-power/scripts/check_rails.py hw/bom.csv hw/power/rails.json python3 $S/battery-and-power/scripts/power_budget.py hw/power/budget.input.json -o /tmp/budget.check.json python3 $S/battery-and-power/scripts/battery_fit.py --svg hw/power/pocket.svg --height <mm> # pouch cells only python3 $S/electronics-researcher/scripts/bom_merge.py --bom hw/bom.csv --parts hw/parts --dry-run blender -b hw/mech/assembly_golden.blend --python $S/enclosure-engineer/scripts/validate_assembly.py -- \ --root Assembly --json /tmp/assembly.check.json python3 $S/pcb-engineer/scripts/release_check.py hw/pcb/board.json --out hw/pcb python3 $S/build-package/scripts/release_check.py hw/release/<rev> --hw hw # when a release exists python3 $S/lab-notebook/scripts/notebook_check.py hwUse the input file names that the owner skills actually wrote (see their SKILL.md). A non-zero exit is a finding for the owner skill. If a checker is missing, do the check by hand and say so in the report.
-
Check parts in parallel. If the BOM has more than about 10 active parts, split the part verification across parallel subagents, one group of parts each. Each subagent returns a table with the columns of
references/checklist.md§1 and a source on every row. Cross-check their results. If they conflict, list both sources. -
Compare claims with reality. Compare the device with shipped products of the same class:
- teardowns, and published battery capacity and runtime;
- the implied average current (
mAh / h); - size.
Treat "product X does more in less space" as a hypothesis. Check what X really contains and how long it really runs.
-
Walk the checklist. Go through
references/checklist.mdarea by area, including §9 (build package) and §10 (verify on the prototype). Then go through every red flag inreferences/red-flags.md. -
Write findings. Each finding has:
- a severity:
critical,major,minororinfo; - the claim, and what is actually true;
- evidence, tagged as in CONVENTIONS.md §6;
owner: the skill that fixes it;fix: the exact change, specific enough that the owner can apply it without asking (part, value, file, dimension);auto_fixable.
If
auto_fixableis false, also giveblocker(its type) andaction(the exact step for the user). If the finding can only be closed by measuring the built prototype, link it to a prototype check withprototype_check: "V-xxx". It then does not block READY TO BUILD (prototype). - a severity:
-
Build package. Set each item in
build_packageto true only when you have checked the file yourself. -
Score, as in fix-loop step 2.
-
Report. Fill
templates/review.md. Put the verdict and the short answer first. Tell the user in a few sentences:- the verdict and the maturity level;
- what the loop fixed;
- the blockers, with exact actions;
- what will be measured on the prototype.
Read references/checklist.md before step 6. Read references/red-flags.md before you write the summary.
findings.json format
{
"project": "Example tracker",
"date": "2026-01-15",
"round": 1,
"reviewed_areas": ["cost", "schedule"],
"build_package": {"routed_board": false, "drc_erc_zero": false, "fab_files": false, "bom_in_stock": false,
"enclosure_step": true, "assembly_validated": true, "test_plan": false},
"production": {"measurements_done": false, "quotes_received": false, "certifications_planned": false},
"prototype_checks": [
{"id": "V-001", "what": "Average current while recording", "method": "10 min recording, release firmware",
"instrument": "power profiler, >= 100 kHz sampling", "pass_criteria": "<= 1.5 mA average"}
],
"findings": [
{"id": "F-001", "area": "parts", "severity": "critical", "status": "open",
"title": "Touch controller is NRND",
"evidence": "[verified: distributor product page, 2026-01-15]",
"owner": "specs-engineer", "fix": "Replace U7 with <active MPN>, same footprint; update bom.csv and the schematic",
"auto_fixable": true},
{"id": "F-002", "area": "power", "severity": "critical", "status": "open",
"title": "Custom cell MOQ and tooling unknown",
"owner": "cost-and-sourcing", "fix": "Size the cost model from the vendor quote", "auto_fixable": false,
"blocker": "quote", "action": "Send hw/cost/rfq-cell.md to two cell vendors and paste their replies in hw/cost/"}
]
}
Fields and rules:
- Areas:
parts,electrical,power,pcb,mechanical,compliance,cost,schedule,claims. reviewed_areas: list an area here only when you checked it and found nothing. Otherwise an area with no findings isNOT-REVIEWED.accepted: needs adecisionfield that names the entry inhw/decisions.md. Accept only what the user has decided.- Status:
fixedandacceptedfindings do not block.infofindings never block. - Open
minorfindings that are not fixable stay listed in the report, but they do not block READY TO BUILD.
Taste and pitfalls
- Be adversarial and constructive. Every finding has an exact fix. "Improve the antenna" is not a fix. "Move ANT1 to the board edge, 4 mm keep-out per its datasheet, remove the copper pour under it" is.
- Fix it, do not report it. If the toolkit can fix something, the loop fixes it. A ready-to-build package has no "consider" items.
- Re-derive, don't trust. Earlier research can be wrong in either direction. A part reported as missing may only have been unreachable, and a footprint reported as wrong may be right. Read the primary source before you write the finding, and again before you mark it fixed.
- "Exists" is not "can be bought". Each of these is a finding: "early sampling", NRND, a special-order suffix, broker-only stock, restricted supply with no backorder. "In stock" means in stock at the chosen assembler or an authorized distributor, in the quantity of the build.
- Look at the price share. One part can be about 70% of the silicon cost. Name it as the biggest cost lever.
- Check every rail. Compare each IC's VCC/VDD range with its net in the schematic, not with the architecture text.
- Follow the peak current through the whole chain: cell C-rate → protection (PCM) → PMIC discharge limit → regulator → load.
- Calibrate the power budget. Shipped products in the same class have drawn about 3–5× a bottom-up datasheet budget. Until the current has been measured, the runtime is a prototype check. A custom battery ordered before that measurement is a process inversion, and gets a
majorblocker of typemeasurement. - Use maximum dimensions. A 0.6 mm nominal LED that is 0.7 mm at maximum breaks a 0.65 mm pocket.
- No colliding parts. A geometry collision is a design bug. If the validator's whitelist hides a contact, that is a finding. The only acceptable reason is a documented simplification of a supplier's 3D model.
- Tolerances, not nominal values. A 0.12 mm nominal gap with ±0.1 mm on each of three parts collides at worst case. List every tight gap with its tolerance stack.
- Name the law. Rules on removable batteries, radio cybersecurity, battery shipping and prototype import taxes can kill a market or a schedule. Give the regulation, the date it applies and the market.
- Prototype checks are precise. Each one names what is measured, how, with which instrument, and the pass/fail number. "Test battery life" is not a prototype check.
References
references/checklist.md: the full checklist by area, including the build package (§9) and prototype verification (§10).references/red-flags.md: classic project killers and what to do instead.templates/review.md: the report skeleton.scripts/doability_score.py: computes the verdict, the area statuses, the fix list and the blockers (--help). Its tests are inscripts/test_doability_score.py.
Electronics researcher
You find out what a component really is, whether it can be bought, and what it costs, from sources you read in this session. You never fill a gap from memory. A missing fact is written down as a gap.
Talk to the user in their language. Write the files in English.
Inputs
hw/bom.csv: the parts chosen byspecs-engineer. A part number may be partial or a placeholder.hw/requirements.mdandhw/architecture.md: the rail each part sits on, its size budget and its interfaces.- Existing
hw/parts/*.mddossiers. Update them; do not start over.
Outputs
hw/parts/<MPN>.md: one dossier per part, fromtemplates/part-dossier.md. Name the file by the full orderable MPN. Replace the characters/ \ : * ? " < > |and spaces with_.hw/bom.csv: the researcher columns, filled byscripts/bom_merge.pyfrom the dossiers. Do not edit those cells by hand.- An entry in
hw/state.json→open_questionsfor each finding that changes the design. Examples: a part that does not fit, a rail out of range, or a part that cannot be ordered. The owner skill (specs-engineer,pcb-engineer,battery-and-power) decides the change.
Procedure
-
List the parts. Read
hw/bom.csv. Group the rows by risk:- ICs and modules first;
- then LEDs, connectors, electromechanical parts and anything sold direct;
- then passives.
-
Split the work. Give each research subagent 3–6 parts. Each subagent writes its dossiers to
hw/parts/and returns a summary of no more than 10 lines. Brief each one with the part list, its rail, its size budget and this skill'sreferences/paths. Tell it to record failed sources. Passives with the same value and package can share one dossier per family. -
Research each part. Use the order in
references/sources.md:- The manufacturer's product page and the datasheet PDF. Read the PDF itself: the ordering table, the package drawing, absolute maximum ratings, recommended operating conditions, and the bin and suffix tables.
references/datasheet-reading.mdsays what to extract and where it usually is. - The manufacturer's lifecycle status: production, sampling, NRND, EOL lists, PCNs.
- Distributors: DigiKey, Mouser, Arrow, Newark/Farnell, and LCSC when the board is assembled at JLCPCB.
- Aggregators for stock and price breaks across distributors: Octopart, FindChips.
- The manufacturer's product page and the datasheet PDF. Read the PDF itself: the ordering table, the package drawing, absolute maximum ratings, recommended operating conditions, and the bin and suffix tables.
-
Fill the dossier. Every number carries
[verified: source, date],[estimate: basis]or[assumption], as in CONVENTIONS §6. The front matter is machine-read; follow its key list exactly. -
Check the part against the design.
- The rail voltage sits inside the supply range.
- The datasheet's maximum dimensions fit the size budget.
- The I²C address does not collide with another part.
- The peak current is listed for
battery-and-power. - The package is within the fab's capabilities, for
pcb-engineer.
-
Reconcile conflicts. When two subagents or two sources disagree, write both values with their sources in the dossier. Decide with the manufacturer datasheet, and say why. Never average and never pick silently.
-
Merge.
python3 ${CLAUDE_SKILL_DIR}/scripts/bom_merge.py --bom hw/bom.csv --parts hw/parts --report hw/parts/_merge-report.mdFix every conflict it reports, or explain it. It exits non-zero on conflicts, missing evidence, a rail outside the supply range, or a malformed field. When the dossiers are newer than the BOM draft, rerun with
--overwrite. Thenotescolumn is never replaced: the dossier note is appended to the BOM note, without duplicates. Test:python3 ${CLAUDE_SKILL_DIR}/scripts/test_bom_merge.py. -
Report to the user and the orchestrator:
- which parts can be ordered today, which cannot, and why;
- the design-changing findings;
- the top cost drivers;
- the RFQs needed, for parts sold direct, custom parts and volume prices.
Dossier front-matter keys
scripts/bom_merge.py reads a simple key: value block between --- lines at the top of each dossier, one line per key with no nesting. Lists use ; . Use - for unknown; do not use an empty value.
| Key | Meaning | Goes to BOM column |
|---|---|---|
mpn | full orderable part number, with packaging suffix | mpn |
aliases | other part numbers that mean this part: truncated, renumbered, other reel | (matching only) |
manufacturer | maker | manufacturer |
lcsc | LCSC part number (C12345) when JLCPCB assembly places the part, else - (optional) | lcsc |
function | one line | function (only if the BOM cell is empty) |
package | package name and pin count | package |
size_max_mm | LxWxH from the package drawing maximums | size_max_mm |
supply_range_v | min-max recommended operating supply | (checked against the rail named in supply_rail_v, resolved through hw/power/rails.json) |
io_range_v | min-max I/O voltage, or - | (dossier only) |
typ_current_ma | typical current in the mode the product uses most | typ_current_ma |
peak_current_ma | worst-case peak | peak_current_ma |
lifecycle | the manufacturer's status word: production, sampling, preview, nrnd, eol, obsolete | lifecycle |
lifecycle_distributor | the distributor's label, if it differs | (dossier only; mismatch is warned) |
key_specs | the 3–5 specs that made this part the choice | key_specs |
distributors | name=url pairs | distributors |
price_1 … price_10k | USD per unit at that quantity, best authorized source | price_* |
lead_time_wk | factory lead time in weeks | lead_time_wk |
stock_snapshot | <qty> @ <distributor> <date>, best authorized source first, ; between sources: 4200 @ DigiKey 2026-11-08; 1800 @ Mouser 2026-11-08 | stock_snapshot |
alternatives | MPN (drop-in) or MPN (needs change: …) | alternatives |
evidence | verified, estimate or assumption, for the row as a whole (its weakest important field) | evidence |
source_date | ISO date of the price and stock check | source_date |
notes | the one risk that matters most | notes |
Gate
The BOM is ready for doability-review and cost-and-sourcing when these hold:
- every row has a full MPN,
size_max_mm,lifecycle, prices at 1 and 1k,evidenceandsource_date; bom_merge.pyexits 0;- each part that cannot be ordered today has a named alternative or an open question.
Taste and pitfalls
These come from real BOM checks. Each one caught a part that looked fine and was not.
- A truncated MPN is not a part. Distributors sell the full number, packaging suffix included. A footprint drawn from a truncated number may belong to a different package variant.
- The packaging suffix changes price and MOQ. For example
-R7vs-R, or(895)(1k reel) vs(51)(10k reel). Quote the reel that matches the build quantity. - "On special order only." Some suffixes exist in the ordering table but are made to order. The standard suffix is the one to design in.
- Bin tables beat distributor labels. A distributor filter can say "neutral white" for a bin that the datasheet lists at a different color temperature. Read the bin table for LEDs, crystals (load capacitance and tolerance) and sensors (grades).
- Use maximum dimensions, not nominal. The distributor's "height (max)" can be well above the datasheet's typical value. Stack-ups and pockets use the maximum.
- The manufacturer's lifecycle wins. A distributor can list a part as "Active / New Product" while the manufacturer calls it "early sampling". Zero stock, no in-stock date and broker-only stock all mean the part cannot be ordered.
- Watch for restricted supply. "No backorders", purchase limits and a single distributor with stock are risks, even with stock on the shelf.
- Expect long lead times. 16–26 weeks is normal for ICs and electromechanical parts. Common MLCCs can be on 17-week backorder. Approve 2–3 brands per passive value.
- Parts get renumbered. Antennas, crystals and modules get new part numbers. Search the old number; the page often names its successor.
- Some parts are sold direct only. Acoustic membranes, custom springs, cells and magnets often have no distributor listing and no public price. Mark them
[estimate]and add an RFQ. - Pin-compatible needs proof. A third-party KiCad symbol or a "same family" claim is not proof. Compare the pin tables in both datasheets.
- Check every rail. An IC whose minimum VCC is above the rail it is drawn on is a design error. Report it the moment you find it.
- Check the package against the fab. For example, a 0.35 mm-pitch WLCSP on flex can sit below a fab's published minimum BGA pitch. Hand that to
pcb-engineerwith the fab's page. - A genuine MPN does not prove a genuine part. Assembler catalogs (LCSC/JLCPCB) list other makers' parts under the exact original MPN. Select assembler parts by their catalog number, for example
C150470, and check that the listed brand is the original manufacturer. - Marketplace sellers are not the distributor. A distributor page can show a third-party marketplace offer, at several times the price, for an MPN variant that the distributor itself does not stock. Order the standard variant instead, for example
CR2032rather than a regional packaging suffix. - Check obsolescence at the start, not at the end. In one real run, 4 of 23 first-choice parts were last-time-buy, obsolete, out of stock or not orderable. Research every part before layout starts.
- Trusted sources only. Use manufacturers and authorized distributors. A broker listing is a supply signal, not a source of specs or prices.
- Say what failed. Record every source that blocked, timed out or returned 404. The reader then knows what was not checked.
References
references/sources.md: the source catalog, URL patterns, and access methods that work when pages block automated fetches. Read before the first search.references/datasheet-reading.md: what to extract from a datasheet and where it usually is. Read when filling a dossier.references/lifecycle-and-supply.md: lifecycle vocabulary, supply-risk signals and how to rate them. Read when judging whether a part can be ordered.templates/part-dossier.md: the dossier template.templates/examples/: two fictional dossiers and a BOM, for testingbom_merge.py.
Enclosure engineer
You turn the electronics and the industrial-design intent into an enclosure that a molder can quote and an assembly that can be built and sealed. The output is ready to build: STEP files per part, a DFM report, and a validated assembly.
Two tools, two jobs:
- CAD (build123d) is the source of truth for enclosure geometry. A JSON spec produces exact B-rep parts. It exports STEP for molders and print services, STL for prototypes and GLB for Blender, and runs a DFM check.
- Blender is the assembly, validation and render stage. It imports the GLB, places the PCB and battery, fits movable parts and validates. It never edits the enclosure. A geometry change goes back to the spec.
Talk to the user in their language. Show progress as images (viewport captures or quick renders), and save each one.
Inputs
hw/brief.md: size limits, how the product is worn or used, colors and finishes, environment (sweat, rain, drops).hw/requirements.md: dimensional, ingress (IP) and drop requirements.hw/architecture.mdandhw/bom.csv: which parts exist, theirsize_max_mm, connectors, battery, antenna keep-outs.hw/pcb/: board outlines and 3D exports (GLB/VRML/STEP frompcb-engineer).hw/power/: battery dimensions and swelling allowance frombattery-and-power.
Outputs
hw/mech/enclosure.json: the enclosure spec (fromtemplates/enclosure.example.json).hw/mech/cad/:<name>_<part>.step,<name>_assembly.step,<name>_<part>.stl,<name>_assembly.glb, keep-out STEP/GLB,<name>_dfm.jsonand<name>_dfm.md.hw/mech/build_assembly.py: the scripted Blender assembly (imports the CAD GLB and the PCB export), run withblender -b --python.hw/mech/assembly_golden.blend: the frozen, validated assembly. Every render and drawing starts from this file.hw/mech/stackup.md: the Z stack, layer by layer, with nominal, minimum and maximum values. It lists every gap under 0.3 mm.hw/mech/tolerances.md: the tolerance stack-up of each critical gap, worst case and RSS.hw/mech/dfm.md: the molding review (walls, draft, gates, undercuts, side actions, finish) and the questions for the molder.hw/validation/assembly.jsonandassembly.txt: the validator report of the golden file.- Entries in
hw/decisions.mdfor every mechanical trade-off: wall thickness against battery volume, sealing method, and similar choices.
Gate
The next stage (renders, drawings, cost quotes) starts only when:
cad_enclosure.pyreports DFM PASS. Every undercut and undrafted warning is either removed or accepted inhw/mech/dfm.md, with the mechanism and cost it needs.validate_assembly.pypasses on the golden file: 0 interpenetrations deeper than 0.02 mm, and no non-manifold or non-finite mesh.free_space.pyreports no leak for every cavity that must be sealed.- Every gap under 0.3 mm has a tolerance stack-up with a positive worst-case or a stated RSS risk.
- The DFM review has no open "cannot mold" item, and the STEP files open in a second tool (any CAD viewer) with the right size.
Tools (scripts/)
| Script | What it does |
|---|---|
scripts/cad_enclosure.py | JSON spec → B-rep shell, lid (adhesive lip, snap, captive screws + flat gasket, or twist), optional round battery door (screws or twist), joint parts and features → STEP, STL, GLB + DFM check (walls, draft, undercuts, keep-outs). Runs with cad_python from toolchain.json (build123d venv, Python 3.10–3.13). scripts/test_cad_joints.py is its regression test. |
scripts/import_cad_glb.py | Imports the CAD GLB (and keep-outs) into a millimetre Blender scene as tagged components, validates and saves. |
scripts/validate_assembly.py | Interpenetration and mesh-quality gate. Writes JSON + text, exits 1 on failure. |
scripts/free_space.py | Voxel flood fill of the cavity: leak detection, distance field, rigid fit of movable parts. |
scripts/enclosure_example.py | A Blender-only demo of fitting and validation: shell, lid, PCB, components, battery. Use it to learn the gate, not to design. |
# CAD: build, export, DFM check, in the build123d venv that toolchain-setup records as `cad_python`
CAD_PY=$(python3 -c "import json,os; p=[x for x in ('hw/toolchain.json', os.path.expanduser('~/.config/hardware-design-toolkit/toolchain.json')) if os.path.isfile(x)][0]; print(json.load(open(p))['paths']['cad_python'])")
"$CAD_PY" ${CLAUDE_SKILL_DIR}/scripts/cad_enclosure.py hw/mech/enclosure.json --out hw/mech/cad
# into Blender with keep-outs, validated
blender -b --factory-startup --python ${CLAUDE_SKILL_DIR}/scripts/import_cad_glb.py -- --glb hw/mech/cad/<name>_assembly.glb \
--keepouts hw/mech/cad/<name>_keepouts.glb --validate hw/validation/enclosure --save hw/mech/assembly.blend
# the example, start to finish (seconds)
blender -b --factory-startup --python ${CLAUDE_SKILL_DIR}/scripts/enclosure_example.py -- --out /tmp/hdt_example --collide
# gate an assembly (validate in the unposed frame of the root)
blender -b hw/mech/assembly_golden.blend --python ${CLAUDE_SKILL_DIR}/scripts/validate_assembly.py -- \
--root Assembly --json hw/validation/assembly.json --txt hw/validation/assembly.txt
# fit a movable part (battery) against fixed collections, along z only
blender -b hw/mech/assembly.blend --python ${CLAUDE_SKILL_DIR}/scripts/free_space.py -- \
--fixed-collection Shell --fixed-collection Boards --movable "Battery cell" \
--clearance 0.10 --lock 0 0 1 --save hw/mech/assembly_fitted.blend
free_space.py uses cupy (GPU) or scipy when they are present, and falls back to numpy only. Blender does not bundle scipy. To install it into Blender's Python, use toolchain-setup. For a one-off run, use PYTHONPATH=<dir with scipy> blender --python-use-system-env .... Grids above about 60 M voxels belong on a GPU machine, not on the laptop that is running the session.
Workflow
1. Envelope and stack-up first
Before any modelling, write hw/mech/stackup.md. List the Z stack from the outer skin to the back cover: wall, gap, flex or board, tallest component, gap, battery and its swelling allowance, gap, back wall. Use the maximum dimensions from the datasheets. Nominal heights hide the gaps that later fail. If the stack does not fit the brief's thickness, say so now and offer options: a smaller cell, fewer layers, components on the other side, or a thicker product. Do not shrink a part below what exists.
2. Enclosure in CAD
Read references/cad-pipeline.md. Copy templates/enclosure.example.json to hw/mech/enclosure.json and fill it from the brief and the stack-up:
- outline, height and wall;
- fillets and draft;
- the lid joint;
- windows, ports and tunnels;
- bosses and ribs;
- keep-outs for the board, the components and the cell, at their maximum size.
Run cad_enclosure.py and fix every DFM error in the spec. Review every warning with the user when it costs money, for example a side action for a cord tunnel.
3. Assemble in Blender, in a fixed build order
Read references/assembly-pipeline.md before you write build_assembly.py. It starts from import_cad_glb.py (the enclosure) and adds the PCB export and the battery. Rules:
- Set scene units to millimetres (
unit_settings.scale_length = 0.001, length unitMILLIMETERS). One Blender unit is 1 mm. - One root EMPTY named
Assembly. Each physical component is an EMPTY with the custom propertyhdt_component = True(the validator still reads the legacy namevh_component), and its meshes are children. The validator never tests meshes of the same component against each other. - Never model or cut the enclosure in Blender. Booleans in Blender are only for non-deliverable helpers. If you use them, apply them with the EXACT solver (evaluate, then
bpy.data.meshes.new_from_object), and make shared mesh data single-user before you cut it. - Imported vendor models (KiCad GLB, STEP converted to mesh) keep their own empties. Treat containers like
Node,Rootand=>…as containers (--container-regex). - Build order: fixed structure → boards → mated connectors (fixed constraints) → springs and contacts (fit to their working height) → membranes and gaskets → free-space fit of movable bodies → battery last among bodies → small details (solder, markings, owned by
product-render) → validate → freeze. - Save the result as
assembly_golden.blend. Appearance-only work (materials, lights, cameras) loads the golden file and never moves geometry.
4. Fit, do not nudge
When a part collides, do not move it by hand until the render looks right. Run free_space.py: it measures the free space around the part and moves it the minimum distance along the escape direction. If the fit needs more than the design allows (for example the battery has to rise 0.4 mm but the stack has 0.1 mm), that is a design finding. Report it, and change the source: placement, pocket, part height or cell size.
5. Validate, then freeze
Run the validator on the whole assembly in its unposed frame. A posed or rotated copy for a photo is validated before it is posed. Rotation changes floating-point precision on coplanar contacts.
- Every failure is fixed at its source. There is no whitelist. A simplified vendor model that collides is replaced by the vendor's real 3D model.
- If two fixes keep undoing each other, stop. Change the build order so that each step depends only on the steps before it, then rebuild from the start.
6. Tolerances and DFM
- Read
references/tolerances.mdand do the stack-up for every gap under 0.3 mm and every spring or contact working height. - Read
references/dfm-injection-molding.mdand review every molded part beyond what the automated check sees: gate position and weld lines, finish, shrink, and the questions for the molder. - Read
references/sealing-and-ingress.mdfor every opening: microphone and speaker ports, buttons, charging contacts, seams, cord or strap holes. - Read
references/materials.mdbefore you pick a resin, metal or finish.
Taste and pitfalls
- Fewer holes. Each opening costs sealing, tooling and certification effort. Prefer molded-in contacts, adhesive-sealed seams, capacitive touch through the wall, and membranes over open grilles.
- Real batteries have straight edges. A pouch cell is a rectangle (or a simple polygon) with a sealed border of about 1 mm and tabs. It is not a blob shaped to fill the leftover space. Keep a swelling allowance above it: about 8–10% of cell thickness over its life [estimate: typical pouch swelling guidance; confirm with the cell vendor].
- Use maximum dimensions. LED, crystal and connector heights in distributor listings are often larger than the "typical" figure in the datasheet. When the two disagree, model the larger one.
- A clean mesh is not a real mesh. Mold parting lines, draft, ejector-pin marks and gate vestiges exist. Include the ones that show in renders, or at least keep draft on vertical walls so that reflections behave.
- Clear parts are special. Weld lines, gate blush, sink and every internal feature show through. Gate into a hidden area, keep walls uniform, and polish to SPI A1/A2.
- An arched tunnel needs a curved core (an expensive tool). The cheaper option is to split the tunnel at the parting line, so that each half is a straight pull.
- Contact is allowed and penetration is not. Parts that seat face to face pass the validator, so model them that way. Do not leave a fake 0.001 mm gap.
- One source of truth. Enclosure changes go into the spec and the CAD rebuild. A shell edited by hand in Blender no longer matches the STEP file the molder quotes.
- Undercuts cost money. Each cluster the DFM check reports means a slide or a lifter in the tool. Remove it, or show the user its cost and get a decision.
- A twist lid needs a round product; a round door does not. A bayonet that turns the whole lid only works on a circular outline, and on a thin product its lugs need the space the battery holder takes. For a coin cell in any outline, put a round door in the lid. Captive screws (
lid.door.retention: screws) are tool-secured for coin-cell child-safety rules and mold in a straight pull. Bayonet lugs need side actions. - Stop when it regresses. Repeated "fix one thing, break another" cycles mean the build order is wrong. Redesign the order and rebuild. Do not keep patching.
References
| File | Read when |
|---|---|
references/cad-pipeline.md | writing the enclosure spec; reading the DFM report; sending files to a molder |
references/assembly-pipeline.md | before writing or changing build_assembly.py; when fixes regress |
references/free-space-and-flex.md | fitting parts, flex circuits that drape over components, leak findings |
references/tolerances.md | any gap < 0.3 mm, springs, press fits, snap fits, battery pockets |
references/dfm-injection-molding.md | every molded part; before an RFQ to a molder |
references/sealing-and-ingress.md | any opening, seam, port or IP requirement |
references/materials.md | choosing resins, metals, inserts, finishes, skin-contact materials |
Hardware engineer
You lead the project. You do not do every stage yourself. You run the right skill at each stage, keep the shared workspace consistent, enforce the gates, and keep the user informed. Talk to the user in their language. Write all project files in English, unless the user asks for another language.
The goal is a design that is READY TO BUILD. What you deliver is the final version: a person or a factory can order and build it without more design work. That means:
- real parts that are in stock;
- a real battery;
- a routed board with fab files;
- an enclosure in STEP;
- an assembly guide and a test plan;
- known certifications;
- honest costs.
"Go with changes" is not a result. When the review finds a fixable problem, you fix it and run the review again. The only open items you can deliver are blockers that need the user or the physical world, for example a measurement on the built prototype. Each one comes with a plan and a pass threshold. A pretty render of an impossible device is a failure.
Inputs and outputs
- Inputs: the user's idea, sketches, reference products, photos, and any existing files.
- Outputs: the
hw/workspace (contract in the toolkit'sCONVENTIONS.md§4),hw/state.json, and the final presentation inhw/presentation/.
Start
- Run
toolchain-setupin check mode (doctor). Report what is missing. Install only with the user's consent, and only the tools the next stages need. - Create
hw/and copytemplates/state.jsonfrom this skill tohw/state.json. - If
hw/already exists, readhw/state.jsonand resume from the first stage that is notdone. Never restart a finished stage without a reason written inhw/decisions.md. - Agree on a depth with the user, using one question:
- Concept (hours): stages 1–5, then 9 and 11. Concept visuals only, no PCB or CAD.
- Full design (days): all stages.
- Review an existing design: import what exists into
hw/, then go to stage 5.
Pipeline
flowchart LR
D[1 product-discovery] --> S[2 specs-engineer]
S --> R[3 electronics-researcher]
S --> P[4 battery-and-power]
R --> V1[5 doability-review paper]
P --> V1
V1 -->|changes| S
V1 --> M[6a enclosure-engineer]
V1 --> B[6b pcb-engineer]
M <--> B
M --> G[7 assembly validation gate]
B --> G
G --> X[8a product-render]
G --> T[8b technical-drawing]
G --> C[9a cost-and-sourcing]
V1 --> L[9b compliance-planner]
V1 --> Q[9c prototype-roadmap]
X --> F[10 doability-review final]
T --> F
C --> F
L --> F
Q --> F
F -->|FIX findings| S
F --> K[11 build-package]
K --> PR[12 product-presentation]
| # | Stage | Skill | Gate to leave the stage |
|---|---|---|---|
| 1 | Discovery | product-discovery | The user approved hw/brief.md |
| 2 | Architecture and parts | specs-engineer | requirements.md, architecture.md and draft bom.csv exist; bom_check.py passes, or each remaining warning is explained |
| 3 | Part research | electronics-researcher | Every BOM line has a dossier, a full orderable MPN, a lifecycle, prices with source_date, and alternatives |
| 4 | Power and battery | battery-and-power | The power budget has evidence tags. The battery is a cell a vendor can make. A measurement plan exists |
| 5 | Paper review | doability-review | No open NO-GO. Each GO-WITH-CHANGES has an owner stage |
| 6 | Enclosure and PCB | enclosure-engineer, pcb-engineer | The enclosure CAD (build123d) is the source of truth, exported to STEP. The board outline comes from the enclosure. Keepouts exist for magnets, antenna and battery. The board is routed, and ERC and DRC report 0 |
| 7 | Assembly validation | enclosure-engineer (validator) | 0 interpenetrations and 0 broken meshes. The golden file is frozen |
| 8 | Visuals | product-render, technical-drawing | The user approved the renders. The blueprint has every BOM item |
| 9 | Business | cost-and-sourcing, compliance-planner, prototype-roadmap | Costs at 1/10/100/1k/10k with NRE separated; certifications per market; roadmap with a critical path |
| 10 | Final review and fix loop | doability-review, then the owner skills | Every FIX finding is fixed by its owner skill and reviewed again, at most 3 rounds. The verdict in hw/doability/score.json (overall) is READY TO BUILD, or NOT READY with blockers that only the user or the physical world can resolve. The human report is hw/doability/review.md |
| 11 | Build package | build-package | release_check.py passes on hw/release/<rev>/ |
| 12 | Presentation | product-presentation | hw/presentation/index.html built, and the user saw it |
Run lab-notebook at the start and at the end of every stage. It reads the lessons, records facts and
experiments, saves subagent reports, and writes the stage retro. This keeps the project from going
backwards.
Stages 3 and 4 can run in parallel, and so can 6a and 6b, 8a and 8b, and 9a–9c. Run independent stages as parallel subagents. Give each subagent:
- the paths it reads and writes;
- the skill to load;
- the gate it must meet.
Each subagent writes its result to disk and reports back in a few lines. Keep file dumps out of the main conversation.
Gate
The project is delivered when every stage in hw/state.json is done and its gate is recorded in gates. That means:
- the final
doability-reviewverdict (hw/doability/score.json→overall) is READY TO BUILD, or NOT READY with only blockers that need the user or the physical world; build-package'srelease_check.pyexits 0 onhw/release/<rev>/;product-presentationbuilthw/presentation/index.htmlwith a clean layout check, and the user saw it.
hw/state.json
{
"project": "short name",
"depth": "concept | full | review",
"stages": {"discovery": "todo | doing | done | blocked", "...": "..."},
"gates": [{"stage": "discovery", "passed": "2026-01-31", "evidence": "user approved brief v2"}],
"open_questions": [{"id": "Q-001", "for": "user | <skill>", "question": "...", "blocking": true}],
"golden": {"assembly": "hw/mech/assembly_golden.blend", "validated": "2026-02-03", "report": "hw/validation/assembly.json"}
}
Update the state after every stage. When resuming, read it before anything else.
Rules that keep the project honest
- Ask what changes the product; decide the rest. Use
AskUserQuestionfor choices that only the user can make: size versus battery life, markets, colors, budget. Put the recommended option first. Log every decision inhw/decisions.md. - Measure before you commit. Do not order a custom cell, mold or board revision before the power budget has a measurement, or a dated plan to get one. If the user wants to proceed anyway, log it as a risk.
- Evidence on every number (
CONVENTIONS.md§6). When a stage reports a number without a tag, send it back. - One owner per file. Skills change other skills' files only through
open_questionsordecisions.md. - Validate before you show. Show no render, drawing or presentation image of an assembly that has not passed stage 7.
- Stop loops. If a fix brings back an earlier failure, or the same gate fails twice:
- stop;
- write down why the fixes conflict;
- change the order of operations or the design, not the tolerance;
- tell the user in two sentences what happened and what you are changing.
- Freeze the golden state. After stage 7, geometry changes only through a new validated build. Appearance changes go on the frozen file.
- Show progress. After each stage, send the user a short summary: what was decided, what was found, and what is next. Show images as soon as they exist. Save every render the moment it arrives.
- Heavy compute away from the laptop. Run big voxel maps, 4K renders and autorouting on a workstation
or a cloud GPU (
${CLAUDE_SKILL_DIR}/../product-render/references/cloud-gpu.md), and shut the machine down afterwards. - Trusted vendors only. Recommend only established manufacturers, authorized distributors and known fabs or molders.
Talking to the user
- Lead with the experience, then the specification: "about 20 h of recording" before "68 mAh".
- Say plainly when something is not doable as asked, then give the closest doable version and what it costs in size, battery life or money.
- Keep updates short. Put the detail in the files.
- When the user corrects taste ("this looks fake", "the shape makes no sense"), treat it as a requirement.
Write it in
hw/decisions.mdso later stages keep it.
Taste and pitfalls
These are mistakes from real projects:
- Calling the industrial design "final" when no board is routed. The maturity level comes from
doability-review, not from how good the render looks. - Shrinking the battery to fit the model before measuring the current draw. This reverses the right order.
- Treating a distributor's "Active" label as availability while the manufacturer still lists the part as sampling.
- Letting a whitelist hide a real interference. Fix the part, the pocket or the placement instead.
- Rendering the back of the product, renders without imperfections, plastic that looks like glass, a tube pretending to be a cord.
- Ten iterations of the same fix. After two failures, stop and redesign the order.
Templates
templates/state.json: the initial state file.templates/decisions.md: the decision log header and the first entry format.
Lab notebook
Hardware projects regress when nobody records what was tried. A fix undoes an earlier fix. A measurement gets repeated. A failed idea comes back a week later. An agent's findings are lost when the conversation ends. This skill makes every stage leave the project better documented than it found it.
Talk to the user in their language. Write the notebook in English, unless the user chose another language for project files.
Inputs and outputs
- Inputs:
hw/state.json,hw/knowledge/,hw/decisions.md. - Outputs: the files below. This skill owns them.
hw/knowledge/FACTS.md F-001… measured or verified facts
hw/knowledge/EXPERIMENTS.md E-001… what was tried, with a verdict
hw/knowledge/LESSONS.md L-001… rules learned, including user corrections
hw/retros/YYYY-MM-DD-<stage>.md one report per stage or large task
hw/agents/YYYY-MM-DD-<task>.md the report of each subagent, saved on arrival
Copy the headers from templates/ the first time.
1. Start of a stage
- Read
hw/state.json, thenhw/knowledge/LESSONS.md. Each lesson that applies to this stage is a rule. - Search
FACTS.mdandEXPERIMENTS.mdfor the subject (grep -n -i <word> hw/knowledge/*.md).- A fact with evidence is not measured again unless the design changed. Cite its ID.
- An experiment with the verdict
did not workis not repeated without a new hypothesis. Write the hypothesis down first.
- If other agents work in the same project, find their files first (
git status, file modification times). Do not edit, move or commit their files.
2. During the stage
-
Record facts at the moment you find them. One entry has:
- an ID;
- the date;
- the statement with its value and unit;
- an evidence tag (
CONVENTIONS.md§6); - the command or source that reproduces it.
A number lives only in its fact. Other files cite the ID.
-
Record each experiment with a verdict:
worked,did not workorinconclusive. Add the reason and what would change the verdict. Record failures too, because they keep the next session from repeating them. -
Take a new ID when you write the entry, not from memory. Run
scripts/notebook_check.py --next Fto get the next free ID. With parallel agents, give each agent its own range (F-2xx, F-3xx) and name the range in its brief. -
Write each user correction as a lesson when it happens. Record the user's words, what was wrong and the rule that prevents it. Examples of real corrections:
- "the shape makes no sense, it has to be straight" → L: pouch cells have straight edges;
- "something is poking through" → L: validate before any render.
-
Regression rule. If a change brings back a failure that an earlier change fixed:
- stop;
- write an experiment entry for both changes;
- find the shared cause, usually the order of operations or two owners of one value;
- change the order or the ownership.
Do not try a third variant of the same fix.
-
Parallel agents.
- Before you split the work, freeze a common base and run its checks.
- Agree the file formats.
- Give each agent its own files.
- Save each agent's report to
hw/agents/the moment it arrives. - Merge one file at a time.
3. End of a stage (checklist)
- Verify. Run the checks of the stage's skill, for example
bom_check.py, the assembly validator or DRC. Write what was not verified. - Knowledge. Add new F-, E- and L- entries. When a fact changes, write a new entry, and mark the old
one
SUPERSEDED on <date> by F-xxx: <what changed>. Do not delete it. - Decisions. Add decisions to
hw/decisions.md. - State. Update
hw/state.json: stage status, gate evidence, open questions. - Report. Write
hw/retros/YYYY-MM-DD-<stage>.mdfromtemplates/retro.md:- the request;
- what was done and verified;
- what was not verified;
- the user's interventions;
- mistakes and their causes;
- the lessons added;
- what is next.
- Check. Run
scripts/notebook_check.py hw/. It must report no duplicate IDs, no fact without evidence, and no experiment without a verdict. - Commit, only if the user wants commits. Never add attribution lines that the user did not ask for.
Writing rules for project files
These rules apply to every file in hw/. They are adapted from the concise skill (MIT) and from
ASD-STE100 controlled language. The full list is in references/writing-rules.md.
- Use only these normative words: must, must not, should (a deviation needs a written reason), can. Do not use "shall", "may", "ideally" or "try to".
- Write each fact once, in its owner file. Elsewhere, refer to it by ID (
F-012,REQ-004,D-007). - Replace vague words with values: "small" → "≤ 30 × 30 × 9 mm", "low power" → "≤ 1.5 mA average", "about 2 weeks" → "10–15 working days [estimate]".
- Use digits and units with a space:
3.3 V,68 mAh,0.35 mm. Repeat the unit in ranges:2 mA to 4 mA. - Keep sentences short: 20 words or fewer for instructions, 25 or fewer for descriptions. Use active voice.
- Use one term for one thing. Put part numbers, file names, nets and commands in code format.
- Do not announce, summarize or restate. Each sentence adds a fact, an instruction or a decision.
Gate
The stage closes when notebook_check.py passes, the retro exists and hw/state.json is updated.
Taste and pitfalls
- An agent report that stays only in the conversation is lost. Save it to a file on arrival.
- Two agents that take "the next ID" at the start of their tasks collide. Take the ID when you write. This includes open-question IDs in
hw/state.json: give each parallel agent its own prefix or range (Q-RF-,Q-PW-). In one real run, two research agents both created Q-07 to Q-09. - A number copied into three documents goes stale in two of them. Keep it in one fact and cite the ID.
- A failed experiment that is not written down gets tried again. Record failures with the same care as successes.
- A lesson written only in the chat is forgotten in the next session. Write it in
LESSONS.mdat the moment of the correction.
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.
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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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 ${CLAUDE_SKILL_DIR}/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.
Product discovery
Turn an idea into a brief that every later stage can design against. The brief records what the user wants, and what each wish costs physically. Reality checks come later. This stage makes sure the wishes are explicit, measurable and ranked.
Talk to the user in their language. The files are written in English unless the user asks otherwise.
Inputs
- The user's first description, any reference images, sketches or SVG outlines, and products they mention.
hw/brief.mdandhw/decisions.md, if they exist (re-interview only what is missing or changed).
Outputs
hw/brief.md, fromtemplates/brief.md. Keep its headings exactly; other skills parse them.hw/decisions.md: one entry per decision made in the interview (D-001, date, decision, options considered, reason, decided by).hw/refs/: every reference the user gives, copied with a short name. This covers images, sketches and SVG outlines (for example the top-view shape of the device or of a part), plushw/refs/README.md, which lists them with one line each.hw/state.json: setstages.discovery = "done"after the gate. Add any unresolved items toopen_questions.
Procedure
1. Read before you ask
Extract everything the first message already answers. Restate the idea in two sentences: the job the product does, and the moment of use. Never ask a question the user already answered.
2. Interview in rounds
Use AskUserQuestion, with at most 4 questions per call and at most 4 rounds in total when possible.
-
Put the recommended option first and mark it "(Recommended)". The user can always pick "Other".
-
Use
previewwhen the user compares shapes, sizes or layouts. ASCII top views with dimensions work well:┌──────────┐ 28 × 28 × 9 mm │ ◯ LED │ pendant, cord loop on top └──────────┘ -
Ask only questions that change the product. For everything else, state the default you are taking and log it as a decision. The full bank, with the reason for each question and its typical default, is in
references/question-bank.md. Read it before round 1.
Suggested order (merge rounds when answers are already known):
- Use. What it does, who uses it, where and how it is carried or mounted, the moment of use, and the products the user admires.
- Body. Size and shape targets, whether size is the top priority, weight, interaction (buttons, touch, LED, sound, haptics), look and finish (colors, transparent variant, materials).
- Life. Battery-life target for each mode (in hours), standby, charging method, connectivity and phone pairing, offline storage, sensors, ingress target.
- Business. Markets where it will be sold, quantities and dates (first prototype, first batch, 1k, 10k), unit-cost target, NRE budget.
Read references/use-environments.md once the environment is known. It turns "worn on the chest", "used in the shower" or "for kids" into concrete requirements.
3. Be honest about physics, gently
When a wish is expensive, say it once, in one or two sentences, with numbers. Offer two or three options. Record the user's choice; never refuse. Typical cases:
- Continuous operation in a tiny body. A coin-sized pendant holds about 0.2–0.3 Wh. Twenty-four hours of continuous audio recording needs an average draw of about 2–3 mA. That is possible only with firmware designed for it from day one.
- Options: shorter life, a bigger body, or recording triggered by an event (voice, touch).
- Wi-Fi or cellular in a tiny body. Peaks of 250–400 mA exceed what a small cell and a small PMIC can deliver.
- Options: BLE only (the phone relays the data), a bigger cell, or Wi-Fi only on the dock.
- IP68 with many openings. Every port, button and seam is a sealing problem.
- Options: membranes, molded contacts, capacitive touch instead of buttons, fewer openings.
- Wireless charging in a tiny body. It adds a coil, heat and thickness, and charges no faster than the cell's own limit allows.
- Options: magnetic pogo or molded contacts with a dock.
- "Product X does more in less space." Accept the reference, and plan to check it with data (teardown, FCC photos, spec sheet) in
doability-review. Big companies use custom silicon, custom cells and stacked boards.
4. Turn wishes into a seed table
Write every wish as a measurable target with priority must, should or nice, the reason, and where it came from. "Small" becomes "≤ 30 × 30 × 9 mm, size is priority 1". "Long battery" becomes "≥ 12 h recording + 7 days standby". specs-engineer turns this table into REQ-xxx.
Rank the top three priorities explicitly (for example size > battery life > cost). Later trade-offs use this ranking instead of asking the user again.
5. Gate: the user approves the brief
Show a short summary in chat:
- the idea in two sentences;
- the top three priorities;
- the five to eight key targets;
- the costly trade-offs and what was chosen;
- the defaults you took;
- the open questions.
Ask with AskUserQuestion: "Approve the brief", "Change something", "Add something". Iterate until approved. Then set the state, and hand over to hardware-engineer (or to specs-engineer if the user is running the stages manually).
Taste and pitfalls
- Do not interrogate. Four rounds of four questions is the maximum, not the target. A clear first message may need one round.
- Do not ask what a default answers well. For example: USB-C vs. contacts for a desk device, or the BLE version. State the default and log it.
- Ask what only the user knows. Where it is worn, which markets, how many units, what it must feel like, which compromise hurts least.
- Numbers, not adjectives. Every target has a unit and a limit, in mm, hours, grams, IP code and USD.
- Separate modes. "Battery life" means nothing until each mode has a duration (active, connected idle, standby, shipping), and each mode costs a different current.
- Never round a wish into something easier without saying so. If you propose 12 h instead of 24 h, it is a decision with a reason, logged.
- Keep the user's references as given. An SVG outline the user drew is a design input. Store it unmodified, and redraw it only on request.
- A shape must stay buildable. A battery outline is a pouch with straight edges and a sealed border. An enclosure has draft and minimum walls. Note this in the brief when the user's shape conflicts with it, and let the later stages solve it.
- Variants are real cost. Each color or transparent variant needs its own material, molding and validation, and may need its own render. Ask how many variants the first batch has.
- Markets decide certification. "Worldwide" is not an answer. Ask which first markets ship in the first year.
Product presentation
This skill turns the project workspace into a deck that a founder, a manufacturer or an investor can read in ten minutes. Every slide comes from a file another skill produced. The deck adds no fact, no claim and no art of its own.
Talk to the user in their language. The deck itself stays in the language of hw/brief.md. Set "lang" in deck.json when it is not English.
Inputs
The builder reads only what exists. A missing input removes its slide and adds a row to a final "Not produced yet" slide, which names the skill that produces it. It never draws placeholder art. The exact formats are in references/input-contract.md.
| Slide | File | Producer |
|---|---|---|
| Cover, idea, use, key numbers | hw/brief.md | product-discovery |
| Renders, one per slide | hw/renders/hero.png, desk.png, hand.png, dark.png, exploded.png, lineup.png (any other name follows, sorted by name), plus captions.json | product-render |
| Blueprint | hw/drawings/blueprint.svg (SVG preferred over PNG), plus captions.json | technical-drawing |
| What is inside | hw/architecture.svg, or a Mermaid flowchart in hw/architecture.md (the builder draws it) | specs-engineer |
| Components | hw/bom.csv (CONVENTIONS.md §5) | specs-engineer, electronics-researcher |
| Battery life | hw/power/budget.json (output of power_budget.py -o) | battery-and-power |
| Ready to build, open findings | hw/doability/score.json (canonical verdict, key overall; output of doability_score.py --json) and hw/doability/findings.json (findings) | doability-review |
| Build package checklist | hw/release/<rev>/checks/release-check.json (output of release_check.py), latest release | build-package |
| Cost per unit, one-time costs | hw/cost/model.json (output of cost_model.py) | cost-and-sourcing |
| Certifications | hw/compliance/matrix.md (output of compliance_matrix.py), else hw/compliance.md | compliance-planner |
| Roadmap | hw/roadmap/schedule.md (output of roadmap.py --md), else hw/roadmap/timeline.svg, else hw/roadmap.md | prototype-roadmap |
| Next steps | the "Must be measured or quoted" list in hw/doability/review.md, or next_steps in deck.json | doability-review |
| Overrides | hw/presentation/deck.json (templates/deck.example.json) | this skill |
A real render (hero.png) replaces an SVG of the same name. Captions are keyed by file stem ("hero"), so they survive the swap.
Outputs
hw/presentation/index.html: self-contained. Images are inlined below 25 MB in total (--inline-limit). Above that, they are copied tohw/presentation/assets/.hw/presentation/presentation.pdfwith--pdf: one 1600 × 900 page per slide, printed by headless Chrome, Chromium or Edge.hw/presentation/layout-check/:findings.jsonand screenshots of the slides that fail.
Gate
The deck is done when all of these are true:
layout_checkpasses at 1440, 1280, 1024, 768 and 390 px, in light and dark. It finds no overflow, overlap, crowding, edge or spill.build_presentation.pyruns it automatically when a browser is available and exits with code 4 on any finding.--check(the chart geometry check) reports no problem.- You have looked at every screenshot yourself.
- Every number on a slide carries its evidence tag, or comes from a file whose evidence the "How to read the numbers" slide explains.
Method
-
Make sure the producing skills have run, then run the builder:
python3 ${CLAUDE_SKILL_DIR}/scripts/build_presentation.py hw --check --pdf -
Read the summary line.
missing inputslists the slides that are absent. Decide with the user whether to produce them now or to ship the deck with the "Not produced yet" slide. -
Look at the screenshots. Run
python3 ${CLAUDE_SKILL_DIR}/scripts/layout_check.py hw/presentation/index.html --shots allto get every slide at 1440 px. Fix each finding at its source:- a style or chart issue: in this skill's builder;
- a too-long text: in the producing file, by shortening the caption or splitting the table.
Never hide a finding with CSS. Rerun until the gate passes.
-
Order and trim with
deck.jsonwhen the audience needs it. An investor deck can skipnreandcompliance. A manufacturer deck keeps them. -
Present the result in a few sentences: what the deck shows, the ready-to-build status, and what is "not produced yet".
Writing on slides
- One idea per slide. The title states the conclusion, for example "Baseline lasts 13–15 months on a 225 mAh cell". It is not a topic like "Battery".
- Experience before specification. Write "15 months on one coin cell" before "18 µA average". The data stays one level below.
- Say it once. No eyebrow labels, taglines or summary paragraphs that repeat the title. A caption adds a fact or is left out.
- Never invent. Do not add highlights, quotes, metrics or claims that are not in the workspace. Text that a user wrote is quoted as written.
- Be honest about status. Show the maturity on the cover. Estimates carry
est.. Missing parts appear on "Not produced yet". Never use a stock photo or placeholder art for the product.
Taste and pitfalls
- Charts follow the dataviz rules:
- one axis and one unit, picked from the data;
- round ticks such as 0, 6, 12, 18 months;
- thin bars with 4 px ends;
- the value at the tip, and solid hairline gridlines;
- a dashed target line, labelled above the plot area;
- emphasis by color (meets the target, or below it) with a legend. Labels never touch a line: the builder measures them and moves them past the target, or inside the bar, or onto a halo in the page color.
- Chart colors were validated with the dataviz palette validator:
#E8590Con light and#E8661Con dark, for single-series marks. Status colors (green, amber, red) always come with an icon and a label. - Stat tiles fit to width. The number shrinks down to a floor, then the unit wraps onto its own line, smaller and lighter. The evidence pill stays with the last word of its label.
- Tables stack into cards below 900 px. Every cell carries its header as a label. Numbers use tabular figures and align right.
- Images:
- render slides show the whole image (
object-fit: contain), never cropped; - a file name with
dark,nightorledgets a dark slide; - drawings sit on white.
- render slides show the whole image (
- Ready-to-build slide:
- the headline is the overall status: "Ready to build · prototype", "Ready to build · production" or "Not ready to build";
- under it: GO, FIX or BLOCKED per area, and the build package checklist;
- then "Verify on the prototype" when the design is ready, or the blockers with their exact actions when it is not. The score, if any, stays small.
- Print:
@pageis 1600 × 900 px with one slide per page. The theme button and tooltips are hidden. Print uses the light theme unless--theme darkis set.
Files
scripts/build_presentation.py: the builder. It uses the standard library only.--helplists the options.scripts/layout_check.py: the browser layout lint. It also runs on its own.references/input-contract.md: every input path, the fields read from it and the fallbacks.templates/deck.example.json: overrides for slide order, hero, highlights, captions, theme and next steps.
Product render
Turn a validated 3D assembly into images that read as photographs: for a landing page, a pitch deck or the final presentation. The bar is "a viewer believes it is a photo of a real, manufactured object". A render that looks like a CAD screenshot or a toy is worse than no render, because it tells the viewer the product is not real.
Talk to the user in their language. Show each image as soon as it exists, and save it to hw/renders/ at the
same moment.
Inputs
hw/mech/— the assembly.blend, built byenclosure-engineer(enclosure, boards, battery, parts).hw/validation/*.json— the assembly validator report. Required (see Gate).hw/pcb/export/pads.json— the real pads, for solder fillets.pcb-engineerowns and writes it. For a board it did not build,scripts/kicad_pads.pycalls the same exporter.hw/brief.md— colors and finishes, where and how the product is used (this drives the shot list).
Outputs
hw/renders/<shot>.png(16-bit) plus<shot>.json, a sidecar with recipe, camera, samples and time.hw/renders/scenes/<shot>.pyor.blend— what is needed to re-render the shot.hw/renders/sheet_<round>.png— contact sheets of variants compared side by side.
Gate
Before any render:
- The geometry validator passed on the exact assembly being rendered. Use the same pose: validate in the frozen device frame, then move the whole assembly rigidly for the shot.
- The report is newer than the
.blend.
scripts/studio.py enforces both. --allow-unvalidated exists only for material tests and scenes that are
not an assembly. Never use it to get past a failing assembly. Fix the geometry at the source instead (owner:
enclosure-engineer).
Before calling the presentation done, every shot must pass references/realism-checklist.md.
Workflow
- Plan the shots with
references/shot-list.md. Pick 3–6 shots that show what the brief promises: size in the hand or on the body, the main interaction, the materials, and the inside (exploded or close-up). Ask the user only about taste decisions that change the set, such as colorway, mood or background. Default to a dark product on a dark studio; it reads best (see the checklist). - Freeze the geometry. Copy the validated assembly to
hw/renders/base.blendand never edit its geometry there. Changes to look (materials, lights, camera) go into a script that opens the frozen file. If a fix and a regression start undoing each other, stop. Rebuild in the fixed order: assembly → fit → solder → validate → freeze. Do not patch in a loop. - Materials:
scripts/materials.py(reference:references/materials.md). Map every object to a material kind with name globs:
Wear is on by default: fingerprints, smears, micro-scratches, and dust on up-facing faces. Clean surfaces look fake. Real scans (ambientCG CC0 sets) look better than the procedural fallback. Fetch them once, withblender -b base.blend --python ${CLAUDE_SKILL_DIR}/scripts/materials.py -- \ --assign "Enclosure*=plastic_black:wear=0.4" "Window*=plastic_clear:wear=0.6" \ "Strap*=silicone:color=0.02,0.02,0.022" --wear-textures <ambientCG folder> --save look.blendtoolchain-setup. - Solder (any shot that shows a board):
scripts/solder.py --pads pads.json --board main=<collection>. It simulates each fillet from the real pad, stencil and paste volume. Wrinkles and slight asymmetry are correct. Floating or blobby solder is not. Run it last in the build, before validation. The contact line sits--edge-inset(0.03 mm) inside the copper, so zero-margin masks do not clash. If the validator still reports solder × mask on one part, the footprint's pad and mask opening disagree: send that topcb-engineer, and solder the rest with--exclude <ref>.--onlyand--excludetake ref globs, so you can enable parts one by one. - Preview first. Render
--format preview --preset previewfor every shot, and compare variants (HDRI rotation, colorway, exposure, f-stop) withscripts/contact_sheet.py. Show the sheet. Only then render finals. - Final:
scripts/studio.pywith--format 4k-vertical|4k-horizontal --preset final|hero. Run finals on a GPU. If the user's computer is a laptop or has no strong GPU, use a cloud GPU (references/cloud-gpu.md), and pull each image as soon as it finishes. - Check each image against
references/realism-checklist.mdbefore showing it. Name the problems you see before the user does. If the user rejects an image, write down the reason as a rule for the next shots.
blender -b look.blend --python ${CLAUDE_SKILL_DIR}/scripts/studio.py -- --target "Product" --recipe dark-studio \
--view hero --lens 100 --fstop 8 --format 4k-vertical --preset final \
--emit "LED*=1,0.86,0.70:60" --validator-json hw/validation/assembly.json --out hw/renders/hero_dark.png
Recipes (scripts/studio.py --recipe)
| Recipe | Use | Key settings |
|---|---|---|
dark-studio | default hero, clear or dark products, LED on | world 0.012; one big soft key; 2 thin strips behind; weak top; AgX Base Contrast |
tabletop-hdri | "on the desk", lifestyle-neutral | studio HDRI for reflections, matte table, soft key; Khronos PBR Neutral |
white-seamless | catalog, spec sheets | curved backdrop, overhead softbox, fills; avoid white product on white |
hero-float | landing page hero | dark graphite wall with soft gradient, rim strips, optional glossy floor |
Details, light ratios and why each light is there: references/lighting-recipes.md.
Camera rules
- The scene's front is −Y.
--viewnames an azimuth and elevation around the product. The product faces the camera unless the shot is explicitly about the back (charging contacts, engraving). - Physical camera: 85–105 mm full-frame equivalent, which gives no wide-angle distortion on small objects. The
36 mm sensor side follows the long image side, so a vertical frame uses
sensor_fit=VERTICALwith sensor height 36. Leaving the 24 mm default crops the frame. - Depth of field is real but consistent. Small products need f/8–f/16 to stay sharp front to back. Anything at the same distance as a blurred object must be equally blurred, or the image reads as a composite.
- Focus is on the first surface the camera sees at the center, or on
--focus <object>(for example the LED).
Taste and pitfalls
- Never render before validating. A part poking through a wall gets noticed at once, and it costs more trust than any good render earns.
- Clear plastic is not glass. Use IOR ~1.49–1.59, a little volume absorption, an oily fingerprint film and micro-scratches. If it looks like a jewel, it is wrong.
- White products on white backgrounds turn into flat shapes. Use the dark colorway for hero shots and show white on dark or high-contrast scenes.
- Metal and glass look real only through what they reflect. Give them an HDRI or strip lights to reflect. A big softbox must not show as a white sheet across a screen or a window; use thin strips for edges.
- Cords, straps and fabric: use a real braided structure with fibers and lint (see the materials reference). A smooth tube looks fake at once.
- Hands and people: use a real rigged scan, fix its joints, and give the skin subsurface scattering. Do not let it go dark under studio light. If no good model is available, do not do a hand shot.
- Markings and labels are textures (laser marking, silkscreen, barcode). Use geometry only where it changes the silhouette or the reflections.
- Lights are invisible to the camera. Only the backdrop is seen. Caustics stay off, clamp indirect is 4, and blur glossy is 0.5. These stop fireflies without a visible loss.
- Animations: turn persistent data off, because it caused flicker every N frames. Render a low-res motion preview of every frame and watch it as a video before the final.
- Compositing into a user's photo is hard. Read
references/photo-compositing.mdand set expectations first. A clean studio shot beats a bad composite. - LED glow: use emission on the lens or phosphor plus a small point light just above it. Keep it subtle;
a lit LED should not light up the whole room.
studio.pyhides every light it did not create, so do one of these:- use
--emit; - tag your light with the custom property
hdt_keep_light = True; - make the glow an emissive mesh hidden from camera rays.
- use
- Offsets from a component: use
world_offset(obj, (dx, dy, dz)), which applies rotation only. KiCad and GLB component empties often carry a 1000× scale, andobj.matrix_world @ vputs the point metres away. - Targets:
--targettakes a collection, an object (with its children) or a glob. A glob that matches empties includes their children, and a glob can also match collection names (for a lineup). - Thin translucent parts over a dark cavity (membranes, TPU button caps, light windows) read dark with
a large subsurface scale. Use
MAT.get(kind, sss_mm=0.05)unless the part is lit from inside. - Exploded views:
- Gaps: about each part's plan diagonal × sin(camera elevation) plus its height, so no part covers the next one in the image.
- Layout: every part on one axis, in assembly order. Include every visible part (button caps, membranes, screws, gaskets).
- Check: look at the image for parts that overlap in 2D, not only in 3D.
- Engine: Cycles with OptiX. An A/B test found LuxCore no better for studio products and much slower
on a cold kernel cache (
references/cloud-gpu.md).
Scripts
| Script | What it does |
|---|---|
scripts/materials.py | PBR library (enclosure, metals, PCB parts, solder, LEDs, fabric, floors) with wear and per-part color variation; --list shows all kinds |
scripts/studio.py | recipes, camera, render settings, LED emission, the validation gate, sidecar JSON |
scripts/solder.py | Young–Laplace solder fillets from pads.json, conformed to the board surface; --only and --exclude per part, --edge-inset |
scripts/solder_geom.py | the pad rules of solder.py without Blender (wettable pads, inset, ref selection); tested by scripts/test_solder_geom.py |
scripts/kicad_pads.py | .kicad_pcb → pads.json: a thin wrapper around pcb-engineer's exporter (same format) |
scripts/contact_sheet.py | join previews into one sheet |
scripts/selftest.py | builds a test product and board, runs every recipe at thumbnail size; run it on a render machine (cloud GPU), not on a laptop that is also running the session |
All scripts run headless (blender -b … --python <script> -- <args>), print one summary line, and return a
non-zero code on failure. They work in scenes built in millimetres or in metres: sizes, light power and
texture scales follow the scene units.
References
references/realism-checklist.md— run it on every image before showing it.references/lighting-recipes.md— each recipe, light by light, and when to change it.references/shot-list.md— which shots tell the product story, with framing for each.references/materials.md— material values and the physics behind them, including solder.references/photo-compositing.md— placing the product into a real photo (camera match, shadow catcher, grain match).references/cloud-gpu.md— rendering on a cloud GPU, with speed and cost and the Cycles-versus-LuxCore note.
Prototype roadmap
Turn the design into a dated plan that a team can follow. Each stage has a deliverable and a gate. The plan shows the critical path and the date by which each long-lead part must be ordered. Write it to hw/roadmap.md.
Talk to the user in the user's language. Files are in English unless the user's project uses another language.
Inputs
| File | What you take from it |
|---|---|
hw/brief.md | launch target, quantities, markets, budget |
hw/state.json | stage reached so far, gates already passed |
hw/bom.csv | lead_time_wk, stock_snapshot, lifecycle; custom parts (cell, molded parts, flex) |
hw/power/ | whether the power budget is measured or only estimated |
hw/compliance.md | certification durations and blocking items ("Schedule hooks") |
hw/cost/ | tooling and NRE lead times, MOQs |
hw/doability/review.md | open risks that need an experiment before a commitment |
Outputs
hw/roadmap/stages.json: stages, dependencies, duration ranges, gates, milestones and long-lead items. The format is intemplates/stages.example.json.hw/roadmap/schedule.mdandhw/roadmap/timeline.svg: generated byscripts/roadmap.py.hw/roadmap.md: the plan, built fromtemplates/roadmap.md, including the bring-up log.hw/state.json: the current stage and the next gate.
Procedure
-
Place the project. Decide which stage it is in: idea, Stage 0, Stage 1, EVT-n, DVT, PVT or MP. Use what has actually been built and measured. Do not use how finished the CAD looks: a collision-free 3D model means the industrial design is frozen, not the engineering.
-
Write the stages JSON. Start from
templates/stages.example.json, and remove the stages the product does not need. For example, a product with a catalogue cell has no custom-cell stage.- For each stage, give a
[best, worst]duration in weeks, its dependencies (depends_on, optionallag_weeks, negative for overlap) and an exit gate. Take the gates fromreferences/stages.md. - Use real lead times from
hw/bom.csv, supplier quotes andhw/compliance.mdwhere you have them. Tag each duration as verified or estimate. - Add a
long_leadentry for every part whose lead time is 12 weeks or more, or whose stock is low, with the stage that first needs it. - Give each
long_leadentryqty_neededand, when you have it, today's distributor stock:"stock": {"on_hand": 9278, "source": "LCSC", "date": "YYYY-MM-DD"}. When the order-by date from the factory lead time has passed but the stock coversqty_needed, the item is buy now from stock, not late. With too little stock or no stock data, it stays LATE and shows the shortfall. - Dependencies go in
depends_on. The script rejects unknown stage keys, so a typo such asafterfails loudly instead of silently starting the stage at week 0.
- For each stage, give a
-
Generate:
python3 ${CLAUDE_SKILL_DIR}/scripts/roadmap.py --stages hw/roadmap/stages.json --md hw/roadmap/schedule.md --svg hw/roadmap/timeline.svgRead the critical path, the "LATE" rows and the "in stock: buy now" rows. Look at the SVG before you embed it: stage names wrap between words, and milestone labels take separate lanes so they never cover each other. Test the script with
python3 ${CLAUDE_SKILL_DIR}/scripts/test_roadmap.py. -
Check the order of commitments. No custom cell, mold or board revision may start before the measurement that sizes it. If the plan has one, move it, or write down why the risk is accepted (
hw/decisions.md).- The usual critical path: power measurement → cell decision → custom cell → UN 38.3 → certification → sale.
- The final mold also waits for the cell envelope.
-
Write
hw/roadmap.md. The answer comes first:- where the project is now;
- the first legal sale, best and worst case, and what drives it;
- what to order now;
- the next gate.
Then give the timeline, the per-stage plans, an empty bring-up log and the schedule risks.
-
During EVT and later, use
references/bringup-checklist.mdfor each new board and log the results. Usereferences/test-fixtures.mdto plan test access before routing, and fixtures before PVT. -
Hand off.
cost-and-sourcingtakes the NRE timing and the long-lead purchases.doability-reviewtakes the stage the project is in and the uncommitted measurements.product-presentationtakestimeline.svgand the answer-first block.
Gate
The roadmap stage passes when:
- every stage has a deliverable, a duration range with an evidence tag and an exit gate;
- the critical path is identified, and no custom part starts before the measurement that sizes it (or the accepted risk is logged);
- every long-lead part has an order-by date, and late items are reported to the user;
- the first-legal-sale date is a range (best to worst), not a single optimistic date.
Taste and pitfalls
- Measure first. The first engineering deliverable is often a measurement bench, not a PCB. Current measured on a dev kit with the real duty cycle sizes the battery, the memory and the enclosure.
- The 3D model freezes the industrial design, not the engineering. Expect 3–4 board revisions and 1–2 mold iterations before mass production. Do not call a design "final" before it has been powered, measured, dropped and certified.
- Quote ranges, never single dates. Teams that promise the best case to customers end up refunding pre-orders.
- Order long-lead parts at once. Order EVT and DVT quantities as soon as a part is chosen. Lead times of 16–26 weeks are normal for springs, drivers and connectors, and stock can vanish.
- Certification is on the path, not after it. In markets like Brazil, nothing with a radio can be sold before homologation, and that includes a small launch batch.
- Design test access before routing: test pads, an RF test strategy and a test mode in firmware.
- Bring-up closes with numbers. Every checklist line records a measured value and the instrument. "Seems fine" does not close a line.
- Keep the roadmap honest. When a gate fails, move the dates and tell the user. Do not shrink later stages to keep the launch date.
References
references/stages.md: what each stage builds, the questions it answers and its gate, plus the critical path, long-lead parts and the iterations to expect.references/bringup-checklist.md: step-by-step board bring-up, from before power to the system soak.references/test-fixtures.md: design for test and the production fixtures, with NRE ranges.templates/stages.example.json: an example plan for a fictional BLE fitness band.templates/roadmap.md: the output template.
Specs engineer
You decide what is inside the product: the architecture and one real part per function, with two alternatives each. You do not research every part in depth. electronics-researcher does that. You make the choices that the research then confirms or overturns.
Talk to the user in the user's language. Files are in English.
Inputs
hw/brief.md(fromproduct-discovery). Required. If it is missing, runproduct-discoveryfirst.hw/power/(frombattery-and-power), when it exists: battery volume and the current budget.hw/mech/(fromenclosure-engineer), when it exists: board outline, height available per zone.hw/decisions.md: earlier decisions. Do not reopen a logged decision without a new fact.
Outputs
hw/requirements.md: numbered requirements. Template:references/requirements-template.md.hw/architecture.md: Mermaid block diagram, rails table, bus table, pin budget, and the architecture comparison.hw/bom.csv: canonical BOM, columns exactly as in CONVENTIONS §5. Starter:templates/bom.example.csv.hw/power/rails.json: rail definitions used byscripts/bom_check.py. Starter:templates/rails.example.json. Ifbattery-and-powerowns this file already, add rails throughhw/state.jsonopen_questionsinstead.hw/decisions.md: one entry per architecture or part choice (D-NNN).
Method
Work in this order. Each step writes to a file, so the next step and the other skills can read it.
1. Requirements
Read the brief and write hw/requirements.md. Each requirement has an ID, a measurable target, a hard limit, a priority and its source in the brief.
- Convert experience language into numbers. "Lasts a working day" becomes
REQ-0xx: autonomy ≥ 12 h of continuous recording, target 16 h. "Fits in a pocket" becomes an envelope in mm. - Write the environment as requirements: sweat, rain, drops, temperature, UV, skin contact.
- Write the regulatory markets as requirements. They decide radios, battery shipping and labeling. See
compliance-planner. - Mark each requirement
must,shouldorcould. If twomusts conflict, for example size against autonomy, stop and ask the user which one gives. Show the numbers.
2. Functions
List the functions the hardware must perform: sense, compute, store, connect, power, charge, indicate, actuate, protect. List one row per function with its requirement IDs. A function with no requirement is scope creep. Ask before keeping it.
3. Candidate architectures
Sketch two or three architectures. Examples:
- single SoC versus SoC plus a radio companion;
- on-board storage versus streaming only;
- one board versus a main board plus a flex.
Pattern shapes and typical part families are in references/architecture-patterns.md. Compare the candidates in a table:
| Criterion | What to estimate |
|---|---|
| Area and height | silicon and passive area in mm², tallest part in mm |
| Power | average and peak current per mode, from datasheet typicals × 2 until measured |
| Cost | silicon at 1k units |
| Lifecycle and supply | in mass production, second source |
| SDK | maturity, drivers for every peripheral |
| Risk | the riskiest part and why |
| Certification | radios and markets |
Recommend one candidate, say why in two sentences, and log it in hw/decisions.md. Ask the user only when the choice changes what the product does, for example dropping Wi-Fi to reach the size. Otherwise decide and tell them.
4. Component per function
For each function, pick a primary part and two alternatives. Run every candidate through references/selection-checklist.md. The checklist is not optional: it covers the traps that kill designs late.
Fill hw/bom.csv:
mpnis the full orderable number, with the packaging suffix.size_max_mmcomes from the datasheet's maximum dimensions.supply_rail_vis the rail name fromrails.json.key_specsholdskey=valuetokens separated by;.scripts/bom_check.pyreads these:vdd=1.7-3.6,i2c=0x2C,bus=I2C0,vio=1.8.evidenceisassumptionuntilelectronics-researcherverifies the row.- Leave price columns empty rather than guessing. If you must estimate, tag the row
estimateand state the basis innotes.
Include the parts people forget:
- passives that set height or area (inductors, bulk capacitors, crystal);
- antenna and matching network;
- test points or a programming connector;
- ESD protection on every external contact;
- battery protection;
- connectors, springs and contacts;
- the LED window or light pipe, membranes and the label.
5. Rails, buses and pins
In hw/architecture.md:
- Rails table. For each rail, give the source, nominal voltage, tolerance, average and peak load, and every part on it. The rail must sit inside every part's supply range. One low-voltage part, such as a 1.8 V-only memory or mic, can force a rail, and that rail can exclude another part, such as an LED driver that needs at least 2.5 V.
- Peak path. Put the largest simultaneous peak (radio TX plus flash program plus LED) against the battery C-rate, the protection IC, the PMIC discharge limit and the regulator limits.
- Bus table. For each bus, list every device, its address, speed and voltage. Address conflicts and level mismatches show up here, and an address can change with the part's variant.
- Pin budget. List every signal against the SoC package's GPIO count and special functions (PDM, I2S, QSPI, ADC, NFC, wake). The smaller package of the same SoC often has fewer GPIO.
6. Check and hand off
-
Run the linter:
python3 ${CLAUDE_SKILL_DIR}/scripts/bom_check.py hw/bom.csv --rails hw/power/rails.jsonFix every error. Explain or fix every warning. The rail checks come from
battery-and-power'scheck_rails.py, imported bybom_check.py; both scripts give the same verdict. -
Ask
electronics-researcherfor a dossier per part (hw/parts/<MPN>.md), primaries first, the riskiest first. -
Send the battery, PMIC and power budget to
battery-and-power. -
Ask
doability-reviewto challenge the architecture before the PCB starts.
When research overturns a part, update the BOM row, log the decision, and rerun the linter.
Gate
The PCB and enclosure work starts only when all of these hold:
- Every
mustrequirement maps to at least one BOM row, or is marked infeasible with the user's agreement. bom_check.pyexits 0.- Every IC row has
evidence = verified, with its dossier inhw/parts/. - No primary part is "early sampling", "preview", NRND, EOL or special-order only, unless the user accepted it as a logged risk with a fallback part.
- The rails table and the peak path show margin. "It might work" is not margin.
- The pin budget fits the chosen package, with at least 2 spare GPIO.
Taste and pitfalls
These mistakes have been made on real projects:
- Assuming the mic port. A MEMS mic can be bottom-port, with the sound hole on the pad side, which needs a hole through the board. The design assumed top-port. The port direction decides the board hole, the gasket and the enclosure opening. Read it in the datasheet title and drawing.
- Truncated MPN. "BM23FR0.6-16DS" is a family, not an orderable part. The suffix sets height, plating and reel size. Distributors return the wrong part, or none, for a truncated number.
- Nominal heights. An LED listed at 0.25 mm can be 0.35 mm maximum. That 0.1 mm became a pocket in the enclosure. Stack-ups use maximums.
- Ignoring the rail. An RGB driver was planned on the 1.8 V rail, but it needs VCC of at least 2.5 V. Check
vddagainst the rail for every IC. - Over-sized parts for simple jobs. A 20-pin trackpad controller was chosen to sense one electrode. A single-channel touch controller is smaller, cheaper and has fewer lifecycle risks.
- Choosing from memory. Never place a part whose datasheet nobody has opened. Training memory gets packages, heights and lifecycle wrong. Mark such rows
assumptionand send them to research. - Lifecycle traps. "Active" at a distributor can be "early sampling" at the maker, and the smallest package of an SoC is often the last to reach mass production. Suffixes like "QN" can mean special order only.
- Silent peaks. Wi-Fi TX peaks of about 250–400 mA exceed small wearable PMICs, whose discharge limits are around 100–125 mA, and tiny cells. If a radio peak cannot be fed, drop the radio or change the power path.
- Stock-only planning. One distributor with 500 pieces is not a supply chain. A part with zero authorized stock and no date needs a fallback before layout.
- Cost blindness. A single part, such as a large NAND, can be most of the silicon cost. Show the top three cost drivers in the architecture comparison.
- Scope creep. Every extra sensor costs area, power, firmware and certification time. Keep only what a requirement needs.
References
references/requirements-template.md: structure ofhw/requirements.md, with examples. Read it at step 1.references/architecture-patterns.md: common product shapes and part families per function. Read it at step 3.references/selection-checklist.md: the per-part checklist. Read it at step 4, for every part.scripts/bom_check.py: BOM linter. Run--helpfor the options.templates/bom.example.csvandtemplates/rails.example.json: starter files for a fictional product.
Technical drawing
This skill turns a validated 3D assembly into drawings that a supplier can quote from. The output is vector linework: hidden lines are removed, every part has a numbered balloon, and the parts list has real dimensions. Talk to the user in their language. The drawings themselves use the language set in the config labels.
Inputs
- The assembly
.blendinhw/mech/, fromenclosure-engineer, after the geometry validator passed (hw/validation/). Do not draw an assembly that failed validation. Parts that intersect produce wrong linework and a wrong drawing. hw/bom.csvfor item names, part numbers, materials and quantities.hw/brief.mdfor the product name.hw/state.jsonfor the revision (EVT-0, DVT-1 …).
Outputs
hw/drawings/drawing.json: the config. Keep it in the project so the drawing can be regenerated after every design change.hw/drawings/<name>_blueprint.svg|pdf|png: the exploded view, blue theme.hw/drawings/<name>_print.svg|pdf|png: the exploded view, white theme for print and PDFs.hw/drawings/<name>_ortho_<theme>.svg|pdf|png: the orthographic views with overall dimensions. Themes come fromortho_themes, or fromthemeswhen it is not set.- One slide per drawing.
product-presentationturns every file stem inhw/drawings/into a slide. Keep one theme there, usually print. Put the other theme inhw/drawings/<theme>/, for examplehw/drawings/blue/. hw/drawings/<name>_items.json: the anchor, envelope and visibility of each item. Other skills reuse it, for exampleproduct-presentation.
Gate
The drawing is done when all of these hold:
- The script ends with
BLUEPRINT okand lists neitherITEMS WITHOUT GEOMETRYnorhidden in this view. - You have looked at the PNG and every check in "Review" passes.
- The BOM items match
hw/bom.csv: same items, same quantities.
Tools
Everything runs headless in Blender, with no UI. Tested with Blender 5.2, using only bpy, mathutils and numpy. If rsvg-convert is installed (librsvg, via toolchain-setup), the scripts also write PDF and PNG. Without it they write SVG only.
# exploded isometric + BOM (both themes)
blender -b hw/mech/assembly.blend --python-exit-code 1 --python ${CLAUDE_SKILL_DIR}/scripts/blueprint.py -- hw/drawings/drawing.json hw/drawings/product
# orthographic views with overall dimensions
blender -b hw/mech/assembly.blend --python-exit-code 1 --python ${CLAUDE_SKILL_DIR}/scripts/ortho_views.py -- hw/drawings/drawing.json hw/drawings/product
# self-test on a fictional assembly (builds it, draws it)
BLENDER=/path/to/blender ${CLAUDE_SKILL_DIR}/scripts/selftest.sh /tmp/td-selftest
scripts/drawing_core.py: the shared engine, covering mesh extraction, feature edges, ray visibility, sheets, title block and export.scripts/line_clean.py: the line-merge pass used byortho_views.py. It removes the short ticks and dots that two nearly coincident outlines leave at a seam. Configure it withline_clean:{"enabled", "tol_mm", "maxlen_mm"}, in paper mm. It is pure Python and tested byscripts/test_line_clean.py, which needs no Blender.ortho_include: the group names to draw in the orthographic views, for example only the exterior parts. All groups are drawn when it is not set.scripts/make_test_scene.py: builds the fictional sensor puck used by the self-test and bytemplates/blueprint.example.json.
On a large assembly with 1M+ triangles and thousands of parts, ray casting can take minutes. Run it on the machine that holds the assembly. A cloud box is worth it only when it already runs the renders.
Procedure
- Copy the template
templates/blueprint.example.jsontohw/drawings/drawing.jsonand edit it. Every rule lists in order and the first match wins:frame_object: the object whose local axes are the product axes, usually the top empty of the device. The drawing ignores how the device is posed for renders.root: draw only meshes under this object.skip_prefixes: solder, markings, labels, lights, cords and boolean cutters. They clutter the linework and are not parts.groups: what moves together in the explode, withoffset_mmalongexplode_axis. Use"fine": truefor PCB assemblies so that the parts are drawn with thin lines.items: BOM rows, asid,name,spec,qtyandmatch. Put specific rules first, such as a connector found through its ancestorJ1, and general rules after, such as "everything in the board collection".- A match rule takes
names(base names, without.001),prefixes,collections,ancestors, orall: true. envelopeper item:auto, the default: the whole item when qty is 1, else one unit "(each)";item;largest;all: list each distinct unit, for example the two halves of a connector pair;false.
view: azimuth 35° and elevation 24° is a good three-quarter view. Raise the elevation when the parts are flat.sheet: A4, A3, A2, LETTER or TABLOID.standard_scale: truesnaps to ISO 5455 scales.projection:third(US) orfirst(Europe and most of Asia). Ask the user which market the supplier is in if it is unknown.title: product, subtitle, revision,date: "auto", units, sheet.decimal: ","for markets that use a decimal comma.labels: translations of all fixed texts, such as "BILL OF MATERIALS" and "Item". Translate them all when the drawing goes to a non-English supplier.
- Choose explode offsets so that each group clears the next in the projected view, not only in 3D.
- Gap per flat part: about its plan diagonal × sin(view elevation), plus its height. For example, a 32 mm square part at 24° needs about 18 mm, not its thickness.
- A thin flex or film hidden behind a cover needs more spacing, or it disappears.
- Put every part on one axis, in assembly order, and include the small visible parts: button caps, membranes, screws and gaskets.
- Run
blueprint.pyand read its last line.ITEMS WITHOUT GEOMETRY [n]: a rule matched nothing. Fix the rule.hidden in this view [n]: no point of item n is visible, so its leader is dashed. Increase that group's offset, move the part to its own group, or change the view.
- Look at the PNG. Use the Read tool on the
_print.png, then do the review below. Fix the config and run again until it is clean. - Run
ortho_views.pyfor the overall-dimension sheet. Keephidden_lines: falsefor assemblies. Dashed internals clutter the sheet. Turn them on for single parts. - Check the numbers: the overall size in the title block against
hw/brief.mdandhw/requirements.md, and each envelope against the datasheet's maximum dimensions inhw/parts/. A mismatch is a design error. Report it. Do not edit it in the drawing. - Write the outputs to
hw/drawings/and record the drawing revision inhw/state.json.
Review (look at every sheet before you show it)
- Every part is visible and has exactly one balloon. The dots sit on the part they name.
- Leaders do not cross and do not pass over another dot. Balloons do not overlap.
- No text leaves its cell. Long specifications wrap inside the table, and the table ends above the title block.
- Nothing touches the frame. The drawing is centred in its area.
- Outlines are clean single lines. A hatched or doubled edge means a mesh with split vertices. The engine merges vertices by position, so if it persists, check for duplicated, overlapping geometry in the model.
- Envelopes are per unit, and the overall size matches the product.
- The scale shown is a standard scale, and the sheet size is right for it. Small products often read better on A4 or Letter at the same scale.
Taste and pitfalls
These are mistakes made and fixed while drawing a real wearable:
- Hatched board edges. Imported PCB meshes have split vertices at every face, so every edge looked like a boundary and the board edge became a comb of short strokes. Merge vertices by position before you classify edges. The engine does this.
- Hidden parts. A thin flex under the cover disappeared in the exploded view. The fix was more spacing between groups, not a different line style.
- Crossing leaders. Placing balloons in anchor order is not enough when two anchors are at nearly the same height. The engine places them in order with a minimum gap, then swaps slots while any two leaders cross or a leader runs over another dot.
- Summed envelopes. The BOM showed one item the size of all its instances added together. Envelopes are for one physical unit, and an assembly bought as one item, such as a PCBA, shows its whole envelope.
- Axis views lose outlines. In exact front, top and side views, many faces are seen edge-on. Treat edge-on faces as not front-facing when you detect silhouettes, or box outlines vanish.
- Draw from the frozen, validated assembly. Never draw a scene posed for a render (rotated, on a cord, with fibers). Set
frame_objectso that the product axes are used. - Title block overflow. Bold values are about 0.64 em per character, not 0.56. With the lower estimate, "32.0 × 32.0 × 10.0 mm" ran into the next cell. The engine now shrinks values with the higher factor. Use
title.overall_sizefor a shorter text. - Seam ticks in orthographic views. A shell rim and a lid rim with 1° draft are both partly visible and leave short ticks along the seam.
line_cleanremoves them. Check the seam at full resolution. - Do not decorate. One accent color for balloons and leaders, ink for the linework, and a grid only on the blueprint theme. The drawing is a document, not a render.
- Name parts the supplier understands. Use a material and process ("PC, optical grade, injection molded, SPI A2"), a full orderable part number, and a quantity per product. Never use an internal nickname.
References
references/drawing-standards.md: what an RFQ drawing must contain, line types (ISO 128), title block (ISO 7200), scales (ISO 5455), projection methods, general tolerances (ISO 2768), and balloon and parts-list conventions. Read it before the first drawing of a project, and when the user asks for a drawing "by the standard".templates/blueprint.example.json: the full config, with comments, for the fictional test assembly.
Toolchain setup
Installs the toolkit's software, checks it, and writes toolchain.json with every tool path. Other skills read that file instead of guessing paths.
Talk to the user in the user's language. Commands and file names stay as they are.
Inputs
- None required.
hw/in the current project, if it exists. Doctor then also writeshw/toolchain.json.
Outputs
~/.config/hardware-design-toolkit/toolchain.json. On Windows,%APPDATA%\hardware-design-toolkit\toolchain.json.XDG_CONFIG_HOMEis respected.hw/toolchain.jsonwhen the project has ahw/folder. This copy overrides the user-level one.
Gate
scripts/doctor.py exits with 0 and prints required: OK. Until then, no other skill runs a script that needs a missing tool.
Procedure
-
Check first. Run
python3 ${CLAUDE_SKILL_DIR}/scripts/doctor.pyfrom the project root. On Windows usepython. It takes about 5 s, because it starts Blender headless once to read its Python, modules and GPU. -
If
required: OK, stop. Tell the user, in one line, which optional tools are missing and what they would add. -
If something required is missing, ask before installing anything. Installing changes the user's system. Show the user:
- the list of what will be installed and why: one line per tool from the doctor table and
references/software.md; - the approximate download size: KiCad ~1.5 GB with libraries, Blender ~400 MB, JRE ~50 MB, Freerouting jar ~65 MB, scipy ~40 MB;
- that a password (sudo) may be asked;
- the dry run output of the installer (step 4).
Install only after the user says yes.
- the list of what will be installed and why: one line per tool from the doctor table and
-
Show the plan. Run the installer for the OS with
--dry-run(PowerShell:-DryRun):OS Command macOS bash ${CLAUDE_SKILL_DIR}/scripts/install_macos.sh --dry-run(needs Homebrew; if it is missing, the script points to https://brew.sh)Linux bash ${CLAUDE_SKILL_DIR}/scripts/install_linux.sh --dry-run(apt, dnf or pacman; add--flatpakto get the current KiCad and Blender from Flathub)Windows powershell -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/scripts/install_windows.ps1" -DryRun(winget) -
Install. Run the same command without the dry-run flag. Add flags only when the user wants them:
--with-optional: ffmpeg (turntable videos), ImageMagick, libheif (HEIC phone photos as references), KiKit (PCB panels, into KiCad's Python), FreeCAD (STEP viewer).--with-assets: the render wear textures (ambientCG CC0: Fingerprints009, Smear003, Scratches005, SurfaceImperfections015) and the studio HDRIstudio_small_09(Poly Haven CC0), into~/.local/share/hardware-design-toolkit/assets/(%LOCALAPPDATA%on Windows).product-renderreads them fromtc["assets"].--with-cloud: AWS CLI and Session Manager plugin, for rendering on a cloud GPU. Never install these unless the user plans to render in the cloud.--with-gpu(Linux, Windows): cupy for NVIDIA GPUs. It speeds up the free-space flood fill.
-
Verify. Run
scripts/doctor.pyagain. Report the table in a short form: ✓ for found, ✗ for required and missing, – for optional and missing. -
Fix what remains by hand. The common cases are in "Taste and pitfalls" below.
The installers are idempotent. Running them again skips what is installed and verifies the Freerouting checksum.
How other skills use toolchain.json
Read the project file first, then the user file:
import json, os, subprocess
def toolchain():
base = os.environ.get("APPDATA") if os.name == "nt" else \
os.environ.get("XDG_CONFIG_HOME", os.path.expanduser("~/.config"))
for p in ("hw/toolchain.json", os.path.join(base, "hardware-design-toolkit", "toolchain.json")):
if os.path.isfile(p):
return json.load(open(p))
raise SystemExit("toolchain.json not found: run the toolchain-setup skill (scripts/doctor.py)")
tc = toolchain()
subprocess.run(tc["cmd"]["kicad_cli"] + ["pcb", "drc", "board.kicad_pcb"]) # cmd is an argv list
- Use
tc["cmd"][id], an argv list, to run a tool. It also covers Flatpak installs, where the "path" isflatpak run …. - Use
tc["paths"][id]when a plain file path is needed, for example the Freerouting jar. - If a key is
null, the tool is missing. Tell the user to run this skill. Do not guess a path.
Schema ("schema": "hardware-design-toolkit/toolchain@1"):
{
"schema": "hardware-design-toolkit/toolchain@1",
"generated_at": "2026-01-01T12:00:00+00:00",
"os": "macos | linux | windows",
"arch": "arm64",
"ok": true,
"missing_required": [],
"paths": {"<id>": "/abs/path or null"},
"cmd": {"<id>": ["argv", "list"] },
"versions": {"<id>": "x.y.z or null"},
"blender_gpu": [{"type": "OPTIX | CUDA | METAL | HIP | ONEAPI", "devices": ["name"]}],
"assets": {"Fingerprints009": "/abs/.../textures/Fingerprints009", "studio_small_09": "/abs/.../hdri/studio_small_09_2k.exr"},
"tools": {"<id>": {"id": "", "found": true, "path": "", "cmd": [], "version": "", "required": true,
"ok": true, "note": "", "purpose": ""}}
}
Tool ids:
- Required:
kicad_cli,kicad_python(a Python that canimport pcbnew),blender,blender_python,blender_numpy,blender_scipy,java(17 or newer; the Java the Freerouting jar needs: 17 for 1.9.0, 25 for 2.5.0),freerouting_jar,python(3.10 or newer),cad_python(the build123d venv, Python 3.10–3.13),git,rsvg_convert,chrome(headless browser for the presentation layout check and PDF). - Optional:
blender_cupy,kikit,freecad,ffmpeg,imagemagick,heic_converter(sips on macOS),render_assets,gh,aws,session_manager_plugin.
Environment overrides, checked before the search: KICAD_CLI, KICAD_PYTHON, BLENDER, JAVA or JAVA_HOME, FREEROUTING_JAR, RSVG_CONVERT, CHROME, CAD_PYTHON, FREECAD.
Taste and pitfalls
- Never install without consent. Show the dry run first. Do not add
--with-cloud"just in case". - macOS
/usr/bin/javais a stub. It prints "Unable to locate a Java Runtime" even when Homebrew's OpenJDK is installed. Homebrew's OpenJDK is keg-only: it lives in/opt/homebrew/opt/openjdk/bin/javaand is not on PATH. Doctor checks that location. Scripts must usetc["cmd"]["java"], notjava. - KiCad's Python is not the system Python. On macOS and Windows,
pcbnewimports only in KiCad's bundled interpreter. On Linux it imports in the systempython3, from thekicadpackage. Run board scripts withtc["cmd"]["kicad_python"]. - Blender ignores the user's site-packages. Install modules with Blender's own Python. Use
--no-deps, so pip does not install a second numpy that shadows the bundled one and breaks the ABI. If the app bundle is read-only, the installers install into Blender's userscripts/modulesfolder, which Blender puts onsys.path. - Distribution packages lag. Ubuntu's own KiCad and Blender can be a major version behind. Use the KiCad PPA or
--flatpak. The toolkit needs KiCad 9 or newer, and Blender 4.2 LTS or newer; it is tested on KiCad 10 and Blender 5.2. - Pin Freerouting and verify it. The installers download 1.9.0 and check its SHA-256 (why 1.9.0:
references/software.md). To upgrade, changeFREEROUTING_VERSIONandFREEROUTING_SHA256together. The digest is listed on the GitHub release page. - No GPU listed in
blender_gpumeans Cycles renders on the CPU. That works, but slowly. For 4K or turntables, suggest a machine with an NVIDIA (OptiX) or Apple Silicon (Metal) GPU, or a cloud GPU (product-render). - build123d needs Python 3.10–3.13. It has no wheels for newer Pythons, so pip on the system Python 3.14+ fails to resolve it. The installers create a dedicated venv at
~/.local/share/hardware-design-toolkit/venv. They preferuv(uv venv -p 3.12 <venv> && uv pip install -p <venv>/bin/python build123d), which also downloads Python 3.12 when needed. Without uv they fall back topython3.12/python3.13 -m venv+ pip. Run CAD scripts withtc["cmd"]["cad_python"]. - Windows
rsvg-convertcomes from MSYS2 (C:\msys64\ucrt64\bin). Doctor finds it there, even when it is not on PATH.
References
references/software.md: every tool, its role in the toolkit, minimum version, license and official download page. Read it when you explain to the user what will be installed.
Sponsors
Details
- Marketplace
- ctresb/hardware-design-toolkit
- Category
- Community