Diagram Design: How the AI Diagram Skill Works

Ask Claude or Codex for a diagram and you almost always get the same thing back: a few rounded rectangles, some arrows, a default accent color, and a layout that looks nothing like the rest of your site. Diagram Design is an open-source AI skill built to fix exactly that — and it does it with a trick that has nothing to do with better prompting.

Here's how Diagram Design actually works: instead of asking the model to "make it look nice," it hands the model a hard numeric budget — a fixed cap on colors, nodes, arrows, and corner radius — and a checklist it has to pass before it's allowed to output anything. That one decision, a budget instead of a vibe, is the whole idea worth stealing here.

What Diagram Design actually is

Per its own GitHub "About" line, Diagram Design is "Editorial diagram design for Claude Code, Codex, GitHub Copilot, Cursor, Factory Droid, and Pi," continuing: "44 diagram types. Self-contained HTML + SVG. No shadows. No Mermaid slop." (The README itself gives a different count elsewhere — more on that discrepancy further down.) The README describes it more plainly: "An agent skill that draws diagrams as one self-contained HTML + SVG file, in your brand."

It's not a standalone app you download. It's a skill file that plugs into the AI coding tools people already use — Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Cline, Windsurf, and others, installed with one command: npx skills add cathrynlavery/diagram-design. Once it's installed, you don't open a diagram editor — you type something like "make me an architecture diagram of my app" into the agent you're already chatting with, and it writes out a single .html file with inline SVG, no build step, no JavaScript dependency.

It's free and ships under the MIT License, copyright line "Copyright (c) 2025 Cathryn Lavery." The maker, Cathryn Lavery, describes herself in her GitHub bio as "Founder @bestselfco ($55M+ bootstrapped). Sold to PE in 2022. Bought it back 2024. Becoming AI Native & documenting as I go!" — a self-reported figure, not an audited one, but it's the only context the repo itself gives for who built this.

The origin problem: the model understood the content, not the design

The README explains why the skill exists with a small, specific complaint. Lavery writes that for her own blog she'd want a diagram, and "I'd ask Claude and get back a generic rounded-box thing that looked nothing like the rest of the site." The line right after that complaint is the actual insight: "The model already understood the content." The model wasn't failing at comprehension — it understood the architecture, the flow, the steps she wanted to show. What it had no sense of was taste: how much to show, how much to leave out, where the one accent color should go.

That's the gap Diagram Design is built to close, and the README is explicit that it's a narrow one: "Diagram Design is for the diagram you are going to publish," not for every whiteboard sketch.

The mechanism: replace "make it nice" with a numeric budget

The actual rules live in skills/diagram-design/SKILL.md, a long instruction file the agent reads before it draws anything. Instead of a vague style guide, it sets hard numbers:

• A complexity budget, not a suggestion: per SKILL.md, every diagram is capped at nine nodes, twelve arrows, two coral accent elements, and two callouts.
• A grid, not freeform placement: "Structural geometry sits on a 4px grid," so nothing is positioned by eye.
• Connectors with one shape only: "Orthogonal only." Right-angle elbows exclusively — the file states flatly that "Diagonals fail."
• One color that means something: per SKILL.md, the accent "goes on 1–2 elements max," reserved for the one or two things in the diagram that actually matter.
• A hard ban on shadows: "Shadows are out. Borders are in." with a max corner radius of 6–10px, or none at all.
• A bias toward deletion: the README's own summary of the philosophy is "Every node earns its place."

None of that is stylistic advice phrased as "try to keep it clean." It's a set of pass/fail thresholds a model can actually check itself against — which is the transferable idea. Telling an LLM to "have good taste" produces inconsistent results because taste isn't an instruction, it's a judgment call made differently every time. A number is not a judgment call.

The "taste gate": a checklist before the model is allowed to ship

The skill doesn't just hand over the rules once and hope they stick — it makes the agent check its own work. SKILL.md defines a pre-output checklist, headed "Run before producing any diagram," plus a five-step build sequence for new diagrams: copy a template, load the type reference for whatever diagram type was chosen, fill in the placeholders, handle any requested motion, and only then run what the file calls the taste gate. Before any of that, section zero of the file requires the agent to confirm a project's brand style guide has actually been customized — if the defaults are still sitting there untouched, the agent is told to stop and ask the user how to customize it rather than silently shipping a generic-looking result anyway.

It also makes the agent narrate itself: before rendering, the agent has to "state the plan in one short message" — which visual type it picked and why — so the numeric rules aren't hidden inside a black box; you see the decision before you see the output.

It covers a lot of diagram types, and it imports from competitors

The skill isn't limited to flowcharts. Its README lists 45 visual types in its "What it makes" table — including architecture diagrams, sequence and state diagrams, an ER / data model diagram, timelines, a quadrant chart, a Sankey diagram, a Gantt chart, a Wardley map, and a UML class diagram — each rendered in three static variants: minimal light, minimal dark, and full-editorial. Per the same README, it also imports existing draw.io, Mermaid, and Excalidraw files and redraws them in its own style, exporting the result to SVG or PNG.

Worth flagging honestly: the project's own numbers don't agree with each other. The About blurb says 44 diagram types, the unreleased section of the CHANGELOG describes a gallery-numbering fix that lands on the same 44, while other text in the README still says 45. Both counts come from the same project, just caught mid-update — a small, almost funny confirmation that this is a genuinely live repo rather than a polished one-and-done release.

This is actively maintained, not a one-week trending spike

Diagram Design isn't a dead repo coasting on an old viral moment. At the time of writing it carries 52.6k stars and 3.3k forks, 17 open issues with titles as specific as "SVG export scopes CDATA markers into carried stylesheet selectors," and 29 open pull requests against 258 closed. The visible commit history shows 35 commits landing on October 10 and 12, 2026 alone, 15 of them tagged as automated "chore(release)" plugin-manifest version bumps and the rest human-authored fixes, features, and merges — a sign of a release pipeline that ships constantly rather than in big, rare drops. There's no tagged GitHub release yet; the Releases tab is empty, so the version number to trust is the one in the plugin manifests and CHANGELOG, not a release page.

What it doesn't solve

The project is upfront about its own limits in the README: output quality still depends on which model is running the skill, and the same prompt can produce a different layout on different runs — the rules constrain the result, they don't make it deterministic. The output also isn't an editable source format the way a Mermaid .mmd file is, so for a diagram that changes every sprint and lives in version control, the README itself concedes Mermaid is still the better tool. This is a skill for the diagram you're about to publish once, not the one you're going to keep editing forever.

What this generalizes to

The lesson here isn't "use a 4px grid." It's a pattern that applies anywhere you're asking a language model to produce something that's supposed to look designed: vague aesthetic instructions ("make it clean," "make it modern") produce inconsistent output because the model has nothing concrete to check itself against. A numeric budget — a cap on elements, a fixed grid, a single accent color, a pass/fail checklist run before the output ships — gives the model something it can actually verify, the same way a narrowly scoped GitHub-trending Claude Code skill earns trust by doing one job with explicit, checkable rules instead of a broad, vague mandate. If you're building anything where an AI agent has to produce a visual or structural artifact and you keep getting generic results back, the fix demonstrated here isn't a better prompt — it's a smaller, harder-edged rulebook, the same move Loop Habit Tracker's scoring formula makes when it replaces a vague "stay consistent" goal with a number you can actually compute.