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-toolkit

Run it inside Claude Code after adding the marketplace with /plugin marketplace add ctresb/hardware-design-toolkit.

Contents

Discovered from source

Skills 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-hi tokens), typ_current_ma, peak_current_ma.
  • hw/mech/: the battery pocket outline (SVG or polygon) and its height, when enclosure-engineer has one. Otherwise, the size limits from the requirements.
  • hw/parts/<MPN>.md: current figures with sources, from electronics-researcher.

Outputs

FileContent
hw/power/budget.input.jsonthe budget model: modes, duties, parts, rails, comparables, limits. Format: templates/power_budget.example.json
hw/power/budget.jsonresults from scripts/power_budget.py
hw/power/rails.jsonshared rail table, owned by this skill (schema below)
hw/power/battery.json, hw/power/battery.svgresults from scripts/battery_fit.py: outline, thickness, capacity range, top view
hw/power/power.mdthe 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_v holds the rail name (1V8). A part on several rails lists them as VSYS|1V8, matched in order to vdd, vdd2, and so on.
  • key_specs holds tokens such as vdd=1.7-3.6; vio=1.8; i2c=0x2C.
  • The budget input carries the same fields per rail, plus the regulator model (type direct|ldo|buck|boost, efficiency, iq_ma, off_modes). power_budget.py --rails-out writes the table.
  • scripts/check_rails.py hw/bom.csv hw/power/rails.json fails any part whose supply range does not contain its rail's full range. It is the toolkit's single rail implementation: specs-engineer's bom_check.py and electronics-researcher's bom_merge.py import it.

Workflow

  1. 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] in hw/decisions.md.
  2. 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.
  3. Add comparables. Find 2–3 shipped products in the same category that publish battery capacity and runtime. electronics-researcher can find them. Put them in comparables. Their average current (capacity × usable fraction / runtime) is the empirical case, and it often is 3–5× the bottom-up baseline.
  4. 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.
  5. 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 tell specs-engineer through hw/state.json → open_questions.
  6. Size the battery. Read references/battery-reality.md first.
    1. Look for catalog cells that fit the pocket (§6 of the reference).
    2. 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 L or --polygon file.json instead of --svg. --stepped allows one step (custom cells only). --chem pouch-hv selects a high-voltage cell.
      • Exit code 1 means the claimed capacity is above the realistic range.
    3. Show the user battery.svg. Plan the product on the low end of the capacity range until a vendor quotes it.
  7. 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.
  8. 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.
  9. Plan the measurement with references/measurement.md: instrument, firmware build, modes to capture, pass criteria. This plan is part of the gate.
  10. Write hw/power/power.md from templates/power.md. Add each decision to hw/decisions.md and each question for the user to hw/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.py passes.
  • 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 bare 70 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 against rails.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

PathFromUsed for
hw/release/release.jsonthis 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, .netpcb-engineerDRC/ERC = 0, routed board, pin map
hw/pcb/fab/<board>/ Gerber zip, BOM, CPLpcb-engineerfab and assembly files
hw/bom.csvspecs-engineer, electronics-researcherorderable MPNs, LCSC numbers, stock dates
hw/mech/cad/ STEP/STL, hw/mech/dfm.mdenclosure-engineerenclosure parts
hw/validation/assembly.jsonenclosure-engineerassembly passes, newer than the CAD
hw/drawings/technical-drawingthe 2D drawing PDF and exploded images
hw/power/battery-and-powerbattery spec, power-measurement thresholds
hw/cost/cost-and-sourcingcost and lead time per order step
hw/doability/doability-reviewthe 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

  1. Write hw/release/release.json. Copy templates/release.example.json, and set the revision (A, B…) and the target level (prototype or production). 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 from hw/cost/, and cite it.

  2. Write the documents that only this skill owns. Use the templates:

    • assembly-guide.md (templates/assembly-guide.md): numbered steps, exploded images from technical-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 from battery-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.

  3. 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-engineer did not export them, it builds the assembler BOM and CPL from the KiCad position file and hw/bom.csv, applying the rotation offsets in the config.
    • It writes the purchase carts with attrition, the pin map, ORDER.md, README.md and MANIFEST.json.
  4. 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.

  5. 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 in hw/release/<rev>/checks/pre-order.md.

  6. 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.py runs 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 of release.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

FileWhat you take from it
hw/brief.mdtarget markets, launch order, quantities, who the users are (children?), where the product is used
hw/architecture.mdradios, frequencies, TX power, internet connectivity, firmware updates
hw/bom.csvradio 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 in templates/traits.example.json).
  • hw/compliance/matrix.md: generated by scripts/compliance_matrix.py.
  • hw/compliance.md: the plan, built from templates/compliance.md.
  • Entries in hw/decisions.md for each design lever the user accepts.
  • Entries in hw/state.json → open_questions for items that other skills own. Examples: TX cap → firmware, battery door → enclosure-engineer, UN 38.3 in the cell contract → battery-and-power.

Procedure

  1. Collect the traits. Fill hw/compliance/traits.json from the inputs. Use the market codes US CA EU UK BR JP KR CN AU IN. List the radios as ble, bt_classic, wifi, nfc, gnss, lte, subghz, lora, zigbee, thread or uwb. Set product_category, for example item_finder or wearable: item finders trigger the unwanted-tracking (DULT) rule.

  2. Run the matrix:

    python3 ${CLAUDE_SKILL_DIR}/scripts/compliance_matrix.py --traits hw/compliance/traits.json --out hw/compliance/matrix.md --show-skipped
    

    Test 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 by id: a known id replaces the toolkit rule, "disabled": true removes it, and a new id is added. The matrix names every local change. Propose generic rules upstream to references/rules.json.
    • Battery chemistry: battery.chemistry can 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.
  3. 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.

  4. 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.

  5. Apply the design levers. For each lever in references/design-levers.md that 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.

  6. 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 for prototype-roadmap, what was verified, the RFQs to send and the open questions.

  7. Hand off.

    • cost-and-sourcing takes the certification NRE (low and high).
    • prototype-roadmap takes the schedule hooks.
    • doability-review takes 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.md holds 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-researcher fills 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 by compliance-planner; you read them and never re-estimate them).
  • hw/roadmap.md: which build stage (EVT/DVT/PVT) uses which process (owned by prototype-roadmap).

Outputs

  • hw/cost/manufacturing.json: the inputs of the cost model. Start from templates/manufacturing.example.json.
  • hw/cost/model.json, hw/cost/cost.md and hw/cost/cost.svg: written by scripts/cost_model.py. In cost.md the 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 against targets.unit_cost.
  • hw/cost/rfq.md: the quotes to request, built from templates/rfq.md.
  • hw/cost/sourcing.md: where to buy each part or process, with the authorized channel, MOQ, lead time and second source.

Procedure

  1. 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-researcher to fill them. Do not invent a price.
    • A part with no price stays in the model with a warning.
  2. 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 pcba block. 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.

  3. 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> or assumption.
  4. 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). See references/cost-reference.md.

  5. Run the model:

    python3 ${CLAUDE_SKILL_DIR}/scripts/cost_model.py --mfg hw/cost/manufacturing.json --out hw/cost --svg
    

    The 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.

  6. 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".

  7. Read the result like an engineer and write cost.md around the script's tables, outside the generated-block markers. Put the brief's unit-cost goals in targets.unit_cost, so each tier reads met, not proven or not 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.
  8. 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.

  9. 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

KindBehaves likeExamplesIn the model
Recurringpaid for every unitparts 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; freightrecurring, BOM, pcba variable
Per order (batch)paid on every production order, spread over that orderPCBA setup, stencil, feeder loading, fixtures, handling; molding run setup and color change; plating lot charge; prototype board lotper_order, pcba batch
One-time (NRE)paid once per design revisionmold 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 servicesnre
Yield lossa percentage on recurringscrapped and reworked units; cosmetic rejects on clear parts (10–30% early)yield_loss_pct
Landeda multiplier on recurring plus freightduties, import taxes, broker feeslanded

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.md under "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.json has an evidence tag.
  • cost.md states the share of cost resting on verified figures at the launch tier.
  • rfq.md covers 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_pct or 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:

FileRead when
references/cost-reference.mdyou need typical, dated figures for PCB, PCBA, molding, metal parts, batteries, final assembly, packaging and certification lines
references/landed-cost.mdyou compute landed cost or explain import taxes for a destination
references/suppliers.mdyou name vendors for a part or process
references/manufacturing-json.mdyou write or debug hw/cost/manufacturing.json
templates/rfq.mdyou write hw/cost/rfq.md
templates/manufacturing.example.json, templates/bom.example.csvyou 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.md
  • hw/bom.csv, hw/parts/*.md
  • hw/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.md
  • hw/doability/findings.json from 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 that build-package and product-presentation read: key overall, plus areas, blockers, fixes, build_package and prototype_checks. Generated by scripts/doability_score.py --json.
  • hw/doability/score.md and hw/doability/fixes.json, generated by the same script.
  • hw/doability/review.md, filled from templates/review.md. Do not name it report.md: some setups refuse to create files with that name.
  • Open questions for the user in hw/state.json under open_questions. Do not edit files that other skills own (CONVENTIONS.md §4). Owners apply the fixes.

Final verdict

VerdictMeaning
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 READYLists 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 never GO.

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 codeMeaningNext step
0READY TO BUILDProceed to the build
3Fixable findings remainRun the next fix round
2NOT READY, blockedAsk the user for the listed actions
1findings.json is malformedFix the input file

Fix loop (with hardware-engineer)

  1. Review round N. Run the method below and write findings.json with "round": N.
  2. 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
    
  3. Fix. If the exit code is 3, hardware-engineer gives each owner skill its part of fixes.json. Each owner applies the exact fix, re-runs its own checks (DRC/ERC, validator, power budget) and records what it changed.
  4. Re-review. Run round N+1, from scratch, on the changed files. Mark a finding fixed only after you have verified the change yourself. A fix can create new findings, so check for them.
  5. 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.

LevelMeansTypical evidence
conceptIdea, sketches, a first BOMbrief, block diagram
pre-EVTParts chosen; boards placed but not routed or not built; 3D model frozenKiCad placement, validated assembly, renders
EVTBoards built and powered; functions proven on the bench; enclosure prototypebring-up log, measured current, basic RF test
DVTDesign-intent parts: soft-tool enclosure, custom cell samples, pre-compliance passeddrop, IP and thermal tests; pre-scan reports
PVTProduction line, fixtures and yield; certifications grantedfirst 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)

  1. Inventory. List what exists in hw/. Write down each stated claim: size, runtime, capacity, price, IP rating, markets, launch date.

  2. 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.
  3. 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 hw
    

    Use 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.

  4. 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.

  5. 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.

  6. Walk the checklist. Go through references/checklist.md area by area, including §9 (build package) and §10 (verify on the prototype). Then go through every red flag in references/red-flags.md.

  7. Write findings. Each finding has:

    • a severity: critical, major, minor or info;
    • 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_fixable is false, also give blocker (its type) and action (the exact step for the user). If the finding can only be closed by measuring the built prototype, link it to a prototype check with prototype_check: "V-xxx". It then does not block READY TO BUILD (prototype).

  8. Build package. Set each item in build_package to true only when you have checked the file yourself.

  9. Score, as in fix-loop step 2.

  10. 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 is NOT-REVIEWED.
  • accepted: needs a decision field that names the entry in hw/decisions.md. Accept only what the user has decided.
  • Status: fixed and accepted findings do not block. info findings never block.
  • Open minor findings 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 major blocker of type measurement.
  • 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 in scripts/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 by specs-engineer. A part number may be partial or a placeholder.
  • hw/requirements.md and hw/architecture.md: the rail each part sits on, its size budget and its interfaces.
  • Existing hw/parts/*.md dossiers. Update them; do not start over.

Outputs

  • hw/parts/<MPN>.md: one dossier per part, from templates/part-dossier.md. Name the file by the full orderable MPN. Replace the characters / \ : * ? " < > | and spaces with _.
  • hw/bom.csv: the researcher columns, filled by scripts/bom_merge.py from the dossiers. Do not edit those cells by hand.
  • An entry in hw/state.json → open_questions for 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

  1. 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.
  2. 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's references/ paths. Tell it to record failed sources. Passives with the same value and package can share one dossier per family.

  3. Research each part. Use the order in references/sources.md:

    1. 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.md says what to extract and where it usually is.
    2. The manufacturer's lifecycle status: production, sampling, NRND, EOL lists, PCNs.
    3. Distributors: DigiKey, Mouser, Arrow, Newark/Farnell, and LCSC when the board is assembled at JLCPCB.
    4. Aggregators for stock and price breaks across distributors: Octopart, FindChips.
  4. 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.

  5. 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.
  6. 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.

  7. Merge.

    python3 ${CLAUDE_SKILL_DIR}/scripts/bom_merge.py --bom hw/bom.csv --parts hw/parts --report hw/parts/_merge-report.md
    

    Fix 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. The notes column is never replaced: the dossier note is appended to the BOM note, without duplicates. Test: python3 ${CLAUDE_SKILL_DIR}/scripts/test_bom_merge.py.

  8. 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.

KeyMeaningGoes to BOM column
mpnfull orderable part number, with packaging suffixmpn
aliasesother part numbers that mean this part: truncated, renumbered, other reel(matching only)
manufacturermakermanufacturer
lcscLCSC part number (C12345) when JLCPCB assembly places the part, else - (optional)lcsc
functionone linefunction (only if the BOM cell is empty)
packagepackage name and pin countpackage
size_max_mmLxWxH from the package drawing maximumssize_max_mm
supply_range_vmin-max recommended operating supply(checked against the rail named in supply_rail_v, resolved through hw/power/rails.json)
io_range_vmin-max I/O voltage, or -(dossier only)
typ_current_matypical current in the mode the product uses mosttyp_current_ma
peak_current_maworst-case peakpeak_current_ma
lifecyclethe manufacturer's status word: production, sampling, preview, nrnd, eol, obsoletelifecycle
lifecycle_distributorthe distributor's label, if it differs(dossier only; mismatch is warned)
key_specsthe 3–5 specs that made this part the choicekey_specs
distributorsname=url pairsdistributors
price_1 … price_10kUSD per unit at that quantity, best authorized sourceprice_*
lead_time_wkfactory lead time in weekslead_time_wk
stock_snapshot<qty> @ <distributor> <date>, best authorized source first, ; between sources: 4200 @ DigiKey 2026-11-08; 1800 @ Mouser 2026-11-08stock_snapshot
alternativesMPN (drop-in) or MPN (needs change: …)alternatives
evidenceverified, estimate or assumption, for the row as a whole (its weakest important field)evidence
source_dateISO date of the price and stock checksource_date
notesthe one risk that matters mostnotes

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, evidence and source_date;
  • bom_merge.py exits 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 -R7 vs -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-engineer with 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 CR2032 rather 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 testing bom_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.md and hw/bom.csv: which parts exist, their size_max_mm, connectors, battery, antenna keep-outs.
  • hw/pcb/: board outlines and 3D exports (GLB/VRML/STEP from pcb-engineer).
  • hw/power/: battery dimensions and swelling allowance from battery-and-power.

Outputs

  • hw/mech/enclosure.json: the enclosure spec (from templates/enclosure.example.json).
  • hw/mech/cad/: <name>_<part>.step, <name>_assembly.step, <name>_<part>.stl, <name>_assembly.glb, keep-out STEP/GLB, <name>_dfm.json and <name>_dfm.md.
  • hw/mech/build_assembly.py: the scripted Blender assembly (imports the CAD GLB and the PCB export), run with blender -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.json and assembly.txt: the validator report of the golden file.
  • Entries in hw/decisions.md for 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:

  1. cad_enclosure.py reports DFM PASS. Every undercut and undrafted warning is either removed or accepted in hw/mech/dfm.md, with the mechanism and cost it needs.
  2. validate_assembly.py passes on the golden file: 0 interpenetrations deeper than 0.02 mm, and no non-manifold or non-finite mesh.
  3. free_space.py reports no leak for every cavity that must be sealed.
  4. Every gap under 0.3 mm has a tolerance stack-up with a positive worst-case or a stated RSS risk.
  5. 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/)

ScriptWhat it does
scripts/cad_enclosure.pyJSON 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.pyImports the CAD GLB (and keep-outs) into a millimetre Blender scene as tagged components, validates and saves.
scripts/validate_assembly.pyInterpenetration and mesh-quality gate. Writes JSON + text, exits 1 on failure.
scripts/free_space.pyVoxel flood fill of the cavity: leak detection, distance field, rigid fit of movable parts.
scripts/enclosure_example.pyA 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 unit MILLIMETERS). One Blender unit is 1 mm.
  • One root EMPTY named Assembly. Each physical component is an EMPTY with the custom property hdt_component = True (the validator still reads the legacy name vh_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, Root and =>… 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.md and do the stack-up for every gap under 0.3 mm and every spring or contact working height.
  • Read references/dfm-injection-molding.md and 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.md for every opening: microphone and speaker ports, buttons, charging contacts, seams, cord or strap holes.
  • Read references/materials.md before 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

FileRead when
references/cad-pipeline.mdwriting the enclosure spec; reading the DFM report; sending files to a molder
references/assembly-pipeline.mdbefore writing or changing build_assembly.py; when fixes regress
references/free-space-and-flex.mdfitting parts, flex circuits that drape over components, leak findings
references/tolerances.mdany gap < 0.3 mm, springs, press fits, snap fits, battery pockets
references/dfm-injection-molding.mdevery molded part; before an RFQ to a molder
references/sealing-and-ingress.mdany opening, seam, port or IP requirement
references/materials.mdchoosing 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's CONVENTIONS.md §4), hw/state.json, and the final presentation in hw/presentation/.

Start

  1. Run toolchain-setup in check mode (doctor). Report what is missing. Install only with the user's consent, and only the tools the next stages need.
  2. Create hw/ and copy templates/state.json from this skill to hw/state.json.
  3. If hw/ already exists, read hw/state.json and resume from the first stage that is not done. Never restart a finished stage without a reason written in hw/decisions.md.
  4. 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]
#StageSkillGate to leave the stage
1Discoveryproduct-discoveryThe user approved hw/brief.md
2Architecture and partsspecs-engineerrequirements.md, architecture.md and draft bom.csv exist; bom_check.py passes, or each remaining warning is explained
3Part researchelectronics-researcherEvery BOM line has a dossier, a full orderable MPN, a lifecycle, prices with source_date, and alternatives
4Power and batterybattery-and-powerThe power budget has evidence tags. The battery is a cell a vendor can make. A measurement plan exists
5Paper reviewdoability-reviewNo open NO-GO. Each GO-WITH-CHANGES has an owner stage
6Enclosure and PCBenclosure-engineer, pcb-engineerThe 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
7Assembly validationenclosure-engineer (validator)0 interpenetrations and 0 broken meshes. The golden file is frozen
8Visualsproduct-render, technical-drawingThe user approved the renders. The blueprint has every BOM item
9Businesscost-and-sourcing, compliance-planner, prototype-roadmapCosts at 1/10/100/1k/10k with NRE separated; certifications per market; roadmap with a critical path
10Final review and fix loopdoability-review, then the owner skillsEvery 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
11Build packagebuild-packagerelease_check.py passes on hw/release/<rev>/
12Presentationproduct-presentationhw/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-review verdict (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's release_check.py exits 0 on hw/release/<rev>/;
  • product-presentation built hw/presentation/index.html with 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

  1. Ask what changes the product; decide the rest. Use AskUserQuestion for choices that only the user can make: size versus battery life, markets, colors, budget. Put the recommended option first. Log every decision in hw/decisions.md.
  2. 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.
  3. Evidence on every number (CONVENTIONS.md §6). When a stage reports a number without a tag, send it back.
  4. One owner per file. Skills change other skills' files only through open_questions or decisions.md.
  5. Validate before you show. Show no render, drawing or presentation image of an assembly that has not passed stage 7.
  6. 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.
  7. Freeze the golden state. After stage 7, geometry changes only through a new validated build. Appearance changes go on the frozen file.
  8. 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.
  9. 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.
  10. 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.md so 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

  1. Read hw/state.json, then hw/knowledge/LESSONS.md. Each lesson that applies to this stage is a rule.
  2. Search FACTS.md and EXPERIMENTS.md for 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 work is not repeated without a new hypothesis. Write the hypothesis down first.
  3. 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 work or inconclusive. 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 F to 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:

    1. stop;
    2. write an experiment entry for both changes;
    3. find the shared cause, usually the order of operations or two owners of one value;
    4. 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)

  1. Verify. Run the checks of the stage's skill, for example bom_check.py, the assembly validator or DRC. Write what was not verified.
  2. 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.
  3. Decisions. Add decisions to hw/decisions.md.
  4. State. Update hw/state.json: stage status, gate evidence, open questions.
  5. Report. Write hw/retros/YYYY-MM-DD-<stage>.md from templates/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.
  6. Check. Run scripts/notebook_check.py hw/. It must report no duplicate IDs, no fact without evidence, and no experiment without a verdict.
  7. 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.md at 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 with lifecycle active or new.
  • hw/parts/<MPN>.md: pinouts, land patterns, reference circuits, from electronics-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, from enclosure-engineer.
  • hw/state.json: the fab chosen in cost-and-sourcing, if any. Otherwise, design to the common rules in references/fab-capabilities.md.

Outputs

PathContent
hw/pcb/board.jsonthe 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.jsoncounts from every check, and the result line
hw/pcb/release-check.jsonthe ready-to-order gate result, with every missing item
hw/pcb/pcb.mdthe 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.

ScriptRuns withJob
build.py spec [--route] [--step] [--strict] [--release]system Pythonthe whole pipeline below, stops at the first failing gate
pins.py Lib:Symbol [--footprint Lib:Fp], --search, --search-footprintsystem Pythonpin names and pad numbers, to fill a part's pins
spec.py specsystem Pythonvalidate the spec
libgen.py, schgen.pysystem Pythonlibrary + pin/pad/net cross-check; schematic
pcbgen.pyKiCad Pythonboard, outline, legalized placement (real courtyard polygons), planes, keepouts, stack-up
route.py export | import | runKiCad 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 | netKiCad Pythonclose 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,texturessystem Pythonchecks and outputs
fabnotes.pysystem Pythonstackup.md (stack-up and impedance), order.md, panel-plan.json and KiKit panel.json
release_check.pysystem Pythonthe ready-to-order gate (below); exit 0 only when nothing is missing
outline.py, stepbox.pyeitheroutline 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

  1. 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 against references/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.
  2. 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".
  3. Write board.json.
    • Parts come from hw/bom.csv. Prefer KiCad standard symbols and footprints (Lib:Name); check them with pins.py.
    • If a part has no library footprint, generate one from the datasheet's recommended land pattern (not the package drawing), with a body of the datasheet's maximum dimensions. Cite the datasheet figure in the footprint description.
    • Name the pins as the datasheet does. Write every pin: a net, or null for a deliberate no-connect. Use nc_rest only 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 fixed the parts whose position the product decides: connectors, antenna, contacts, sensors under windows, LEDs under light pipes, mics over ports, battery tabs.
    • Add keepouts for everything the enclosure puts against the board (magnets, battery, screw bosses, ribs, mic ports), on the right side. Add exclusive areas for the RF corner and for touch electrodes.
  4. 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.
  5. 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.
  6. Feed the 3D model back. Send export/<board>.glb and export/pads.json to enclosure-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.
  7. 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.
  8. Make it orderable. In the spec:
    • fill lcsc (or mark consign) and mpn for every part;
    • set fab, panel and fiducials;
    • add impedance to the RF and high-speed net classes. Then run build.py --step --release on the machine with the routed board.
  9. Finish. Fix every item release_check.py lists until it exits 0. Then write hw/pcb/pcb.md (stack-up, fab, rules, images, revision) and update hw/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:

  1. 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.py and DRC --refill-zones both do it). DRC reports 0 unconnected items.
  2. 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.
  3. 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.
  4. Stack-up and impedance notes (stackup.md), with an impedance line for every controlled-impedance net class, and order notes (order.md).
  5. Assembly minimum size handled. Either the board meets the assembler's minimum (JLCPCB: 70 × 70 mm), or a panel is planned (panel in the spec: by the fab's service, or KiKit files generated).
  6. Fiducials. At least 2 per assembled side on the board, or 3 on the panel rails.
  7. Placement clean. No failed part and no fixed-part collision. The assembly validator in enclosure-engineer passes with this board's GLB.
  8. 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-cli loses 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 islands counts 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-run on headless Linux) routed a dense 28 mm 4-layer board further. kicad_env.py checks the Java a jar needs.

References

  • references/spec-format.md: every field of board.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.md and hw/decisions.md, if they exist (re-interview only what is missing or changed).

Outputs

  • hw/brief.md, from templates/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), plus hw/refs/README.md, which lists them with one line each.
  • hw/state.json: set stages.discovery = "done" after the gate. Add any unresolved items to open_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 preview when 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):

  1. 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.
  2. 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).
  3. Life. Battery-life target for each mode (in hours), standby, charging method, connectivity and phone pairing, offline storage, sensors, ingress target.
  4. 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.

SlideFileProducer
Cover, idea, use, key numbershw/brief.mdproduct-discovery
Renders, one per slidehw/renders/hero.png, desk.png, hand.png, dark.png, exploded.png, lineup.png (any other name follows, sorted by name), plus captions.jsonproduct-render
Blueprinthw/drawings/blueprint.svg (SVG preferred over PNG), plus captions.jsontechnical-drawing
What is insidehw/architecture.svg, or a Mermaid flowchart in hw/architecture.md (the builder draws it)specs-engineer
Componentshw/bom.csv (CONVENTIONS.md §5)specs-engineer, electronics-researcher
Battery lifehw/power/budget.json (output of power_budget.py -o)battery-and-power
Ready to build, open findingshw/doability/score.json (canonical verdict, key overall; output of doability_score.py --json) and hw/doability/findings.json (findings)doability-review
Build package checklisthw/release/<rev>/checks/release-check.json (output of release_check.py), latest releasebuild-package
Cost per unit, one-time costshw/cost/model.json (output of cost_model.py)cost-and-sourcing
Certificationshw/compliance/matrix.md (output of compliance_matrix.py), else hw/compliance.mdcompliance-planner
Roadmaphw/roadmap/schedule.md (output of roadmap.py --md), else hw/roadmap/timeline.svg, else hw/roadmap.mdprototype-roadmap
Next stepsthe "Must be measured or quoted" list in hw/doability/review.md, or next_steps in deck.jsondoability-review
Overrideshw/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 to hw/presentation/assets/.
  • hw/presentation/presentation.pdf with --pdf: one 1600 × 900 page per slide, printed by headless Chrome, Chromium or Edge.
  • hw/presentation/layout-check/: findings.json and screenshots of the slides that fail.

Gate

The deck is done when all of these are true:

  1. layout_check passes at 1440, 1280, 1024, 768 and 390 px, in light and dark. It finds no overflow, overlap, crowding, edge or spill. build_presentation.py runs it automatically when a browser is available and exits with code 4 on any finding.
  2. --check (the chart geometry check) reports no problem.
  3. You have looked at every screenshot yourself.
  4. 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

  1. Make sure the producing skills have run, then run the builder:

    python3 ${CLAUDE_SKILL_DIR}/scripts/build_presentation.py hw --check --pdf
    
  2. Read the summary line. missing inputs lists 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.

  3. Look at the screenshots. Run python3 ${CLAUDE_SKILL_DIR}/scripts/layout_check.py hw/presentation/index.html --shots all to 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.

  4. Order and trim with deck.json when the audience needs it. An investor deck can skip nre and compliance. A manufacturer deck keeps them.

  5. 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: #E8590C on light and #E8661C on 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, night or led gets a dark slide;
    • drawings sit on white.
  • 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: @page is 1600 × 900 px with one slide per page. The theme button and tooltips are hidden. Print uses the light theme unless --theme dark is set.

Files

  • scripts/build_presentation.py: the builder. It uses the standard library only. --help lists 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 by enclosure-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-engineer owns and writes it. For a board it did not build, scripts/kicad_pads.py calls 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>.py or .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:

  1. 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.
  2. 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

  1. 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).
  2. Freeze the geometry. Copy the validated assembly to hw/renders/base.blend and 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.
  3. Materials: scripts/materials.py (reference: references/materials.md). Map every object to a material kind with name globs:
    blender -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.blend
    
    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, with toolchain-setup.
  4. 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 to pcb-engineer, and solder the rest with --exclude <ref>. --only and --exclude take ref globs, so you can enable parts one by one.
  5. Preview first. Render --format preview --preset preview for every shot, and compare variants (HDRI rotation, colorway, exposure, f-stop) with scripts/contact_sheet.py. Show the sheet. Only then render finals.
  6. Final: scripts/studio.py with --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.
  7. Check each image against references/realism-checklist.md before 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)

RecipeUseKey settings
dark-studiodefault hero, clear or dark products, LED onworld 0.012; one big soft key; 2 thin strips behind; weak top; AgX Base Contrast
tabletop-hdri"on the desk", lifestyle-neutralstudio HDRI for reflections, matte table, soft key; Khronos PBR Neutral
white-seamlesscatalog, spec sheetscurved backdrop, overhead softbox, fills; avoid white product on white
hero-floatlanding page herodark 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. --view names 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=VERTICAL with 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.md and 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.py hides 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.
  • 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, and obj.matrix_world @ v puts the point metres away.
  • Targets: --target takes 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

ScriptWhat it does
scripts/materials.pyPBR library (enclosure, metals, PCB parts, solder, LEDs, fabric, floors) with wear and per-part color variation; --list shows all kinds
scripts/studio.pyrecipes, camera, render settings, LED emission, the validation gate, sidecar JSON
scripts/solder.pyYoung–Laplace solder fillets from pads.json, conformed to the board surface; --only and --exclude per part, --edge-inset
scripts/solder_geom.pythe 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.pyjoin previews into one sheet
scripts/selftest.pybuilds 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

FileWhat you take from it
hw/brief.mdlaunch target, quantities, markets, budget
hw/state.jsonstage reached so far, gates already passed
hw/bom.csvlead_time_wk, stock_snapshot, lifecycle; custom parts (cell, molded parts, flex)
hw/power/whether the power budget is measured or only estimated
hw/compliance.mdcertification durations and blocking items ("Schedule hooks")
hw/cost/tooling and NRE lead times, MOQs
hw/doability/review.mdopen 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 in templates/stages.example.json.
  • hw/roadmap/schedule.md and hw/roadmap/timeline.svg: generated by scripts/roadmap.py.
  • hw/roadmap.md: the plan, built from templates/roadmap.md, including the bring-up log.
  • hw/state.json: the current stage and the next gate.

Procedure

  1. 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.

  2. 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, optional lag_weeks, negative for overlap) and an exit gate. Take the gates from references/stages.md.
    • Use real lead times from hw/bom.csv, supplier quotes and hw/compliance.md where you have them. Tag each duration as verified or estimate.
    • Add a long_lead entry 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_lead entry qty_needed and, 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 covers qty_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 as after fails loudly instead of silently starting the stage at week 0.
  3. Generate:

    python3 ${CLAUDE_SKILL_DIR}/scripts/roadmap.py --stages hw/roadmap/stages.json --md hw/roadmap/schedule.md --svg hw/roadmap/timeline.svg
    

    Read 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.

  4. 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.
  5. 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.

  6. During EVT and later, use references/bringup-checklist.md for each new board and log the results. Use references/test-fixtures.md to plan test access before routing, and fixtures before PVT.

  7. Hand off.

    • cost-and-sourcing takes the NRE timing and the long-lead purchases.
    • doability-review takes the stage the project is in and the uncommitted measurements.
    • product-presentation takes timeline.svg and 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 (from product-discovery). Required. If it is missing, run product-discovery first.
  • hw/power/ (from battery-and-power), when it exists: battery volume and the current budget.
  • hw/mech/ (from enclosure-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 by scripts/bom_check.py. Starter: templates/rails.example.json. If battery-and-power owns this file already, add rails through hw/state.json open_questions instead.
  • 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, should or could. If two musts 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:

CriterionWhat to estimate
Area and heightsilicon and passive area in mm², tallest part in mm
Poweraverage and peak current per mode, from datasheet typicals × 2 until measured
Costsilicon at 1k units
Lifecycle and supplyin mass production, second source
SDKmaturity, drivers for every peripheral
Riskthe riskiest part and why
Certificationradios 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:

  • mpn is the full orderable number, with the packaging suffix.
  • size_max_mm comes from the datasheet's maximum dimensions.
  • supply_rail_v is the rail name from rails.json.
  • key_specs holds key=value tokens separated by ;. scripts/bom_check.py reads these: vdd=1.7-3.6, i2c=0x2C, bus=I2C0, vio=1.8.
  • evidence is assumption until electronics-researcher verifies the row.
  • Leave price columns empty rather than guessing. If you must estimate, tag the row estimate and state the basis in notes.

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

  1. Run the linter:

    python3 ${CLAUDE_SKILL_DIR}/scripts/bom_check.py hw/bom.csv --rails hw/power/rails.json
    

    Fix every error. Explain or fix every warning. The rail checks come from battery-and-power's check_rails.py, imported by bom_check.py; both scripts give the same verdict.

  2. Ask electronics-researcher for a dossier per part (hw/parts/<MPN>.md), primaries first, the riskiest first.

  3. Send the battery, PMIC and power budget to battery-and-power.

  4. Ask doability-review to 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 must requirement maps to at least one BOM row, or is marked infeasible with the user's agreement.
  • bom_check.py exits 0.
  • Every IC row has evidence = verified, with its dossier in hw/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 vdd against 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 assumption and 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 of hw/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 --help for the options.
  • templates/bom.example.csv and templates/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 .blend in hw/mech/, from enclosure-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.csv for item names, part numbers, materials and quantities.
  • hw/brief.md for the product name. hw/state.json for 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 from ortho_themes, or from themes when it is not set.
  • One slide per drawing. product-presentation turns every file stem in hw/drawings/ into a slide. Keep one theme there, usually print. Put the other theme in hw/drawings/<theme>/, for example hw/drawings/blue/.
  • hw/drawings/<name>_items.json: the anchor, envelope and visibility of each item. Other skills reuse it, for example product-presentation.

Gate

The drawing is done when all of these hold:

  1. The script ends with BLUEPRINT ok and lists neither ITEMS WITHOUT GEOMETRY nor hidden in this view.
  2. You have looked at the PNG and every check in "Review" passes.
  3. 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 by ortho_views.py. It removes the short ticks and dots that two nearly coincident outlines leave at a seam. Configure it with line_clean: {"enabled", "tol_mm", "maxlen_mm"}, in paper mm. It is pure Python and tested by scripts/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 by templates/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

  1. Copy the template templates/blueprint.example.json to hw/drawings/drawing.json and 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, with offset_mm along explode_axis. Use "fine": true for PCB assemblies so that the parts are drawn with thin lines.
    • items: BOM rows, as id, name, spec, qty and match. Put specific rules first, such as a connector found through its ancestor J1, and general rules after, such as "everything in the board collection".
    • A match rule takes names (base names, without .001), prefixes, collections, ancestors, or all: true.
    • envelope per 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: true snaps to ISO 5455 scales.
    • projection: third (US) or first (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.
  2. 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.
  3. Run blueprint.py and 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.
  4. 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.
  5. Run ortho_views.py for the overall-dimension sheet. Keep hidden_lines: false for assemblies. Dashed internals clutter the sheet. Turn them on for single parts.
  6. Check the numbers: the overall size in the title block against hw/brief.md and hw/requirements.md, and each envelope against the datasheet's maximum dimensions in hw/parts/. A mismatch is a design error. Report it. Do not edit it in the drawing.
  7. Write the outputs to hw/drawings/ and record the drawing revision in hw/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_object so 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_size for 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_clean removes 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 writes hw/toolchain.json.

Outputs

  • ~/.config/hardware-design-toolkit/toolchain.json. On Windows, %APPDATA%\hardware-design-toolkit\toolchain.json. XDG_CONFIG_HOME is respected.
  • hw/toolchain.json when the project has a hw/ 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

  1. Check first. Run python3 ${CLAUDE_SKILL_DIR}/scripts/doctor.py from the project root. On Windows use python. It takes about 5 s, because it starts Blender headless once to read its Python, modules and GPU.

  2. If required: OK, stop. Tell the user, in one line, which optional tools are missing and what they would add.

  3. 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.

  4. Show the plan. Run the installer for the OS with --dry-run (PowerShell: -DryRun):

    OSCommand
    macOSbash ${CLAUDE_SKILL_DIR}/scripts/install_macos.sh --dry-run (needs Homebrew; if it is missing, the script points to https://brew.sh)
    Linuxbash ${CLAUDE_SKILL_DIR}/scripts/install_linux.sh --dry-run (apt, dnf or pacman; add --flatpak to get the current KiCad and Blender from Flathub)
    Windowspowershell -ExecutionPolicy Bypass -File "${CLAUDE_SKILL_DIR}/scripts/install_windows.ps1" -DryRun (winget)
  5. 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 HDRI studio_small_09 (Poly Haven CC0), into ~/.local/share/hardware-design-toolkit/assets/ (%LOCALAPPDATA% on Windows). product-render reads them from tc["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.
  6. Verify. Run scripts/doctor.py again. Report the table in a short form: ✓ for found, ✗ for required and missing, – for optional and missing.

  7. 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" is flatpak 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 can import 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/java is 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/java and is not on PATH. Doctor checks that location. Scripts must use tc["cmd"]["java"], not java.
  • KiCad's Python is not the system Python. On macOS and Windows, pcbnew imports only in KiCad's bundled interpreter. On Linux it imports in the system python3, from the kicad package. Run board scripts with tc["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 user scripts/modules folder, which Blender puts on sys.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, change FREEROUTING_VERSION and FREEROUTING_SHA256 together. The digest is listed on the GitHub release page.
  • No GPU listed in blender_gpu means 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 prefer uv (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 to python3.12/python3.13 -m venv + pip. Run CAD scripts with tc["cmd"]["cad_python"].
  • Windows rsvg-convert comes 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