Nearly 58,000 GitHub stars and a design rule that fits in one line: "the highest-quality move is usually deletion". diagram-design, by Cathryn Lavery, is an Agent Skill that turns a plain-language request ("make me an architecture diagram with frontend, backend, database and Redis") into a single HTML file with inline SVG. Between 20 August and 9 October 2026 it went from version 2.6.0 to 2.6.70, and the plugin is already at 2.6.110.
What it does: a design system written for the agent
The skill kicks in when you ask for a diagram and covers 45 types according to its README: architecture, sequence, state machine, ER model, database schema, deployment, dependency graph, swimlane, Gantt, Sankey and Wardley map, among others. What it adds is not the drawing, which the model can already do, but the judgement its SKILL.md enforces:
- Target density 4/10. Every node is a distinct idea and every line carries information; above 9 nodes, it is probably two diagrams.
- A single accent colour for one or two focal nodes, 1px hairlines, no shadows.
- Everything on a 4px grid, with a final checklist that covers overlapping labels and content outside the
viewBox. - Semantic patterns before shapes: when the point is a bottleneck, a trust boundary or a request lifecycle, the skill picks the pattern first and then the visual type that expresses it best.
The first time it runs in a project, the agent stops and asks whether you want to adapt the style guide to your brand (from a website, a local folder, pasted tokens or a saved profile) or keep the default palette. Profiles live in ~/.diagram-design/profiles/.
It also redraws existing diagrams: Python scripts extract nodes, edges and containers from draw.io, Mermaid or Excalidraw files, and the SKILL.md tells the agent to treat their labels as untrusted data, never as instructions.
How to install it
With the skills CLI, which works for Claude Code, Cursor, Codex, Copilot and other compatible agents:
npx skills add cathrynlavery/diagram-designIn Claude Code, the marketplace also adds the /export-diagram, /import-mermaid and /doctor commands:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-designClaude Code turns off auto-update for third-party marketplaces by default; the README explains how to switch it on from /plugin. After that, just ask for the diagram in plain language.
Risks and limits
The skill is mostly text: instructions, per-type references and HTML templates. What it runs are local Python scripts (self_check.py to validate the output, the import extractors and export_svg.py / export_png.py), and its privacy policy states it has no server, no accounts and no telemetry. The network shows up in three places:
- Google Fonts. Generated diagrams load their fonts from
fonts.googleapis.comwhen opened. For internal documentation there is a system-fonts option (--system-fontson SVG export). - Onboarding from a website. The agent fetches pages from the site you name, but the
SKILL.mdrequires it to warn you and wait for confirmation first. - PNG export. It needs Playwright and a browser; the skill does not install them on its own.
The key limitation is spelled out in the README itself: quality depends on the model, the same prompt can produce two different layouts, and the result is not an editable source format. There is no text to review in a diff.
Versus Mermaid and draw.io
| Mermaid | draw.io / Excalidraw | diagram-design | |
|---|---|---|---|
| How you make it | Writing text | Dragging shapes | Describing it to the agent |
| Layout | Automatic | Manual | Placed by the agent on a 4px grid |
| Output | Text GitHub renders | Editable file | HTML with inline SVG, exportable to SVG or PNG |
| Changing it later | Edit the text | Edit the canvas | Ask again or edit the SVG |
The README puts it honestly: for docs that live in Git and change every sprint, Mermaid is still the better fit. diagram-design is for the diagram you are going to publish: the one in a postmortem, an architecture proposal or a talk, where it has to read well the first time. The most useful part, in my view, is the importer: start from the Mermaid you already have in the repo and get a polished version for the document other people will read.