AI disclosure: This article was researched, drafted and published by an AI agent. Project capabilities and setup commands were checked against the live project site and repository.
Architecture diagrams are often the last thing a team updates. The code changes, the README changes, and the diagram stays frozen in a screenshot from six months ago. Diagram Design approaches the problem from a different direction: instead of asking every developer to learn a diagram editor, it gives a coding agent a reusable skill for creating and revising visual explanations.
The repository appeared at #9 in the November 21 GitHub Trending daily snapshot, with 636 stars shown in that snapshot. That is current attention, not a guarantee of maintenance or correctness. The live project website currently advertises 50 diagram types and six agent integrations, while the repository README snapshot still mentions 45 types. Treat the catalogue as evolving and use the live documentation for the current list.
- Repository: cathrynlavery/diagram-design
- Project site and gallery: diagramdesign.dev
- Installation and agent support: official setup guide
What the skill does
Diagram Design is an agent skill, not a standalone diagram editor. You install it into a supported coding-agent environment, describe the system or workflow you want to explain, and let the agent use the skill's visual rules and diagram patterns to produce a diagram.
The output is designed to be portable: a self-contained HTML document with inline SVG, rather than a screenshot that can only be edited in one application. The project also documents workflows for importing existing Mermaid, draw.io and Excalidraw material, then applying a more consistent visual treatment.
The live gallery includes architecture diagrams, flowcharts, sequence diagrams, entity-relationship views, timelines and other visual formats. The exact catalogue is changing, which is why the current homepage and docs are more useful than copying an older README count.
Official project gallery image. It is an example output, not a screenshot of a live application.
Why a skill is different from a diagramming app
A traditional diagram editor gives you a canvas and expects you to move shapes around. A skill gives an agent a set of instructions and constraints so it can turn existing technical context into a diagram.
That difference matters when the source of truth already lives in code, docs or an issue:
- Ask the agent to inspect a service boundary or a set of routes.
- Provide the intended audience and the question the diagram should answer.
- Let the skill choose a suitable visual structure.
- Review labels, direction, grouping and missing edge cases.
- Keep the generated HTML or SVG next to the code or documentation it explains.
The workflow is useful for onboarding, architecture reviews, API flows, database relationships, incident retrospectives and explaining a pull request. It is not a substitute for a human architecture review: an agent can produce a visually convincing diagram from incomplete or misunderstood source code.
Another project gallery example, credited to Diagram Design.
Install it in an agent
The repository documents the Skills CLI installation path:
npx skills add cathrynlavery/diagram-design
After installation, start a fresh agent session if your environment only loads skills at startup. Ask it for a concrete deliverable rather than a vague request. For example:
Inspect the API routes and service modules in this repository. Create a sequence diagram showing how a user request moves from the browser through authentication, the API handler, the database and the response. Mark external services and error paths. Save the result as a self-contained HTML file.
For Claude Code, the repository also documents the plugin marketplace flow:
/plugin marketplace add cathrynlavery/diagram-design
/plugin install diagram-design@diagram-design
The project lists additional agent integrations in its setup guide. Use the command documented for your specific agent rather than assuming every host uses the same plugin syntax.
The CLI can update an installed skill:
npx skills update diagram-design
No separate diagram server or build pipeline is required for the basic HTML/SVG output. That makes it convenient to attach a generated artifact to a pull request or publish it alongside documentation.
How to get a diagram that is actually useful
The prompt is part of the engineering work. Include the system boundary, the audience, the intended question, and what should be omitted. A good architecture prompt might specify:
- the services and databases that are in scope;
- which calls are synchronous and which are asynchronous;
- trust boundaries and third-party dependencies;
- the main success path and at least one failure path;
- whether the reader is a new contributor, an operator or a reviewer.
Then verify the output against the source. Check that every service exists, arrows point in the right direction, data stores are not confused with caches, and error paths do not disappear. If the diagram describes an API, compare its endpoints and payload direction with the actual handlers or OpenAPI specification.
For an architecture review, a useful test is whether another engineer can answer a specific question from the diagram without reading the prompt. If they cannot, simplify the visual or add the missing context.
Trade-offs and alternatives
Diagram Design is strongest when the diagram begins with technical context that an agent can inspect. It is less suitable when the work requires pixel-perfect manual layout, complex collaborative editing, or a strict diagram-as-code review pipeline.
| Tool | Better fit |
|---|---|
| Diagram Design | Agent-assisted diagrams from repository or documentation context |
| Mermaid | Version-controlled diagrams embedded directly in Markdown |
| draw.io | Manual editing and broad diagram-format workflows |
| Excalidraw | Collaborative whiteboard-style sketches |
| PlantUML | Text-based UML and repeatable engineering diagrams |
The generated HTML/SVG format is portable, but it is not the same as a native project file for every diagram editor. Import and export fidelity should be tested before making it part of a long-lived documentation workflow.
Also check the repository's privacy notes and the data-handling rules of the agent you use. A diagram can reveal internal service names, network boundaries and infrastructure details. Do not feed private architecture material to an external model unless your organisation's policy allows it.
A short walkthrough
This is a third-party walkthrough of the exact Diagram Design skill, not a maintainer-produced release demo. Use it to see the workflow, then rely on the repository and live documentation for current installation details.
Sources and further reading
- GitHub repository
- Official project site and gallery
- Installation guide
- Repository privacy notes
- Skills CLI documentation
If you try it on a real codebase, start with one diagram that answers one engineering question. Which part of your system is hardest to explain to a new contributor?
Written by Sh Raj Β· LinkedIn Β· StackShade on YouTube


Top comments (0)