What is diagram-design? An MIT-licensed agent skill by Cathryn Lavery that makes Claude Code draw a diagram as one self-contained HTML file with inline SVG, in your brand colors. It picks one of 41 visual types, states its plan, and runs a checklist before writing the file. Use a Mermaid skill when the diagram must diff in a PR.
Disclosure: we run Skillselion, an independent catalog of agent skills and MCP servers, not affiliated with Anthropic, OpenAI or Cursor. We wrote a longer install and brand-setup walkthrough in our diagram-design guide for Claude Code. This post takes a narrower developer angle: what the skill tells the agent to do, step by step, and what lands on disk. The part that changes how the session feels is step 3: the agent tells you what it is about to draw before it draws it. Every quote below comes from cathrynlavery/diagram-design at commit cea465e, verified 28 September 2026.
How do you install diagram-design in Claude Code?
Two commands inside a Claude Code session, from the repo README:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
Source: README.md, Install, commit cea465e, verified 28 September 2026.
The README also says Claude Code disables auto-update for third-party marketplaces by default, so run /plugin, open Marketplaces, select diagram-design and enable auto-update once. The same skill folder works in Codex and other Agent Skills hosts. For how skill loading works in general, see the Skillselion walkthrough on installing a Claude skill.
Quick numbers, dated: the diagram-design skill listing shows about 4.6k installs (catalog data as of 10 September 2026), and the GitHub repo had 42,618 stars on 28 September 2026 (GitHub API). The SKILL.md is at version 2.6 in its frontmatter.
What happens after you ask for a diagram?
Say you type "Make me an architecture diagram of my app: frontend, backend, database, Redis cache." (the README's own example prompt). The SKILL.md walks the agent through roughly six stages.
1. A first-run gate on your style guide. Before the first diagram in a new project, the agent checks whether references/style-guide.md still holds the shipped default tokens. If it does, it stops and asks you to pick a brand source (a website URL, an installed skill, a local folder or design system, pasted tokens, a saved profile, or keep the default). The rule behind it:
Do not silently ship default-skinned diagrams into a branded project.
Source: skills/diagram-design/SKILL.md, line 21, commit cea465e, verified 28 September 2026.
2. Pick a visual type, load one reference. The skill routes the request to one of its types, then loads that type's reference file (architecture, sequence, ER and so on) before drawing.
Forty-one visual types. Semantic patterns describe behavior; type references describe layout.
Source: skills/diagram-design/SKILL.md, line 13, commit cea465e, verified 28 September 2026.
3. Say the plan before drawing. This is the part you notice in the session. The agent posts one short message first:
Before rendering, state the plan in one short message: the chosen visual type (and semantic pattern, if routed), the size preset, and anything the complexity budget (§7) will force out.
Source: skills/diagram-design/SKILL.md, line 139, commit cea465e, verified 28 September 2026.
If you are in the session, you can redirect it there. If the request already pins type, size and content, the skill skips the pause.
4. Hold the complexity budget. The general limits are 9 nodes, 12 arrows and 2 accent-colored elements per diagram, with tighter per-type limits (5 lifelines in a sequence diagram, 8 entities in an ER diagram). Past that, the instruction is short: "If you exceed, split into two diagrams (overview + detail)." (§7 of the SKILL.md, verified 28 September 2026.)
5. Run the taste gate. A pre-output checklist covers type fit, a "remove test" for every node and arrow, accent count, connector geometry (orthogonal elbows, labels that do not sit on their line, no shared attach points) and the accessibility contract. It also asks the agent to run python3 scripts/self_check.py <file> from the installed skill directory.
6. Write one file. The output is a single self-contained .html file with embedded CSS, inline SVG and no external assets except Google Fonts. It is static unless you asked for motion.
What does the output file look like?
The accessibility contract is the part you can check with grep. Here is our illustrative sketch of the shape the contract requires (not copied from the repo):
<svg viewBox="0 0 960 600" role="img"
aria-labelledby="checkout-title checkout-desc">
<title id="checkout-title">Checkout service architecture</title>
<desc id="checkout-desc">Web client calls the API gateway,
which reads from Postgres and caches sessions in Redis.</desc>
<defs><!-- arrow markers --></defs>
<!-- arrows first, then boxes, so lines sit behind nodes -->
</svg>
The rules behind it, from section 12 of the SKILL.md: role="img", aria-labelledby pointing at the title and desc, <title> as the first child before <defs>, and IDs prefixed per diagram so two inline diagrams on one page do not collide. 0 0 960 600 is the viewBox of doc-inline, the default size preset for all three import commands.
The shipped default palette uses paper #f5f5f5, ink #2d3142 and accent #eb6c36. If you see those three values in a file meant for a branded doc, onboarding probably never ran.
How do you redraw an existing Mermaid or draw.io file?
The plugin ships import commands. Three of the README's examples:
/diagram-design:import-mermaid architecture.mmd --size=slide-16x9 --detail=simplified
/diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified --audience=executive
/diagram-design:import-excalidraw whiteboard.excalidraw --size=slide-16x9 --detail=simplified
Source: README.md, Import from draw.io, Mermaid, or Excalidraw, commit cea465e, verified 28 September 2026.
Four dials shape the result: format (html, svg, png, html+png), size preset, detail (faithful up to 24 nodes, balanced up to 12, simplified up to 7) and audience (engineer, mixed, executive). The import extracts content with a Python script, discards the source layout and colors, and redraws. One line in the SKILL.md sets the boundary:
An import is bounded by its source: never invent a component to fill a layout, and never silently drop one.
Source: skills/diagram-design/SKILL.md, line 541, commit cea465e, verified 28 September 2026.
Every import ends with a fidelity ledger listing what was merged, collapsed or dropped. Read it before you paste the result into a deck.
When should you use a different diagram skill?
diagram-design writes a designed file. If your diagram has to live as text in the repo and change in code review, that is the wrong output. The alternatives in our catalog, with dated install figures:
- the design-doc-mermaid page on Skillselion (GitHub): Mermaid flowchart, sequence, class, ER, state, C4 and architecture diagrams from text or source code, aimed at GitHub wikis. About 44.2k installs as shown on its listing on 28 September 2026.
- the Excalidraw Diagram Generator skill (GitHub): an Excalidraw file a teammate can edit by hand. About 29k installs, data as of 7 September 2026.
- the Baoyu Diagram skill page (GitHub): SVG diagrams in a dark-themed design system. About 13.8k installs, data as of 7 September 2026.
- the Mermaid Diagrams skill listing (GitHub): Mermaid syntax for class, sequence, flowchart, ERD and C4 diagrams in software docs. About 4.8k installs, data as of 7 September 2026.
- the Diagram Creator skill (GitHub): Mermaid, PlantUML and ASCII output that renders in docs and IDEs. About 4.2k installs, data as of 7 September 2026.
The SKILL.md makes a related point about when not to draw at all. Lists belong in a table or bullets, and "If a 3-column table communicates the same thing, pick the table." (the SKILL.md selection rules, verified 28 September 2026.)
For the head-to-head, see our comparison of diagram skills for Claude Code. Charts rather than schematics are covered in the data visualization skills guide, and the wider field sits in the Docs and Planning skills ranking and the Docs & Planning category. If you need a diagram during a design conversation rather than for a published doc, obra's brainstorming skill (GitHub) can offer a browser-based visual companion for architecture diagrams and mockups.
FAQ
Does diagram-design need a build step or a renderer?
No. The HTML output opens in any modern browser. PNG export uses Playwright, which the README asks you to install once (pip install playwright && playwright install chromium).
Can I use my company's colors?
Yes. Tell the agent "onboard diagram-design to https://yoursite.com". Per the README, it extracts the palette and fonts, shows a diff, checks WCAG AA contrast of ink on paper at 9 to 12px text sizes, and writes the tokens to references/style-guide.md. Saved profiles plus a .diagram-design marker file let different repos use different brands.
Is it an Anthropic skill?
No. It is a community skill by Cathryn Lavery under the MIT license. Skillselion is independent of Anthropic, OpenAI and Cursor.
Last updated: 28 September 2026. Quotes were checked byte for byte against cathrynlavery/diagram-design at commit cea465e on that date; the SKILL.md last changed in commit da6c92c (27 September 2026 UTC). Install figures are as dated in the text. The Skillselion catalog is refreshed from skills.sh, GitHub and MCP registries and ranked by real installs.
Top comments (0)