diagram-design: Turning AI Diagrams from a Joke into Deliverables with Claude Code
Have you ever asked an AI to draw an architecture diagram?
If so, you probably know this scene: you spend ages describing "microservices + data flow + permission layer," and Claude or GPT hands back a Mermaid diagram — rounded rectangles, gray arrows, unreadable font sizes. You show it to a designer and watch their mouth twitch. Then you open Figma, and 30 minutes later the diagram still isn't done.
cathrynlavery/diagram-design grew out of exactly this scene. It's a Claude Code skill with 27 diagram types, all delivered as self-contained HTML+SVG — no external dependencies, no JS, viewable by simply opening a browser. It earned 2951 stars in a single day. This is not another "awesome-xxx" list; it's a real pain point actually solved.
27 Diagram Types, Not 27 Templates
Here's the key distinction: most diagram tools give you "templates" — change the color, the text, the connectors; it's still fill-in-the-blank. diagram-design gives you "grammar" — each diagram type has structural rules, and the skill knows when to use a swimlane, a pyramid, or a flywheel.
The 27 types:
- Architecture: Components, Flowchart, Sequence, State machine, ER model
- Hierarchy: Tree, Org chart, Nested, Pyramid, Layer stack
- Positioning: Quadrant, Radar, Venn
- Process: Swimlane, Process, Timeline, Gantt
- Data: Bar, Line, Scatter, Medallion, Data flow
- Special: Loop (flywheel), IT current-state, Consultant 2×2, DP integration, DP security matrix
- While chatting with Claude you say "draw a microservices architecture," and Claude calls the skill itself, picks the diagram type, and generates the SVG
- No tool switching, no separate app, no copy-pasting
- Diagram generation becomes part of the conversation flow, not a standalone "output task"
- Pi:
pi install https://github.com/cathrynlavery/diagram-design - Claude Code:
/plugin marketplace add cathrynlavery/diagram-design - Codex:
npx skills add https://github.com/cathrynlavery/diagram-design - Claude Cowork: manually paste the URL
- +2951 stars today — #1 on GitHub Trending, far ahead of second place
- 27 diagram types × 3 variants = 81 deliverables
- 0 external dependencies — pure HTML+SVG, no JS, no build step
- 60-second brand adaptation — reads website CSS and maps automatically
- Supports 4 agent platforms — Pi, Claude Code, Codex, Claude Cowork
The most interesting is the Loop flywheel added in 2.0 — with a "shared memory hub" and dashed write-back lines. This isn't a traditional diagram; it's a modeling tool for dynamic systems.
Brand Adaptation: Claim Your Colors in 60 Seconds
This is what actually delivers the "editorial" feel.
You feed the skill a website URL. It reads your CSS, extracts primary and secondary colors plus fonts, then maps them onto every node, connector, and label across all 27 diagram types. Sixty seconds later, your architecture diagram speaks the same design language as your website.
This step kills the root cause of "AI diagrams looking AI-generated" — mismatched colors and fonts. The diagram itself isn't ugly; it's just inconsistent with its context. diagram-design automates that harmonization.
Why a Claude Code Skill, Not a Standalone Tool
This is the project's most thought-provoking design decision.
It's not a SaaS, not a Figma plugin, not a desktop app. It's an Agent Skill — installed into Claude Code, Codex, or Pi, invoked by the agent itself when needed.
What does that mean?
This is a new paradigm for tool design in the AI era: tools are no longer called by humans — they're called by agents. Skills are the agent's hands.
"The Highest-Quality Move Is Usually Deletion"
The author wrote something in the README worth remembering:
> The highest-quality move is usually deletion. Every node earns its place.
This is anti-Mermaid, anti-PowerPoint, anti-"more is better." Editorial quality comes from restraint — accent color reserved for the 1–2 elements readers should see first, target density of 4/10, and every node must "earn" its place.
This aligns perfectly with classic design principles: Dieter Rams' "less but better," John Maeda's *The Laws of Simplicity*, Edward Tufte's data-ink ratio. diagram-design encodes these principles into the skill's default behavior.
Three Variants: From Draft to Deliverable
Every diagram type ships in three versions:
1. Minimal Light: white background, black lines, one accent color 2. Minimal Dark: dark theme, suited for embedding in docs 3. Full Editorial: full brand colors, suited for blogs and presentations
So you can sketch a minimal version in conversation for quick discussion, then generate the full editorial version for publishing once finalized. One skill covers the entire path from draft to deliverable.
Installation Methods Expose the Ecosystem Landscape
diagram-design supports four platforms, each with its own install method:
These four platforms represent the current state of the "Agent Skill ecosystem" — no unified standard, each platform with its own package manager, but all compatible with the same skill file format. It looks a lot like the early days of npm/pip/gem going their own ways.
diagram-design's value isn't just "prettier diagrams" — it's one of the first reference implementations of a cross-platform agent skill. If you want to know "what plugins look like in the agent era," this is a living specimen.
The Numbers
A Deeper Observation
diagram-design going viral isn't just one tool succeeding — it marks the maturation of a new form: agent skills as standalone products.
Over the past two years, AI tooling has evolved through three generations:
1. Prompt templates (2023–2024): a well-written prompt, copy-paste to use 2. GPTs / Custom Agents (2024–2025): wrappers with system prompts and tool calling 3. Agent Skills (2025–2026): cross-platform, composable capability packages with their own workflows
diagram-design is a textbook example of the third generation — it's not "teaching AI to draw," it's "giving AI a diagramming workflow." The model handles understanding what you want; the skill handles delivering to editorial standards.
That division of labor is the right way to design tools for the AI era. Let the model be the poet, let the skill be the accountant — same principle as Euclid-MCP's "outsourced reasoning": leave strengths to the model, outsource weaknesses to specialized tools.
---
Repo: cathrynlavery/diagram-design
Language: HTML
Today's growth: +2951 stars
Install: /plugin marketplace add cathrynlavery/diagram-design (Claude Code)