How to Use diagram-design with Claude Code & Codex: Install, Trigger, Export SVG/PNG

Aug 20, 2026

Problem

I installed cathrynlavery/diagram-design into Claude Code, and then I typed:

draw a flowchart

Nothing happened. No diagram, no skill selection. The agent just replied with a plain-text sketch and moved on.

If you searched for “diagram-design not working” or “diagram-design not triggering”, this is the exact failure mode.

The skill was installed correctly. But installed does not mean triggered. That gap between “I installed it” and “the agent actually uses it” is the real problem most people hit with diagram-design, and it is exactly what this post is about.

Here is the order of tests I ran, which is also the order of this post:

Install skill -> Trigger with explicit prompt -> Add CLAUDE.md / AGENTS.md
  -> Build a realistic diagram -> Onboard a brand -> Inspect HTML + inline SVG
  -> Export SVG / PNG (--scale 1/2/3) -> Verify in PowerPoint/docs
  -> Redraw Mermaid/draw.io -> Compare Claude Code vs Codex
  -> Review content accuracy, not just the picture

Environment

Claude Code (agent CLI)
OpenAI Codex (agent CLI)
Pi (agent environment, same skill folder)
diagram-design from cathrynlavery/diagram-design
Playwright (used for PNG rasterization)
Export targets: Figma, PowerPoint, documentation
Cursor / ChatGPT: not tested in this run (see the FAQ section)

What diagram-design actually is

diagram-design is not a drawing app. It is a skill/plugin that gives coding agents a reusable diagram grammar plus a consistent editorial design system. You describe an architecture in text, and the agent produces a branded, self-contained HTML file with inline SVG. In short, it is a skill/rule pack for agents, not a standalone GUI drawing tool.

The fastest way to understand it is to compare it with the tools people usually confuse it with:

Tool	What it is	Output	Editable vector?
diagram-design	Skill + design system for coding agents	Self-contained HTML with inline SVG	Yes
Mermaid	Text-to-diagram markup	Diagrams rendered from markdown	Depends on the renderer
draw.io	Interactive diagram editor	XML/drawio files	Yes
Figma	Collaborative vector design tool	Figma files	Yes
Generic AI image generators	Raster art from prompts	PNG/JPG	No

The key difference: diagram-design gives the agent a fixed visual language, so diagrams across a project look consistent without manual formatting.

Supported diagram types and agent environments

According to the skill definitions in the repository, diagram-design covers flowcharts, architecture diagrams, sequence diagrams, and similar structured diagram types. According to the repository, it is built for coding agents: Claude Code, Codex, and Pi. I ran the full install-to-export flow in Claude Code and Codex; Pi uses the same skill folder, but I did not run the complete export matrix there.

Install diagram-design in Claude Code, Codex, and Pi

Installation means copying the skill folder into the agent’s skills/plugins directory. Here is what I ran on my machine:

git clone https://github.com/cathrynlavery/diagram-design
cp -r diagram-design ~/.claude/skills/diagram-design

cp -r diagram-design ~/.codex/skills/diagram-design

For Pi, I put the same folder into the equivalent plugins/skills location that Pi uses.

Before testing, verify the skill is actually on disk:

ls ~/.claude/skills/diagram-design   # or ~/.codex/skills/diagram-design

Notice that installation is the easy part. The folder is on disk. The harder part is making the agent actually pick this skill. That is the next section.

The real problem: diagram-design installed but not triggered

I ran a small test matrix to see how the agent responded to different prompts:

draw a flowchart

Result: the agent drew a plain-text ASCII sketch using its default behavior. It never loaded diagram-design.

Use the diagram-design skill to draw a flowchart of the checkout flow.

Result: the agent loaded the skill and produced the branded HTML/SVG output.

This pattern repeated consistently in my tests. Vague requests such as “draw a flowchart” are unreliable triggers. Explicit requests that name the skill fire reliably. So the practical rule is simple: name the skill in your prompt.

Make selection reliable with CLAUDE.md / AGENTS.md

Prompting works, but it depends on me remembering to name the skill every time. To make selection consistent, I added an instruction to CLAUDE.md (for Claude Code) and AGENTS.md (for Codex):

When the user asks for a diagram, flowchart, architecture overview, or redraw of an
existing diagram, use the diagram-design skill instead of producing a plain-text
ASCII sketch or a generic HTML mockup.

In my testing, adding this line made Claude Code and Codex default to diagram-design for diagram requests, even when the prompt was more casual. This depends on how each agent handles its instructions file, so it may behave differently in other agents. It did not replace the explicit trigger, but it removed most of the guesswork.

Build a realistic architecture diagram

A toy box-and-arrow example does not test anything real. I asked for a realistic service architecture: several components, named relationships, and directional arrows between them.

My request was:

Use the diagram-design skill to draw an architecture diagram of a payment service:
API gateway, order service, payment service, ledger service, and a database.
Show the direction of each call with arrows and label each relationship.

The generated diagram rendered all components with proper arrows and labels. This is where the visual quality started to look convincing. It is also where I had to stop trusting the picture and start checking the facts, because that is where the real risk shows up.

Brand onboarding

The skill can extract a color palette and fonts from a website URL. I pointed it at a real product website and asked it to apply the brand to the diagram.

Result in my test: the extraction produced usable colors and fonts, and the diagram picked them up. The output looked like it belonged to the product instead of looking like a random template.

One caveat: extraction is not curation. If the website palette is noisy, the diagram follows the noise.

Output: self-contained HTML with inline SVG

The default output is a single HTML file with the diagram embedded as inline SVG. There is no external CSS or image dependency. I opened the HTML in a browser, and the SVG stayed crisp at any zoom level because it is vector. This is the diagram-design SVG path: keep the inline SVG as-is and it remains editable vector output.

Export SVG vs PNG from diagram-design

This is the part where people get confused, and it is the top question I get about diagram-design SVG vs PNG output, so I tested it directly.

SVG: keep the inline SVG as-is. It stays vector, which is what you want for Figma, Illustrator, PowerPoint, and print.

PNG: the skill rasterizes the HTML through Playwright. PNG is a raster image, not a “vector PNG” — no export flag changes that. Zoom in and it gets blurry.

The scale flag controls the rasterization pixel density:

diagram-design export diagram.html --format png --scale=1   # 1x density
diagram-design export diagram.html --format png --scale=2   # 2x density (retina)
diagram-design export diagram.html --format png --scale=3   # 3x density (high-res)

--scale=1 produces a 1x image. --scale=2 doubles the pixel density for retina displays. --scale=3 triples it for high-resolution output. A higher scale means more pixels, not a wider layout — the diagram keeps its logical size, and the extra pixels make lines and text sharper.

Is a 2400px PNG enough for PowerPoint or print?

This question comes up every time PNG export is mentioned, so here is the direct answer.

PNG is raster. There is no such thing as a “vector PNG”; a 2400px PNG is still a fixed grid of pixels.
For PowerPoint and web: 2400px is usually more than enough. Slides render at screen resolutions of roughly 1920px wide, so a 2400px PNG looks sharp on typical monitors and projectors.
For print: it depends on the final physical size and DPI. The math is physical width = pixel width / DPI. At 300 DPI, 2400px is about 8 inches wide; at 150 DPI, about 16 inches. If the diagram fits within your printed size at the DPI you need, a 2400px PNG is fine. For large posters or A2+ pages, it is not enough.
For later editing: PNG cannot be edited as shapes. If content may change, export SVG.

--scale=1/2/3 increases pixel density only; it does not change the diagram’s logical dimensions. Scale 3 does not make the diagram wider in layout terms — it gives more pixels per inch, so text and lines stay sharp when zoomed or printed.

Rule of thumb: PNG at 2x–3x for PPT, web, and normal digital documents; SVG for formal print, large sizes, and anything that may need re-editing.

Verify in a real destination

Exporting a file is not the same as the file being usable. I pasted both the SVG and a --scale=2 PNG into PowerPoint and into a documentation page.

In my test, the SVG pasted cleanly as a vector object and could be resized without quality loss. The PNG also looked fine at 2x, but I noticed the difference immediately when I zoomed in. For documentation slides, 2x PNG is usually enough. For print or anything that needs re-editing, SVG wins.

Redraw Mermaid and draw.io diagrams with diagram-design

I took an existing Mermaid diagram and an existing draw.io diagram, then asked diagram-design to redraw both, and I compared before and after.

In my test, the redraw produced a consistent visual style that matched the brand. The structure, boxes, and arrows were recognizable. The main win was consistency: the redrawn diagrams looked like they belonged to the same design system, while the original Mermaid and draw.io versions did not.

Same request in Claude Code vs Codex

I ran the identical diagram request in both Claude Code and Codex after adding the CLAUDE.md/AGENTS.md instructions.

In my test, both agents selected the skill and produced the same style of output. The difference was in setup, not output: each agent reads its own instruction file, so I had to add the guidance twice. Once both files existed, the behavior matched. That match is likely specific to how these two agents load skills; other agents may differ.

FAQ: diagram-design with Cursor, ChatGPT, or standalone

Does diagram-design work with Cursor?

Cursor supports custom instructions and agent features, so a skill folder may be picked up there, but I have not verified this. diagram-design is a folder of rules and grammar for an agent; whether Cursor honors it depends on how Cursor loads skills and how its model decides to follow them. Test it with an explicit prompt before relying on it.

Can I use diagram-design with ChatGPT?

ChatGPT supports custom instructions in projects and GPTs, but I have not verified diagram-design there. Whether it works depends on whether the model reads the skill folder and follows its grammar. Use an explicit prompt and verify the output format; do not assume every model honors the skill’s instructions.

Can diagram-design run standalone?

No. It is not a standalone GUI drawing tool. It is a skill/rule pack that an agent must load in order to produce diagrams. You need an agent (Claude Code, Codex, or another tool that can load the skill folder) to interpret the grammar and generate the HTML/SVG output.

In short: diagram-design is a skill pack for agents. Whether an unlisted platform works is a function of that platform’s skill loading and model behavior, so verify with an explicit prompt rather than assuming compatibility.

Content accuracy vs visual quality

This is the most important finding from my testing.

diagram-design can produce a beautiful diagram that is factually wrong. In one test, the layout looked polished, but a relationship pointed the wrong way and one numeric label was wrong. The skill draws what the prompt says, so if the prompt implies a wrong relationship, the diagram repeats it with professional styling.

Ask for assumptions before generation

I now start diagram requests with this instruction, so the agent surfaces its assumptions before drawing:

Before generating the diagram, list every assumption you are making
about components, relationships, arrow directions, sequence, and numbers.

In my testing, this catches wrong directions and invented components before they become a styled diagram. Generate only after the agent has stated its assumptions.

Verify after generation

Even with assumptions on the table, generated output still needs a manual check. My checklist before I trust any diagram:

[ ] Arrow direction matches the real dependency
[ ] Sequence order in sequence diagrams is correct
[ ] Component names are spelled correctly
[ ] Numbers / percentages match the real system
[ ] No invented components added for visual balance
[ ] No relationships omitted because they were hard to draw

I treat diagram-design as a styling engine, not a source of truth.

When diagram-design can replace Figma (and when it cannot)

diagram-design replaces the manual formatting part of diagram work. If my job is to produce a consistent architecture diagram quickly, the skill saves a lot of time that I would otherwise spend aligning boxes and matching colors.

It cannot replace Figma for collaborative design. Figma is a multi-user editing environment with comments, real-time collaboration, and design workflows. diagram-design generates a static diagram from text. There is no collaboration layer, no version history, and no comment threads.

In short: use it to generate diagrams fast, and use Figma when the diagram must become a living, shared design artifact.

When NOT to use diagram-design

I would skip diagram-design in these cases:

The diagram must be edited interactively by many people (use draw.io or Figma).
The content is not final and you need live editing instead of regeneration.
The team cannot review the generated content, and wrong relationships would cause real damage.
The export target is a printed physical diagram that needs precise layout control.

The tool reduces formatting work. It does not remove the need for human review.

Troubleshooting diagram-design

Common diagram-design problems and quick fixes. Detailed walkthroughs are in the sections above; this is the fast-reference version.

installed but not triggered — the skill is on disk but the agent never loads it. Fix: name the skill in the prompt and add the CLAUDE.md/AGENTS.md instruction (see the trigger section above).
command/skill not found — the folder is missing or in the wrong path. Fix: confirm ~/.claude/skills/diagram-design (or your agent’s equivalent) exists and contains the skill files.
PNG export failing — Playwright is missing. Fix: install Playwright; PNG rasterization depends on it.
unexpected default colors — no brand was provided, so the default palette is used. Fix: run brand onboarding with a website URL.
brand onboarding selects poor colors — extraction copies the site’s palette, noise and all. Fix: pick a cleaner reference URL or override the palette manually.
diagram too dense — too many components makes the output unreadable. Fix: split into levels or simplify the request.
wrong diagram type — the agent chose a flowchart when you needed an architecture diagram. Fix: state the type explicitly in the prompt.

Quick Reference

Task	What to do
Install	Copy the skill folder into the agent’s skills directory (e.g. `~/.claude/skills/diagram-design` for Claude Code, `~/.codex/skills/diagram-design` for Codex)
Verify skill	Confirm the folder and skill files exist before testing
Explicit trigger	Name the skill: “Use the diagram-design skill to …”
`CLAUDE.md` / `AGENTS.md`	Add a rule so diagram requests default to diagram-design
Brand customization	Run brand onboarding with a website URL, then review the palette
Mermaid / draw.io redraw	Ask diagram-design to redraw the existing diagram for a consistent style
SVG export	Keep the inline SVG; it stays vector for Figma, PowerPoint, and print
PNG export	`--format png --scale=1/2/3`; raster via Playwright, density not layout
Recommended: PPT / web	PNG at 2x–3x is usually enough
Recommended: print / large / editable	Prefer SVG

Summary

In this post, I installed diagram-design in Claude Code and Codex, tested vague prompts against explicit prompts, added CLAUDE.md/AGENTS.md guidance, built a realistic architecture diagram, onboarded a brand, exported SVG and PNG at --scale=1/2/3, and verified the results in PowerPoint and documentation. I also covered Cursor/ChatGPT expectations, the 2400px PNG question, Mermaid/draw.io redraws, and content accuracy. The key takeaway is that diagram-design is a skill pack that must be triggered explicitly, that SVG stays vector while PNG is raster, and that it dramatically reduces formatting work but does not remove the need to validate relationships, numbers, directions, and ordering.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 cathrynlavery/diagram-design on GitHub
👨‍💻 Mermaid: text-to-diagram markup
👨‍💻 draw.io (jgraph/drawio)
👨‍💻 Claude Code documentation
👨‍💻 OpenAI Codex on GitHub

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!