diagram-design Claude skill

How to make a diagram with diagram-design, step by step

The workflow is the same in every host that reads Agent Skills. Install the skill, set up your brand once, then describe the diagram in plain words.

1. Install. Run npx skills add cathrynlavery/diagram-design. In Claude Code you can use the plugin marketplace instead (/plugin marketplace add cathrynlavery/diagram-design, then /plugin install diagram-design@diagram-design), which also gives you updates and the slash commands.
2. Answer the first-run question. Before it writes the first diagram in a new project, the skill opens references/style-guide.md and checks whether the tokens are still the shipped defaults (paper #f5f5f5, ink #2d3142, accent #bf4520). If they are, it stops and asks how you want to customize: (a) website URL, (b) installed skill, (c) local folder or design system, (d) paste tokens, (e) keep default, or (f) load a saved profile. The SKILL.md tells the agent not to silently ship default-skinned diagrams into a branded project. Expect this pause, because it is part of the design.
3. Describe the diagram. The README gives prompts like these:
   • "Make me an architecture diagram of my app: frontend, backend, database, Redis cache."
   • "I need a quadrant showing Q2 projects by impact vs effort."
   • "Give me a sequence of a bearer call with token refresh on 401."
   • "Onboard diagram-design to https://yoursite.com"
4. Read the plan. The agent picks a diagram type and states its plan before writing. Check here whether it chose the type you expected, since correcting a plan costs less than redrawing a finished file.
5. Open the file. The output is one .html file. Double-click it to open it in a browser tab or window.
6. Export if you need an image. PNG export runs through Playwright, so do the one-time setup first: pip install playwright && playwright install chromium. SVG export does not need that browser step.

For the OAuth-style sequence prompt above, the README says the skill uses the ALT combined-fragment grammar described in type-sequence.md. The repo ships example-sequence-oauth.html so you can see the expected result before you run the prompt yourself. The repo's docs/cookbook.md collects operator recipes for first diagrams, brand setup, import, export, validation and reusable prompts.

The style guide as the design system's source of truth

Every diagram reads its colors and fonts from one file, skills/diagram-design/references/style-guide.md. The README says everything downstream reads from there, so changing a token there changes the look of every later diagram. That makes the style guide the source of truth for your diagram design system. Avoid patching colors into individual HTML files.

When you onboard from a website, the skill maps parts of your site onto named tokens:

Before it writes the tokens, the skill checks WCAG AA contrast for ink over paper. Diagram labels are small (the README cites 9 to 12px), so a brand color that passes on a marketing page can still fail inside a diagram. When that happens, the skill proposes an adjusted value and explains why. Expect your diagram palette to differ slightly from your site if your site runs close to the contrast limit.

You can skip onboarding and edit the table in style-guide.md by hand. That option fits teams whose palette lives in a design system document rather than on a public website.

For several brands or clients, use profiles. The SKILL.md describes a project .diagram-design marker, resolved according to references/profiles.md. A marker that resolves selects its profile and skips the first-run gate. Option (f) at the gate loads a saved profile. profiles.md also covers failure handling, the protected default and save behavior, so read it before you set up more than one brand.

The audience setting is separate from the brand. It has three values, engineer, mixed and executive, and changes the wording on the diagram, not the number of boxes. The README's example shows one node labeled Auth Service / JWT · RS256 · :8443 for engineers, Auth Service / token check for a mixed audience, and Sign-in for executives. You can keep one data flow or architecture diagram and relabel it for different readers. You do not have to maintain separate versions.

Getting the agent to choose the right diagram type

With 45 types available, the main design decision is which type fits your content. The SKILL.md handles this in two stages: "Semantic patterns describe behavior; type references describe layout." Its selection section is titled "semantic pattern, then visual type." The agent first works out what your content does (a process with steps, a system with components, a comparison along two axes, change over time), then picks the layout that shows it.

Prompts work better when they say what the diagram needs to show, not only what to call it:

• For a system overview, name the components and how they connect, as in the README's "frontend, backend, database, Redis cache" example. That points toward an architecture or high-level type.
• For a ranking or tradeoff, name the two axes. "Impact vs effort" points directly to a quadrant.
• For an interaction over time, name the actors and the branch condition. "Token refresh on 401" tells the agent it needs a sequence with an alternative path.
• For data movement, say where data starts and where it ends up. The type list includes data flow, Sankey and medallion diagrams, and phrasing like this helps the agent tell them apart.

The description covers more than boxes and arrows. It also lists chart types such as bar and dumbbell, waterfall, slopegraph, ridgeline, streamgraph, bump, Gantt, scatter, bubble, beeswarm, box plot, heatmap, treemap and marimekko. It lists planning formats such as kanban, story map, user journey, service blueprint, Wardley map, fishbone, lifecycle phase maps and block decomposition trees. If you are unsure what to ask for, look at the gallery linked from the README first and request the type by name.

The SKILL.md also has a section of universal anti-patterns and a set of core SVG primitives. If a result looks off, such as crowded labels, a decorative element you did not ask for, or a shadow, ask the agent to check the output against those sections. You do not need to describe the fix yourself.

Setup gotchas across agent hosts

A few install details are easy to miss.

Symlink versus copy. If you install into several hosts at once (for example Cursor plus another tool), the skills CLI asks which method to use and recommends Symlink. You get one canonical copy linked into each host root, so a later update reaches all of them. Pass --copy if you want independent copies per host. Copies can drift apart, so you would update each one separately. If your selection resolves to a single directory, the CLI copies, because the two methods behave the same there.

Windows. Without Developer Mode, Windows does not allow the symlinks the CLI prefers. The CLI falls back to copies and reports which roots it copied. The cookbook also has a recipe for Windows junctions if you want linked installs anyway.

Auto-update in Claude Code. Claude Code disables auto-update by default for third-party marketplaces. To turn it on, run /plugin, open Marketplaces, select diagram-design and choose Enable auto-update. After that, Claude Code refreshes the marketplace and plugin in the background after startup. Run /reload-plugins when prompted, or let the next session pick up the update.

Editable installs. If you want to change the skill itself, the README shows a manual route: clone the repo and symlink skills/diagram-design into your host's skills folder, for example ln -s ~/code/diagram-design/skills/diagram-design ~/.claude/skills/diagram-design. Create only the skill roots for the hosts you actually use. If you plan to contribute new diagram types or import grammar, CONTRIBUTING.md lists the validation gates your changes must pass: skin lint, render lint, and geometry and data-encoding verification.

Official sources. The README says official builds come only from the cathrynlavery/diagram-design repository. LittleMight, Cathryn Lavery's company, publishes the plugin directory listings. A listing under any other name is an unofficial copy, so check the publisher before you install from a directory.