PCBKit

View saved version →

---
name: pcbkit-boards
description: Design, change, check, route, share, order and export printed circuit boards (PCBs) with PCBKit, and write and simulate their firmware. Use when the person asks for a circuit board, a PCB, a device with a program (a game, a timer, a sensor display), a breakout or carrier board, or to change, move, label, route, check, analyse, share, order or export one for fabrication or KiCad.
---

# Circuit boards with PCBKit

PCBKit's tools write a board in PCBKit (a small board language with units), place and route it,
check it and export it. The person watches the board beside the conversation (in a terminal or an
IDE: on the live page `board.open` links to): every part, track and analysis appears there as you
work. Work so that what they see is a story: a first board within a minute, then one visible step
at a time, each told in a sentence.

## Tools

Seven areas — `help` (learn), `design` (write the source, build, check), `board` (the built board:
read it, change one thing, show it to the person), `parts`, `analysis`, `lab` (firmware),
`project` (export, share, order) — and `board.open`. `design.edit { path, edits }` here means the
tool `design` called with `{ op: "edit", why: "…", path, edits }`. **Every call says `why`**: one
sentence the person reads on their board while it runs, in their terms ("Putting the crystal
beside the MCU to keep its traces short"); what the call names (`id`, `ids`, `net`) lights up
there. A tool lists its ops and their required fields; `help { command: "board.move" }` gives one
op's whole input. `help { topic: "quickstart" }` has the practice every board follows (finish,
power, sensors, numbers, connectors, devices, ordering): read it before the first design.

## The loop

1. **Build at once, or ask once.** Before the first design, sort what the wish leaves open. A gap
   any sensible default fills is yours: build now and name the defaults in the answer. A figure the
   person left out of a part they named (a named motor's current, a sensor's accuracy, a cable's
   length) is such a gap. A wish that says only what a gadget does (a light that comes on in the
   dark, an electronic die, a plant that says when it is thirsty) is built at once: USB power, a
   common sensor, your MCU, each named. A gap that decides the board is the person's: what it
   drives or reads ("a motor controller" with no motor, "a few sensors" with none named), a supply
   it must live on (a robot's or a car's battery and its noise), how it talks and how far (no Wi-Fi
   out there: radio band, range, battery), how many inputs or outputs a tool for their work has
   (keys, channels, relays). A wrong guess there is a board to throw away, so do not build yet:
   answer with one short message, the three or four questions that change the design, each with the
   default you would take, and the trade-off that decides most of it in a sentence (a remote one:
   sleep current against battery life). Once they answer, build; a choice still open is a default
   you state. A part that misses one figure is the closest one, named in the answer; a chip the
   registry lacks is read from its datasheet in the same turn.
2. **Write the whole first design in one call:** `help { topic: "quickstart" }` (a complete board,
   every block and registry part), then `help.describe { ids: [...] }` for the blocks and
   `parts.use { ids: [...] }` for the chips you use (one call each; `parts.use` answers the
   design's text: no need to read it), then
   `design.write { path: ".pcbkit/design.pcbkit", text, build: true }`: blocks and parts joined by
   nets, no coordinates. `build: true` places, routes and checks in the same call.
3. **Open it:** `board.open` once per conversation, right after the first design; it follows every
   later change by itself, the person's included. Where the host draws no board (Codex, Claude
   Code), its answer is the live page's link: give it in your answer, once. Never call it again.
4. **Fix** wh

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: setup
description: Introduce PCBKit after it is installed and start the person's first circuit board.
---

# Getting started with PCBKit

Tell the person, in two or three sentences, what PCBKit does: it designs printed circuit
boards from a description — composes proven circuits, checks the electrical rules, places and
routes the copper — and exports fabrication files (Gerber, drill, BOM, placement) or a KiCad board.
No account is needed; signing in keeps their boards with their account.

Then ask what they want to build, offering three examples they can pick:

- an LED that blinks every 2 seconds (the classic first board);
- a breakout board for an I2C sensor with a Qwiic connector;
- a small ESP32 board with a button and a status LED.

When they answer, follow the `pcbkit-boards` skill: write a first design at once and show it, so
they see their board within a minute, then lead them one step at a time (`help { topic: "guide" }`).
Say it in their language and in plain words; no experience is needed.