kicad-boards15 KB
View saved version →
---
name: kicad-boards
description: Designs and changes KiCad projects as text (.kicad_sch schematics, .kicad_pcb boards, .kicad_pro settings, symbol and footprint libraries) and takes a device from an idea to a checked schematic and a routed, checked board ready for a factory's review, with what a beginner would not know to ask for. Use before editing any KiCad file, designing or reviewing a schematic or a board, choosing its parts or its layers, placing, routing or analysing it, advising on what a device needs, or preparing its files for manufacturing.
---
# KiCad boards
A board that works is made by checking, not by being sure. What goes wrong is rarely the file's syntax: it is a pin on the wrong net, a part without what its datasheet demands, a capacitor far from its pin, a board called ready that nobody checked, or a device that does what was asked and still cannot be lived with, because nobody thought about how its battery level is read. So the work goes through gates, in order, and a tool decides each one, not your confidence. Each gate is cheap next to the one after it: a wrong pin costs a line now and a board later.
The person watches the whole way. They see the schematic, then the board in 2D as it is placed and routed, then the finished thing in 3D, each when it is ready, with a sentence on what they are looking at (reference/view.md, "Show the work as it goes"). Many of them have never made a board: say things by what they will notice when they hold the device, and bring up what they did not know to ask for.
## The gates
Copy this list into your notes and tick it as you go. Do not start a step while the one before it fails.
```
- [ ] 1. DESIGN.md says what is being built: goal, who builds it and how, supplies, blocks
- [ ] 2. What it also needs that nobody asked for is decided: in, asked, or left out (reference/completeness.md)
- [ ] 3. Every part with more than two pins has its pin table from its datasheet (reference/parts.md)
- [ ] 4. The schematic is written from one description, and `check` (KiCad's electrical rules) is clean; the person has seen it (reference/schematic.md)
- [ ] 5. Layers are decided and set up: how many, what each carries, the widths and clearances as rules (reference/layers.md)
- [ ] 6. The board file holds the outline and the footprints with their nets; `check` says the board and the schematic connect the same pads
- [ ] 7. Placement: fixed parts first, then by how little distance each connection tolerates (reference/placement.md); `look` at it; the person sees it in 2D
- [ ] 8. `route` connects everything; what it could not is fixed by moving parts, not by forcing tracks
- [ ] 9. `check`: KiCad's design rules, nothing unconnected, still the schematic's connections
- [ ] 10. `analyze`: what it finds is fixed in the board (reference/analysis.md)
- [ ] 11. The review lists, read against the board, and "what it also needs" once more (reference/review.md)
- [ ] 12. The person is shown the finished board in 3D with a tour, and told what was verified, assumed and not checked
- [ ] 13. For a factory: its limits as rules, the files made and looked at (reference/manufacturing.md)
```
A small change to a board that exists (move a part, change a value) needs only the gates it touches: the schematic first when a connection or a part changes, the write's check, `route` if copper moved, `check`.
## 1. Write down what is being built: `DESIGN.md`
Before any part is chosen, write `DESIGN.md` in the project and keep it current. It is what the board is checked against, what the person reads to see whether you understood them, and what the next conversation (yours, or another agent's working beside you) reads first. Short and plain:
```markdown
# Goal
A 555 blinker on USB-C: one LED at about 2 Hz. 30 × 22 mm. Soldered by hand by a beginner.
# Supplies
| Rail | Volts | From | Load |
| +5V | 5.0 | J1 (USB-C, 5.1 kΩ on CC1 and CC2) | 5 mA |
# Blocks
Power in (J1, R1, R2) → timer (U1, R3, R4, C1, C2
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 14 — file references are metadata, not package contents.
pcbkit-boards6.13 KB
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** whPreview of the first 4,000 characters. Read full instructions →
setup1.59 KB
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
with them as plain KiCad projects kept in their PCBKit account. The agent writes the schematic and
the board, chooses real parts from PCBKit's library, routes the copper, checks the board with
KiCad's own rules, shows it live beside the conversation, and makes the files a factory needs.
A free account is needed; boards they already have in PCBKit are listed with `projects`.
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 `kicad-boards` skill: make the project, show it at once with `show`
so they watch it take shape (the schematic first, then the board), and lead them one step at a
time. Ask the two things that decide most (will they solder it themselves or have it assembled,
and what powers it), bring up what such a device needs that they did not mention, and say it in
their language and in plain words; no experience is needed.
If you are working in a folder on the person's computer that already holds a KiCad project, say
once that this plugin keeps boards in their PCBKit account, and that PCBKit's plugin for folders
(https://github.com/pcbkit-io/agent-plugin) works on those files where they are; then go on with
what they choose.
