How to Make Claude Code Draw Clean Diagrams with Diagram Design

Diagram Design is a free, MIT-licensed agent skill that makes Claude Code, Codex, Cursor, GitHub Copilot and other coding agents draw diagrams as one self-contained HTML file with inline SVG, in a single editorial style you can recolor to match your brand. It gained 1,190 GitHub stars in a single day on October 11 and had about 50,700 in total by October 12, and getting your first diagram out of it takes around five minutes if you already use one of those agents.

• There is nothing to sign up for and no API key. The skill is instructions, templates and a few small Python scripts that run inside the agent you already pay for.
• One command, npx skills add cathrynlavery/diagram-design, installs it for every Agent Skills host. Claude Code, Codex, Copilot and Factory Droid also get marketplace installs with slash commands.
• It covers 44 diagram types, from architecture and sequence diagrams to Sankey, Wardley maps and exploded axonometric drawings.
• Each output can be checked with the bundled self_check.py, which printed OK on the diagram we made for this guide.

The exact steps, start to finish

1. Check what you have installed. Node.js gives you npx for the installer, and Python runs the self-check and PNG export scripts.

   $ node --version
   $ npx --version
   $ python --version

2. Install the skill. Run this in the project that should own your diagrams, or add -g for a user-wide install (that flag comes from npx skills --help).

   $ npx skills add cathrynlavery/diagram-design

3. Claude Code users: use the marketplace instead if you want updates and slash commands. Type these inside a Claude Code session.

   /plugin marketplace add cathrynlavery/diagram-design
   /plugin install diagram-design@diagram-design

4. Turn on auto-update (Claude Code marketplace only). Run /plugin, open Marketplaces, select diagram-design and choose Enable auto-update. Third-party marketplaces have it off by default.
5. Skip the account step. There is no Diagram Design account, key or config file to fill in. The only requirement is an agent session (Claude Code, Codex, Cursor, Copilot, Gemini CLI and so on) that is already signed in with your own plan.
6. Give it your brand, or accept the default. On the first diagram in a project the skill asks whether to onboard. To pull colors and fonts from your site, say:

   Onboard diagram-design to https://yoursite.com

7. Ask for a diagram in plain words. This is the first example prompt from the README, and the one we used.

   Make me an architecture diagram of my app: frontend, backend, database, Redis cache.

8. Open the file it wrote. It is a single .html file, so double-clicking works, or:

   # Windows (PowerShell or cmd)
   start my-diagram.html
   # macOS
   open my-diagram.html

9. Verify the output. The README's check, run from the folder that holds the skill:

   $ python3 skills/diagram-design/scripts/self_check.py my-diagram.html

What npx skills add put on disk when we ran it

We installed it on Windows 10 with Node 24.17, inside a throwaway project folder with the home directory pointed at a scratch location so nothing touched a real agent setup. Because the command ran inside a Claude Code session, the CLI printed "Agent detected, installing non-interactively", cloned the repo, found one skill and copied it to .claude\skills\diagram-design in the project. On Windows without Developer Mode the CLI copies files, because it cannot create symlinks there. The whole thing took under a minute.

RelatedArchify Setup: AI Diagrams for Claude Code in Minutes

What arrived is three folders and a SKILL.md: references (one markdown file per diagram type, plus the style guide, onboarding and import procedures), assets (templates and over 200 example HTML files) and scripts (the self-check, SVG export and the draw.io, Mermaid and Excalidraw parsers). The installer ends with a line worth taking seriously: review skills before use, because they run with your agent's full permissions. This one is plain text and Python you can read in ten minutes, and its privacy policy says it has no server and sends nothing anywhere. The only network request a diagram makes is to Google Fonts.

Then we asked for the README's first example, an app with a frontend, backend, database and Redis cache. The result was a 1000 by 480 SVG with orthogonal connectors, one focal accent on the hot path, a dashed "DATA" zone around Redis and Postgres, and a legend strip. Running the bundled check on it printed OK my-app-architecture.html.

Installing Diagram Design in Claude Code, Codex, Copilot and Cursor

The generic installer works everywhere that reads Agent Skills, including Cursor, Cline, Gemini CLI, Windsurf and Amp. It does not follow updates on its own, so pull them with npx skills update diagram-design. It also installs only the skill, so the /export-diagram, /import-mermaid, /profile and /doctor commands come with the native marketplace packages. If your host has one, the README says to prefer it.

For Codex:

$ codex plugin marketplace add cathrynlavery/diagram-design
$ codex plugin add diagram-design@diagram-design

For GitHub Copilot, then confirm it shows up with copilot skill list:

$ copilot plugin marketplace add cathrynlavery/diagram-design
$ copilot plugin install diagram-design@diagram-design

For Factory Droid:

$ droid plugin marketplace add https://github.com/cathrynlavery/diagram-design
$ droid plugin install diagram-design@diagram-design --scope user

Pi installs straight from the Git URL with pi install https://github.com/cathrynlavery/diagram-design, followed by /reload in an open session. The author also flags that official builds only come from this repository, and any plugin directory listing under a publisher other than LittleMight is an unofficial copy.

Linking a cloned copy on Windows without Developer Mode

If you want to edit the style guide yourself, clone the repo and link the inner skills/diagram-design folder into your agent's skills directory, because managed installs can overwrite local edits. The README's ln -s lines are for macOS and Linux. The project's cookbook gives a Windows version that makes directory junctions, which need no admin rights or Developer Mode. In PowerShell, for Claude Code, after replacing the clone path:

# PowerShell
$src = "E:\diagram-design\skills\diagram-design"
$t = "$env:USERPROFILE\.claude\skills\diagram-design"
if (-not (Test-Path $t)) { cmd /c mklink /J "$t" "$src" }

The same junction from a plain cmd.exe prompt:

:: cmd.exe
mklink /J "%USERPROFILE%\.claude\skills\diagram-design" "E:\diagram-design\skills\diagram-design"

The cookbook loops the same command over the Cursor, Codex (.agents), Cline, Kiro, OpenCode and Copilot folders. Create only the ones you use.

Teaching it your brand colors and fonts

Out of the box every diagram uses a jet-black and tangerine palette with Instrument Serif titles, Geist labels and Geist Mono for technical text. Ask the agent to onboard to your website and it fetches the homepage, maps the colors it finds to five roles (paper, ink, muted, accent, link), checks that ink on paper passes WCAG AA contrast, shows you a diff and writes the tokens to references/style-guide.md once you say yes. It also prints a receipt listing which URLs it sampled and which fonts it used.

RelatedHow to Stop AI Agents Building Generic UIs with Impeccable

Agencies and freelancers get named profiles. Save a brand once, then drop a .diagram-design file containing profile: acme into each client project, and that project reads ~/.diagram-design/profiles/acme.md without touching the shared style guide. Profiles live outside the install folder, so they survive updates.

Is Diagram Design better than Mermaid for docs?

Not for every doc, and the README says so itself. Mermaid diagrams are text that diffs in a pull request and renders on GitHub. Diagram Design's output is a finished drawing: there is no source to diff and no canvas to drag, layout can differ between two runs of the same prompt, and quality depends on the model you run it with.

It can also redraw what you already have. /diagram-design:import-mermaid README.md --diagram=all or /diagram-design:import-drawio platform.drawio --size=slide-16x9 --detail=simplified keeps the components and connections, throws away the old coordinates and colors, and ends with a ledger of what it merged or dropped.

Fixing "offline: file loads Google Fonts" and other self-check failures

Run the self-check with --offline on a default diagram and it fails with offline: file loads Google Fonts; remove the font <link> to use system fonts. We got exactly that on the shipped architecture example. It is not a bug: the default diagram pulls three fonts from Google. Ask the agent for system fonts, or set the font source to system in the style guide, and the file makes no network requests at all, which matters for air-gapped docs and strict content security policies.

The other thing people hit is PNG export doing nothing. PNG rendering goes through Playwright, which is a one-time install:

$ pip install playwright && playwright install chromium

On Windows, PowerShell 5.1 does not accept &&, so run the two halves as separate lines. The cookbook's version, python -m pip install playwright then python -m playwright install chromium, works in PowerShell and cmd alike. If something else looks off, ask the agent to "run diagram-design doctor" (or /diagram-design:doctor in Claude Code). It is read-only and reports what is missing without installing anything. Finally, a diagram in the default tangerine palette inside a branded project means the first-run gate was skipped or answered with "default": answer it again or add a profile marker.

Is it worth installing? For anyone who publishes diagrams, in blog posts, decks, docs sites or client reports, yes. The default style already looks like a design team made it, the install is one command, and you can read every file it adds. Keep Mermaid for diagrams that live next to code and change every sprint, and reach for this when the picture is going in front of readers. One caution: the version number moves almost daily (2.6.74 when we checked), so pin a clone if you need output that looks identical across months.