mdsweatt Design Illustration
Make a dense plan or design legible at a glance. A reviewer absorbs "inputs flow through four stages, with a safety gate up front and a $-ceiling that can abort" far faster from a whiteboard sketch than from five sections of prose. This skill reads a design and produces a single hand-drawn-style image that conveys its spirit — as a visual aid for review.
It does the whole loop: distill → author the styled prompt → render the PNG via agy → show it.
It doesn't stop at authoring the prompt — it renders the finished image and shows it to you.
Workflow
1. Read and distill the design
Read the artifact to illustrate — usually a plan/design/spec Claude just produced, or a doc the user points to. Then ruthlessly distill to what fits legibly on a whiteboard. A good sketch shows a handful of load-bearing elements, not every detail. Look for:
| Element | What to extract |
|---|---|
| Main flow | The pipeline / stages / lifecycle, left → right (e.g. expand → assemble → run → record) |
| Key decision or comparison | The "X vs Y" or fork the design hinges on (cheap vs costly path, before vs after, baseline vs overshoot) — the house style loves a visible comparison |
| Guards / gates | The safety rails, preconditions, or abort conditions (a ceiling, a validation gate, a quarantine) |
| Inputs & outputs | The concrete objects at each end (a config file, a queue, a results bin) |
| Variants / branches | A small fan-out of the kinds/modes the design handles |
If the design is too big for one image, pick the spine — the one flow a reviewer most needs — and say so. Don't cram.
2. Author the prompt (whiteboard house style)
Adapt the Diagrammatic / Pipeline template below. The same visual grammar maps cleanly onto a software or architecture design: pipeline stages = boxes on a left→right conveyor; the key comparison = the "X vs Y" brackets or a fan of tickets; guards/gates = hand-drawn callout boxes; inputs/outputs = objects at the ends. Keep text minimal — the picture should carry the meaning.
The prompt has four parts:
- A. Scene — a left→right layout. Inputs on the left, the flow across the middle, outputs on the right. Label each stage with a short name.
- B. The hinge — make the design's key decision/comparison visible: a fan-out of labeled tickets, two brackets (expected vs actual), a gauge, a gate. This is what makes the sketch worth more than a box-and-arrow diagram.
- C. Callout boxes — 2–4 hand-drawn boxes on dotted lines, each a short bold title + one plain-language sentence. Color them by meaning (see palette).
- D. Style directive — always close with the block below.
Color semantics (keep to ~4, mapped to meaning, never decorative):
amber = warning / precondition, red = critical / overshoot / abort, blue = baseline / expected / flow, green = informational / success / captured.
Style directive (paste verbatim, adapt the color list to your callouts):
Style: casual whiteboard marker drawing. Black ink outlines, hand-drawn feel, slightly imperfect lines. Use just a few accent colors — [list the 3–4 you used, mapped to meaning]. Think "engineer explaining on a whiteboard," not polished infographic. Keep text minimal and legible.
3. Render the image via agy
Write the finished prompt to a temp file, then run the bundled script:
bash <skill-dir>/scripts/render.sh <output_dir> <name>.png <prompt_file>
It runs agy correctly so you don't have to remember the gotcha (see "The agy recipe" below).
Pick <output_dir> to suit the project — if the project has an images/diagrams scratch dir
(e.g. docs/diagrams/, ./diagrams/), use it; otherwise ask the user or default
to a sensible project path. Name the file after the design (e.g. ingest_pipeline_whiteboard.png).
4. Show it and offer to iterate
Read the PNG back to view it inline and confirm it's coherent (not blank/garbled). Show the user. Whiteboard renders are quick, so if the layout is cramped or a label is wrong, tweak the prompt and re-render rather than over-specifying up front. Offer a second variant if useful.
The agy recipe (and the one gotcha that will bite you)
agy generates and saves an image when asked agentically in print mode — but launched
non-interactively it blocks forever waiting on stdin. The fix is to close stdin with
< /dev/null. Without it you get a silent hang (no output, ~0% CPU) that --print-timeout does
not rescue. The bundled scripts/render.sh already does this. If you invoke agy directly:
cd <output_dir> && agy -p "Generate an image and save it as <name>.png in the current directory. The image: <PROMPT>" \
--dangerously-skip-permissions --print-timeout 7m < /dev/null
< /dev/null— essential; prevents the stdin hang.--dangerously-skip-permissions— so agy's file-write tool doesn't stall on a permission prompt.- Run from the output dir and tell agy the filename, so the PNG lands where you want. If it saves elsewhere, find it and move it.
- agy may print nothing until done; a render typically takes well under a few minutes.
Worked example (calibration)
A reviewer struggling with a 5-section data-ingestion pipeline design. Distilled spine: inputs (an incoming batch of raw files + a schema config) → a validation gate → a 4-stage conveyor (INGEST → VALIDATE → TRANSFORM → LOAD) → a clean data store; the hinge is one record fanning into three source formats (CSV / JSON / XML) with "same record, different format — one loader?"; guards are an amber schema gate and a red rate-limit gauge.
Create a whiteboard-sketch-style diagram showing a "data ingestion pipeline" as a left-to-right assembly line. Far left: an "Incoming Batch" file stack and a "Schema Config" card; an arrow through a "Schema Gate" turnstile into four connected boxes "1. INGEST", "2. VALIDATE", "3. TRANSFORM", "4. LOAD" joined by blue arrows. From INGEST, one record fans into three tickets "CSV / JSON / XML" with a note "same record, different format — one loader?". Above VALIDATE, three icons on dotted lines: "type check", "required fields", "dedupe". Callout boxes on dotted lines: (amber) "Schema Gate — reject anything that doesn't match the schema up front"; (red) "Rate Limit — 1000 rows/sec ceiling" as a gauge under LOAD with the needle in a red "throttle" zone; (green) "Clean Store — every loaded row, validated and typed", a bin catching row receipts with green checks and one amber "quarantined" reject. Style: casual whiteboard marker drawing. Black ink outlines, hand-drawn feel, slightly imperfect lines. Use just a few accent colors — amber for the gate/quarantine, red for the throttle zone, blue for flow arrows, green for the clean store. Think "engineer explaining on a whiteboard," not polished infographic. Keep text minimal and legible.
This produced a clean, legible sketch that mapped one-to-one onto the design's sections.
Quality checklist
- The scene reads left → right with clear inputs and outputs.
- The design's key decision/comparison is visible (a fan-out, brackets, a gauge) — not buried in text.
- Each callout box is a bold title + one plain sentence (not jargon, not a paragraph).
- Accent colors ≤ 4 and mapped to meaning (amber/red/blue/green), not decorative.
- The style directive is present and specifies the whiteboard sketch look.
- You distilled to the spine — the picture isn't trying to show every detail.
- You rendered with
< /dev/null(or viarender.sh) and viewed the PNG to confirm it's coherent.