diagram-design skill tested: the same clean diagrams, a consistent look, three times the cost

Summary

If you want diagrams that share one house style, the diagram-design skill delivers it. If you only need a correct diagram, plain Claude Code already draws one, faster and for a third of the price.

The reason is simple: we measured both. We asked Claude Code on Haiku for six diagrams, an architecture, a flowchart, a sequence, an ER model, a state machine and a timeline, twice each with and without diagram-design, then rendered all 24 in a browser and measured them:

• Both arms were clean. Every diagram rendered, contained every required label, and had no overlapping labels and no text past the canvas.
• The skill set the look. All 12 skill diagrams used its default palette (paper #f5f5f5, ink #2d3142, a coral accent #bf4520), and all 12 read some of its reference files first. None of the plain ones used that palette.
• It cost more and took longer. The 12 skill diagrams cost $0.169 against $0.054, 3.1 times as much, with a median of 62 seconds against 28.
• It broke “self-contained”. We asked for one self-contained HTML file. All 12 skill diagrams loaded fonts from Google Fonts; none of the plain ones loaded anything. Offline, those diagrams fall back to a system font, and online, opening one sends a request to Google.

Our picks

1. Use the skill for a series, not a one-off. Its value is that every diagram looks like the last one: same palette, same type, and, by its rules, an accent kept to one or two focal nodes. For one diagram in a pull request, plain Claude Code is enough.
2. Set your own style once. The skill’s first-run step asks whether to replace its default tokens with your brand. Answer it, or save a profile, so the diagrams match your docs instead of the skill’s defaults.
3. Strip or self-host the font links if the file must work offline. Remove the Google Fonts <link> or host the fonts with the file. The diagrams still render with a fallback font.
4. Budget for the reading. The skill ships 63 reference files and 220 assets; on each run Haiku read a few, which is where the extra tokens and the minute of waiting go.
5. Pick a skill by the format you need next. If the diagram has to be edited later in another tool, an Excalidraw, draw.io or Mermaid skill gives you a source file; diagram-design gives you HTML and SVG.

Who will look at your diagram: a reviewer who needs it correct today, or readers of a document set that should look like one product? The second is what this skill is for.

How we tested

1. The skill. cathrynlavery/diagram-design (MIT, 65,575 stars) at commit e57eda6: the whole skills/diagram-design folder, 290 files, copied into the project, so its references and assets were there to read.
2. Six diagrams with fixed content. Each prompt named the nodes, such as Browser, CDN, API Gateway, Auth Service, Orders Service, Postgres, Redis Cache and a Message Queue for the architecture. Every prompt asked for one self-contained HTML file with inline SVG, the default style and no questions, because the skill otherwise stops on first use to ask about branding.
3. Runs. Each diagram twice per arm, each a fresh claude -p session on Claude Code 2.1.314 with --model haiku. Only the Read tool was allowed; the skill’s scripts could not run.
4. Measuring. We opened each file in a browser and measured the largest SVG: every text element’s on-screen box, pairs of labels overlapping by more than 20% of the smaller one, labels extending more than 2 pixels past the canvas, and the required labels found in the page text. We checked the measurer on a hand-made diagram with one overlapping pair, one label past the edge and one missing label; it found exactly those.
5. Style. In each HTML file we looked for external URLs and for the skill’s three default color tokens.

Results

12 diagrams per arm

	No skill	diagram-design
Rendered	12	12
All required labels	12	12
Overlapping labels, total	0	0
Labels past the canvas, total	0	0
Uses the skill’s default palette	0	12
Loads Google Fonts	0	12
Read files before answering	1	12
Median text elements	18	24.5
Median HTML size	4.2 KB	8.7 KB
Median output tokens	6,016	14,019
Median time	28 s	62 s
Cost, 12 runs	$0.054	$0.169

The skill diagrams carry more text, a median of 24.5 elements against 18: captions, legends and notes in the editorial style. They used about as many colors as the plain ones, a median of 6.5 against 5.5; the difference is which colors, not how many.

On a trial run before the test, the skill answered in one turn without opening any reference and said so in its reply. In the test itself, every skill run opened files first. Expect the skill’s behavior to vary between runs on a small model.

Other diagram skills in our catalog, by output

Skill	Output	Repo stars, Nov 6	Gained in 8 days
archify	Checked standalone HTML	94,277	2,733
gstack diagram	Excalidraw, SVG, PNG	140,531	2,317
beautiful-mermaid	Mermaid to SVG, PNG	77,866	4,788
baoyu-diagram	Dark-themed SVG	27,364	294
drawio-skill	Editable draw.io	10,626	166
excalidraw-diagram	Excalidraw JSON	5,206	72
html-diagram	Self-contained HTML	4,040	243
mermaid-visualizer	Mermaid	3,678	9
c4-architecture	Mermaid C4	2,639	37

Star counts are for the whole repo, and several of these repos hold many skills besides the diagram one.

What to ignore

• Our clean scores as a ceiling. Six diagrams with eight or fewer nodes are easy to lay out. Dense diagrams are where overlap shows up, and where a design system may help more.
• Text element counts as quality. More captions are a style choice. The skill’s own advice is that the best move is usually deletion.
• Color counts. Both arms used five or six colors. What the skill changes is consistency across diagrams.

Limitations

• We scored layout, not taste. Whether the editorial style looks better is a judgment we did not make; the data has every file for you to look at.
• Haiku only, and no scripts. The skill ships PNG and SVG export and a self-check script; we allowed only reading, so those were not used.
• One browser, one viewport. Measurements come from one render at the browser’s default size.

Reproduce it

The scripts are diagram-design-skill-2026-11.py, which generates and scores the diagrams, and diagram-design-skill-2026-11-measure.mjs, which measures them in a browser. The data, diagram-design-skill-2026-11.json, has every run with its measurements, external URLs, tokens and cost, the calibration result, and the other diagram skills. All of them are in our skills directory.

Sources

1. cathrynlavery/diagram-design · official
2. tt-a1i/archify · official
3. Claude Code docs: Agent Skills · official
4. AgentCraft: Claude Code skills directory · blog