Agent Skills: Circuit Diagram Generator

Circuit Diagram Generator

Generate consistent, classroom-friendly wiring diagrams as code so they are reproducible, version-controlled, and easy to tweak. Every diagram is a small Python program that uses schemdraw to emit a PNG and an SVG.

The goal is a picture a beginner can follow with their finger: power comes in at the top, ground sits at the bottom, and each wire is color-coded by what it carries. Prioritize readability over schematic formality.

When to use this

Use it for any request like "draw the circuit for the X kit", "make a wiring diagram", "show how the parts connect", "update the schematic", or "add a hookup figure to the kit page". It targets microcontroller + peripheral projects (Pico, NeoPixel strips/rings, buttons, encoders, potentiometers, sensors, battery packs), but the house style works for any small DC circuit.

Prerequisites

schemdraw must be importable. Check it, and stop to ask the user to install it if missing (don't silently pip-install):

python3 -c "import schemdraw; print(schemdraw.__version__)"   # expect 0.20+

Workflow

1. Get the pin map and the electrical details — don't guess

The diagram must match the code that will actually run. Read the kit's config.py and the lab/example source under src/kits/<kit>/ to learn:

• Which GPIO pin each part uses (e.g. NEOPIXEL_PIN = 0, ROTARY_ENCODER_PIN_A = 12). The shared config.py is the source of truth — prefer it over comments.
• How switches are wired electrically. If the code calls machine.Pin(..., Pin.PULL_UP), the button/encoder uses the Pico's internal pull-up, so its other leg goes straight to GND — no external resistor and no VCC pin. This is the common case in these kits. Only show a +/VCC pin and pull-up resistor if the code/hardware actually needs one (e.g. a KY-040 module with onboard resistors).
• Where power comes from. Power an addressable LED strip from VSYS so it runs on battery (~4.5 V from 3×AA) and on USB (~5 V). A battery pack feeds VSYS through the power switch.

If the pin map is genuinely unavailable, ask the user rather than inventing pins — a wrong pin number in a "helpful" diagram is worse than none.

2. Hold the house-style layout in mind

This layout is what makes the diagrams feel calm and legible. Follow it unless the user asks otherwise.

• White background.
• Red power rail across the TOP, black ground rail across the BOTTOM — this mirrors a breadboard's +/– rails and physical intuition (power up high, ground down low). It is the signature of the house style.
• Microcontroller as a light-blue block, center-left. Put signal/GPIO pins on its right (facing the peripherals) and power pins (VSYS, GND) on its left.
• Peripherals (LED strip, encoder, sensor, potentiometer) as light-fill blocks to the right, pins on their left facing the MCU. Align each peripheral's signal pin to its MCU GPIO pin (use the same pinspacing) so the wires are straight horizontal runs — slanted or jogging signal wires are the number-one thing that makes these diagrams look messy.
• Watch for the adjacent-pin overlap trap. If two multi-pin peripherals (say two potentiometers, or an encoder + a sensor) attach to GPIO pins that sit next to each other, aligning each block to its single pin forces the blocks to overlap vertically. The fix: give the MCU extra empty GPIO slots as spacers (e.g. lay out 7 slots and leave gaps) so consecutive peripherals land on rows far enough apart for their full height. Decide the vertical budget before placing blocks.
• Power input (battery pack + power switch) as a vertical column on the far left: it taps the top rail, runs down through the switch and battery, and its negative terminal drops into the bottom ground rail.
• Common ground: every ground returns to the single bottom rail. Place one Ground symbol on it.
• Color = meaning. Red = power, amber/orange = data & signal (including button lines), black = ground. Put a small wire-color legend in the top-left, above the power rail, and a title at the very top.
• Light pastel fills with dark text so pin names stay readable; give each component class its own hue.
• Dots mark real connections. Wires that merely cross with no dot read as not connected — lean on this instead of forcing every wire to avoid every other.

3. Write the generator script

Copy scripts/circuit_diagram_template.py to live next to the kit's source — the repo convention is src/kits/<kit>/circuit-diagram.py — and adapt the three marked sections: the component blocks, the signal wiring, and the power/ground wiring. The template already encodes the house style (rails, colors, legend, battery column, PNG+SVG export) and runs as-is so you have a working starting point.

Set OUT_DIR to the kit's docs image folder (docs/kits/<kit>/img/) so the figure lands where the page can reference it.

Keep each diagram a standalone script (no shared import) so it stays independently editable and copy-pasteable — matching how code is stored per-kit in this repo.

For the schemdraw API specifics you'll need while editing — the Ic/IcPin parameters, orthogonal Wire routing, the .linewidth() vs .lw() gotcha, labeling vertical elements, and white-background export — read references/schemdraw-cookbook.md.

4. Render, then LOOK at the result and iterate

Run the script, then Read the generated PNG and inspect it like a student would. This visual check is not optional — schemdraw places things exactly where you tell it, so the first render almost always has an overlap or a slanted wire to fix.

cd src/kits/<kit> && python3 circuit-diagram.py

Check for: blocks overlapping each other, pin labels colliding with the block title, signal wires that aren't perfectly horizontal, labels clipped at the canvas edge, and wires crossing through a block. Nudge coordinates, widen a block (edgepadW), or reroute, then re-render. Repeat until it's clean.

5. Embed it in the kit page

Reference the PNG from the kit's markdown with descriptive alt text, restate the color key in words, and list the connections. Pattern:

![Wiring diagram for the <kit> showing the Pico connected to ...](img/circuit-diagram.png)

Follow the colors: **red** wires carry *power*, **amber** wires carry *data
and button signals*, and **black** wires are *ground*.

- The strip's **DIN** (data-in) goes to **GP0**.
- ...

For student-facing pages, add a short "how to read it" note (a dot = connected; crossing wires without a dot are not) and follow CONTENT-GENERATION-GUIDE.md (reading level, and the Pixel mascot voice for tips). Teacher-facing pages use the professional register with no mascot.

Checklist before you call it done

• [ ] Pin numbers match config.py / the lab code exactly.
• [ ] Power rail is red and on top; ground rail is black and on the bottom.
• [ ] Signal wires are straight and amber; power is red; ground is black.
• [ ] Background is white (d.save(..., transparent=False)).
• [ ] Both circuit-diagram.png and circuit-diagram.svg were written.
• [ ] You actually opened the PNG and confirmed nothing overlaps or clips.
• [ ] The figure is embedded with alt text and a color key on the kit page.