/sketchloop

name: sketchloop
description: 'Draw a hand-drawn-style diagram from a description and render it to an actual PNG: flowcharts, architecture, sequence/ER diagrams, graphs, mind maps, box-and-arrow layouts. Authors a D2 text file, renders it via a bundled script to a sketchy hand-drawn PNG offline (no browser), then reads the image back and fixes the diagram. Use when the user wants to draw, sketch, diagram, visualize, or "make a hand-drawn diagram" of something, or mentions D2 or a .d2 file.'
allowed-tools: Write, Edit, Bash, Read

sketchloop: hand-drawn diagrams, rendered offline

Turn a natural-language request into a real **hand-drawn-style image**. You author a [D2](https://d2lang.com) text file (terse, auto-laid-out, no coordinate math); a bundled script renders it to a sketchy PNG **with no browser, no Node, no network**. Then you do the thing that makes this skill different: **you look at the rendered PNG and fix your own diagram** in a short loop. Deliverables are the `.png`, the `.svg`, and the editable `.d2`.

Workflow

1. Design, then author a `.d2`

For anything beyond a few boxes, decide what the diagram should *argue* and pick a shape that mirrors it (a flow left-to-right, a fan-out for one-to-many, a cycle for a loop, a tree for a hierarchy), not a uniform grid of boxes. Then write a `.d2` file into a `sketches/` folder under the user's current directory (create it if missing), e.g. `sketches/<topic>.d2`. If the user names a location, or the work is already happening in a diagrams/docs directory, use that instead; don't nest a `sketches/` folder inside it.

Read **`reference/d2-cheatsheet.md`** for the syntax (shapes, connections, containers, styling, sequence/ER diagrams) and the offline gotchas. The essentials:

direction: right
user: User { shape: person }
api: API Gateway
db: Database { shape: cylinder }
user -> api: request
api -> db: query

**Shape the layout: aim for a balanced rectangle, never a thin strip.** A wide strip of tiny labels is the #1 failure; apply these rules to the `.d2` text as you write it (exact syntax + measurements: the cheatsheet's *Direction, layout & shape* section):

• **Target ~3:2; treat past ~3:1 (either way) as a defect.** `render.sh` prints the

rendered ratio and WARNs past 3:1. Believe it.

• **Cap one axis at ~5 nodes.** A chain or fan of more than ~5 boxes in a single line is

already a strip. **Flipping `direction` only rotates a strip; it does not fix it.**

• **Reshape a long flow in this order:** (1) **merge** stages so the spine is ≤5 boxes;

(2) wrap **peers** (no strict order) with `grid-columns`; (3) **split** a true sequence into multiple linked diagrams, each a clean ≤5 run. Don't `grid` a sequence (grid ignores edges, so ordered arrows zigzag), and don't set `direction` inside containers (ignored by dagre/elk; only the root `direction` and `grid` change the shape).

• **Direction by kind, never mixed.** `down` for hierarchies, trees, decision flows, C4,

README-embedded diagrams; `right` for pipelines and sequences. Pick **one** per diagram; route side-concerns (logging, metrics) perpendicular to the spine.

• **Keep it to 5-9 boxes** (ideal ~7). Past ~15 split into separate diagrams along

meaningful boundaries. If edges ÷ nodes > 3, it's a hairball: regroup.

• **dagre first, elk when lopsided.** If a branchy or container-heavy graph comes out

lopsided, switch to elk (`D2_LAYOUT=elk`). elk balances fan-outs; it does **not** wrap a chain; that's grid's job.

**Style:**

• **Uniform boxes, sized to the label.** Keep boxes a consistent size; let each size to a

short label. Never widen the canvas and let the text shrink to fit; that's what makes labels tiny.

• **Color = meaning, used sparingly.** Most shapes stay default/near-white; give a fill

(light fill + darker stroke) only to shapes that carry meaning: entry point, datastore, external system, error path. Show importance with color, not size (enlarge at most one focal node). Heavy solid fills bury the hand-drawn strokes.

• **Short labels.** 3-5 words. Long labels widen shapes, crowd the layout, and can clip.

Break with `\n` or shorten.

• **No emoji, no `icon:` URLs.** Emoji aren't in the hand font; icons need the network.

2. Render it

Run the bundled `render.sh` (it lives in this skill's directory, next to this file, and self-locates its font, so invoke it by path from anywhere). `<this-skill-dir>` is the directory containing this `SKILL.md`; use its absolute path:

bash "<this-skill-dir>/render.sh" sketches/<topic>.d2

It runs `d2 --sketch` → rewrites the font → rasterizes with `resvg`, writes `<topic>.svg` and `<topic>.png` next to the input, **prints the size + aspect ratio** to stderr (with a `WARN` past ~3:1), and **prints the PNG path** to stdout. (First time: if it reports `d2` or `resvg` missing, see [Requirements](#requirements).)

3. Look at the PNG

**Load the printed PNG into your context as an image**, using whatever your harness provides for viewing image files (in Claude Code that's the `Read` tool). This is the point of the skill: judge the rendered result, not the source text. Scan for:

• **Thin strip / tiny labels.** First, the number `render.sh` printed: past ~3:1 (or any

`WARN`) the layout is a strip and the text is shrunken. This is the most common defect; reshape per step 4. A legitimately wide diagram (sequence, wide ER) is the only exception.

• **Overlaps / collisions:** shapes touching, an edge label sitting on a box or another

label, arrows crossing through shapes.

• **Clipped text:** a label overflowing or cut off by its shape's edge (usually a label

too long for its box).

• **Wrong topology:** an arrow to the wrong shape, a missing connection, a backwards

direction, the wrong shape type.

• **Cramped / lopsided layout:** everything jammed in one corner, a fan spread too wide,

or a tangle of crossing edges that's hard to read.

• **Legibility:** anything you can't