Your Agent Draws Terrible Diagrams. This Skill Fixes That.

I asked Claude for an architecture diagram last month and got back something with drop shadows on every box. Three saturated colors. Rounded corners at whatever radius the model felt like that day. It was technically correct and I couldn’t put it anywhere near the blog.

That’s the current state of agent-generated diagrams. Fast, free, and stylistically homeless. You either fight with Figma for half an hour or you skip the diagram entirely, and most of us skip it.

cathrynlavery/diagram-design is one person’s answer to that. It’s a Claude Code skill — also works in Codex and Cowork — that ships an opinionated design system for 27 diagram types. The output is self-contained HTML with inline SVG and CSS. No build step, no JS, no external images. Open the file in a browser and it renders.

Why bother

The honest objection is that diagrams are documentation, documentation is overhead, and nobody got promoted for pretty boxes.

But sloppy visual hierarchy has a real cost in review. If the reader can’t tell at a glance which node matters, they spend their attention decoding your formatting instead of finding the race condition you missed. That attention budget is small and you’re wasting it on line weights.

The usual failure modes, in my experience:

• Default primary colors used to distinguish services, so every component shouts equally and nothing reads as important
• The same stroke for a gRPC call, a Kafka topic, and a VPC boundary
• A helper service rendered at the same visual weight as the primary datastore
• Freehand placement, so nothing lines up and the eye keeps snagging on it

None of these are aesthetic complaints. They’re all “the reader now has to guess.”

What the skill actually enforces

The design system is short enough to summarise, which is a good sign. One accent color, used on one or two focal nodes per diagram — the README is blunt that using it on five nodes destroys the signal. Three font families with fixed jobs: serif for titles and italic callouts, sans for node names, mono reserved for genuinely technical content like ports and field types rather than as a general “developer” vibe. Hairline 1px borders. No shadows. Border radius caps at 10px.

The rule I liked most: every coordinate, width and gap has to be divisible by 4. It’s presented as non-negotiable, and the claim is that this single constraint is what stops output from looking machine-generated. Whether or not you install anything, that one is free to steal.

There’s also a stated density target of around 4/10, with the idea that a diagram is done when nothing else can be removed. Most architecture diagrams I’ve drawn would fail that badly.

Type coverage goes well past boxes-and-arrows: sequence, state machine, ER, swimlane, quadrant, tree, org chart, Venn, layer stack, pyramid, radar, Gantt, bar/line/scatter, plus data-platform specifics like a medallion layout and a per-role security matrix. Everything ships in three variants — minimal light, minimal dark, and a full editorial version with summary cards.

The onboarding trick

Design systems usually die on adoption. This one has a shortcut that I think is the real idea in the repo.

You point it at your website. It fetches the homepage, pulls the dominant palette and font stack, and maps what it finds onto semantic tokens: paper, ink, muted, accent, link. Your body background becomes the canvas, your CTA color becomes the focal accent, your <h1> family becomes the title font. You get a diff to approve before anything is written.

Two things stop this being a party trick. First, it runs a WCAG AA contrast check on ink-over-paper before writing tokens, and if your brand color falls apart at 9–12px label sizes it proposes an adjustment and tells you why. Anyone who’s watched a beautiful mid-grey turn illegible at 10px will recognise the problem. Second, there’s a first-run gate: on a new project it checks whether the style guide is still at defaults and refuses to quietly ship generic-looking diagrams into a branded repo.

All 27 types read from one references/style-guide.md, using role names instead of hex values, so changes propagate everywhere at once.

Where it sits next to Mermaid

It isn’t really competing with Mermaid. The repo’s tagline says “no Mermaid-slop” and the split is clean:

The old framing was diagram-as-code versus canvas tools, trading maintainability against spatial control. An agent skill sidesteps that. The artifact is still text you can diff and grep, but the layout comes from a model following a written spec rather than from Dagre doing its best.

The catch is real, though: editing means regenerating. If your diagram changes weekly, keep it in Mermaid.

Getting it

Clone and symlink if you plan to customise the style guide by hand:

git clone git@github.com:cathrynlavery/diagram-design.git ~/code/diagram-design
ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design

Or just /plugin marketplace add cathrynlavery/diagram-design if you’re only kicking the tyres. The plugin route keeps everything in the plugin cache, so hand edits to the style guide get wiped on update.

Then you ask for things in plain language and it picks the type for you. Export to PNG or SVG is a separate explicit command, with SVG injecting Google Fonts so it opens standalone in Figma.

One structural note

Worth looking at even if you never install it: SKILL.md is a thin index, and the 34 reference files under references/ load only when relevant. Ask for a flowchart, the agent reads two files. Adding a new type is dropping in a markdown file and wiring one line into the selector.

That’s the difference between a skill that stays fast as it grows and one that slowly eats its own context window. I’ve since restructured two of my own skills the same way.

The README also has a section on when not to draw, which I appreciated more than I expected. The test it gives is whether a reader would learn more from the diagram than from a well-written paragraph. Half my old diagrams fail it.