Draw editorial diagrams with your agent using diagram-design
diagram-design is an agent skill that turns a plain-words request into one self-contained HTML + SVG diagram in your brand, and ships checkers that verify the result.
TL;DR
diagram-design is an MIT-licensed agent skill. You ask your agent for a diagram in plain words, it picks one of 51 diagram types and writes a single .html file with inline SVG that opens with a double-click. You can onboard it to your website's colors and fonts, redraw existing Mermaid, draw.io, Excalidraw or PlantUML diagrams, and export to SVG or PNG.
Why this repo matters
The author's problem, in the README: asking a model for a diagram gave "a generic rounded-box thing" that looked nothing like her site. The model understood the content but lacked taste, so she wrote the taste down: one accent color for the one or two things that matter, 1px hairlines, no shadows, every coordinate on a 4px grid. The README is also candid about the trade-off: output quality depends on the model, and the result is not an editable source format, so for docs that change every sprint in Git, Mermaid is still the better fit. This skill is for the diagram you are going to publish.
Best practices
- Delete before you add. SKILL.md's philosophy is that "the highest-quality move is usually deletion", with a target density of 4/10 and a budget of 9 nodes, 12 arrows and 2 coral elements per diagram. Above that, split into an overview and a detail diagram.
- Ask whether a diagram is needed. SKILL.md tells the agent not to draw when a table, a list or one sentence does the same job.
- Onboard your brand first. The first-run gate pauses if the style guide still has the shipped defaults, and offers a website URL, an installed skill, a local folder, pasted tokens, the default, or a saved profile.
- Keep one accent. The accent color belongs on 1 to 2 focal elements; using it on many nodes erases the signal.
- Verify the file. The README's "It's working if" list says
python3 skills/diagram-design/scripts/self_check.py <file>should printOKon a generated file. - Prefer static; add motion only when it explains order. Motion is optional, never required, and the complete static frame must show without it.
How-to
Where do I start?
1. How do I install it?
The README documents one cross-agent command for hosts that read Agent Skills (Cursor, Claude Code, Codex, GitHub Copilot, Gemini CLI, Cline, Windsurf, Amp and others).
npx skills add cathrynlavery/diagram-design
GitHub Copilot also has a plugin route, which adds the doctor, export, import and profile capabilities:
copilot plugin marketplace add cathrynlavery/diagram-design
copilot plugin install diagram-design@diagram-design
The npx skills add install gives you the skill only. Per the README, the slash commands used in later steps (/export-diagram, /import-*, /profile, /doctor) come with the native packages, so install the plugin on your host (Copilot above, or pi install https://github.com/cathrynlavery/diagram-design for Pi) if you want them. Without them, ask in natural language ("Export this diagram as SVG and PNG").
Next: Ask for my first diagram
Try it
Ask your agent: "Give me a sequence diagram of a login request with a token refresh on 401." Save the output, run self_check.py on it, then ask for the same flow as a flowchart and compare which one reads better. Count the nodes; if you are above 9, ask the agent to split it.
Pitfalls
- Not diff-friendly. The output is HTML with inline SVG, not a text source; the README says Mermaid is better for docs that live in Git and change every sprint.
- Output varies. The README warns the same prompt can lay out differently twice and quality depends on the model you run.
- One network request by default. Diagrams load Instrument Serif, Geist and Geist Mono from Google Fonts; ask for system fonts if you need zero network requests.
- Default skin in a branded project. Skip onboarding and you get the jet-black + tangerine default, so run onboarding once per project or profile.
Next steps
- README and the gallery
- SKILL.md: philosophy, selection guide and pre-output checklist
- docs/cookbook.md: recipes for install, brand setup, import, export and the gates
- references/animation.md: the optional motion contract