# Design Illustration > Turn a plan, design, proposal, spec, architecture, pipeline, or workflow into a hand-drawn whiteboard-style illustration that captures its SPIRIT — and actually render it to a PNG via the `agy` CLI. Use this whenever the user wants a visual aid, diagram, sketch, or "draw this" for a proposal or design they're reviewing, says they are "having trouble following" a design, or asks to "illustrate / visualize / show me this as a picture." Especially proactive after Claude presents a substantial plan or multi-section design: offer to illustrate it. It not only authors the prompt, it produces the image file. Reach for it even when the user doesn't say the word "diagram" but clearly wants a design made legible visually. - Skill: `mdsweatt/design-illustration` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add mdsweatt/design-illustration` - Raw SKILL.md: https://api.skillmd.com/api/skills/mdsweatt/design-illustration/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Design & Media - Author: mdsweatt (https://skillmd.com/u/mdsweatt) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/mdsweatt/design-illustration --- # 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 bash /scripts/render.sh .png ``` It runs `agy` correctly so you don't have to remember the gotcha (see "The agy recipe" below). Pick `` 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: ```bash cd && agy -p "Generate an image and save it as .png in the current directory. The image: " \ --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 via `render.sh`) and viewed the PNG to confirm it's coherent.