Taste fits in a skill file. Checking it is the hard part.

Ask a coding agent for an architecture diagram and you can usually guess the result before it renders. Rounded boxes. A soft shadow under each one. Five pastel fills that mean nothing. One arrow cutting a diagonal across the middle.

The model knew what the system looked like. It had no idea what a good diagram looks like.

diagram-design, by Cathryn Lavery, is an agent skill built to close that gap. It was #4 on GitHub trending on Sunday, with 1,083 stars that day and 50,933 in total when I checked. MIT license. It draws 44 diagram types as a single HTML file with inline SVG, can redraw Mermaid, draw.io and Excalidraw sources, and has an onboarding step that pulls the palette and fonts from your own site.

I did not install it, since installing a skill writes agent config. I cloned the repo into a scratch folder, read the rules, opened the output, and ran the scripts it ships. The interesting part is the gap between the rules and the scripts.

It is mostly prose

Here is what is in the skill folder:

• SKILL.md: 30.5 KB. CI holds it under a 40,000 byte cap, because it loads on every invocation (the reasoning is in the repo's ADR 0004).
• references/: 62 Markdown files, about 710 KB together. One per diagram type, plus the style guide, the import procedures, and the exact SVG markup for nodes, arrows and labels.
• assets/: 204 example diagrams and the templates.
• scripts/: five small Python files, standard library only.

So this is a style guide with a few tools attached. The rules read like an editor's notes. Above nine nodes, split the diagram. The accent color goes on one or two elements, never more. No shadows. Every connector is a right-angle elbow, never a diagonal. Structural geometry sits on a 4px grid. Don't copy Mermaid's automatic layout. The line that sets the tone is the first one in its philosophy section: "The highest-quality move is usually deletion."

The README's origin story is short: Claude kept getting the content right and the look wrong, so she turned her design preferences into rules. One user filed an issue (#242) saying they had copied the rules, not the code, into their own figure skills. Lavery's reply: "Using the rules rather than the code is exactly how they are meant to travel."

The output is boring HTML, on purpose

I opened the shipped flowchart example. It is titled "Should you write this as a skill?" and weighs 9,395 bytes. No script tag. One outside request, the Google Fonts stylesheet. The SVG carries role="img" with a real <title> and <desc>, so a screen reader gets a sentence instead of nothing.

Then I wrote a short Node script to survey all 204 examples. The only outside host in any of them is fonts.googleapis.com. Ten contain a script, and all ten are the animated variants. The median file is 12.6 KB; the largest is an animated exploded keyboard at 208 KB.

The bundled export_svg.py turned it into an 8,703 byte standalone SVG, its ids prefixed so it can sit on a page beside other diagrams.

I ran the import half

The import scripts parse text; they never render or fetch anything. I ran the Mermaid one against the repo's own sample, from outside the clone with python3 -I:

$ python3 -I scripts/mermaid_extract.py sample-flowchart.mmd
- nodes: 9 total / 7 drawable / 2 containers, depth 1
- edges: 7 (4 labeled, 0 dangling), cycle: True
- budget: nodes ok (max 9), edges ok (max 12)
- hubs (focal candidates): API Gateway(6), Token valid?(3), ...

That digest is the model's input for the redraw. It already applies the rules: it checks the budget, nominates focal candidates for the accent color, and flags the one note nothing connects to. The repo's adversarial sample hides IGNORE ALL PREVIOUS INSTRUCTIONS inside a node label. The extractor kept it as escaped text and discarded the four style directives and the click handler.

One limit showed up fast. A three-line Mermaid pie chart exits with code 2: the importer reads flowchart, sequence, state and ER diagrams only. Its source lists Gantt, timeline, journey, Sankey and quadrant charts as refused too, even though the skill can draw all five of those types from scratch.

Then I tried to make it fail

The skill ships a checker, self_check.py, that the agent is told to run on its own output. So I gave it some slop. I copied the flowchart example and broke three of the headline rules: the accent color on all seven nodes, a drop shadow under six of them, and one diagonal arrow.

$ python3 -I scripts/self_check.py sloppy.html
OK sloppy.html

$ python3 -I repo/scripts/verify-geometry.py sloppy.html
sloppy.html:96: connector <line 560,410 -> 740,264> has a diagonal
segment ... route it as a rounded right-angle elbow

The shipped checker passed it. The repo's geometry verifier caught the diagonal, but it sits outside the skill folder that npx skills add installs, and SKILL.md only points to it from a repository checkout. The palette lint said nothing, since every color I used was on the palette. No script in the repo looks for shadows. Several chart verifiers (heatmap, waterfall, bubble and more) do cap the accent at one mark, so the rule is checkable. Nothing generic counts it for a flowchart, and those verifiers sit outside the skill folder too.

In fairness, self_check.py does what its docstring promises. When I added a remote image and deleted the <title>, it failed with five findings. It is a safety and accessibility gate, not a taste gate.

Even the examples drift. In issue #276, a user found that this same flowchart example broke its own type reference: ovals at radius 24 instead of 20, and YES labels sitting on the connector instead of beside it. The geometry verifier passed it then. It is fixed now; the file I opened has radius 20 and the labels moved off the line. But if the author's own reference file can drift, a model's fresh output certainly can.

Two kinds of rules

This is the part worth keeping, even if you never draw a diagram.

Some rules a script can check: the palette, the fonts, no outside assets, accessible names, no diagonal connectors, the grid. Others only judgment can apply: which node to delete, which one or two things earn the accent, whether a paragraph would beat the drawing. The second kind is why this skill's output looks good. It is also the kind nothing verifies.

The README is upfront about this. It says output quality depends on the model, and that the same prompt can lay out differently twice. A skill is instructions. It raises the floor exactly as far as the model reads and follows them.

So if you are writing a skill for your team (slide style, email tone, diagram rules), sort every rule into those two piles. Every rule a script can check should become a script, and it should ship inside the skill, where the agent can run it. My own inspection script counted accent strokes and shadow filters in 27 lines of Node. Its shadow count alone (none in the original, one filter in mine) would have failed my sloppy file.

What I did not test

I never asked a model to draw anything with it. That is the honest hole in this post: I can tell you what the rules say and what the checkers catch, but not how often an agent actually follows them.

A few more edges from the issues and docs:

• The first-run gate pauses. With the default style guide, the skill stops to ask about your brand. Issue #262 describes an unattended run that hit that question mid-job with no one there to answer it.
• Fonts come from Google by default. The checker's --offline flag fails any file that loads them, and the style guide has a system-font option.
• PNG export needs Playwright and Chromium. The SVG export is pure Python.

To look before you install, the gallery shows every type in its light, dark and editorial variants.

Which of your team's taste rules could become a check today, and which ones will only ever live in prose?