Ask a coding agent to produce an architecture diagram and the default output is a collection of rounded boxes connected by arrows. Every node the same size, every connection the same weight, no hierarchy, no focal point—nothing a reader could not have inferred from a well-organized table. Diagram Design is a skill built around the premise that output quality is a design problem, not a rendering one.
What the skill does
Diagram Design is a plugin maintained by Cathryn Lavery of BestSelf.co. The inspected version is 2.6. It installs into Claude Code, Codex, GitHub Copilot, Factory Droid, Pi, and any Agent Skills-compatible host—Cursor, Gemini CLI, and others—through a shared CLI. Output is a self-contained HTML file with inline SVG. No build step, no external image dependencies.
The SKILL.md opens with a philosophy statement before any capability description: “The highest-quality move is usually deletion.” Every node represents a distinct idea; two nodes that always travel together are one. Every connection carries information; if the relationship is obvious from layout, remove the line. Target density: 4/10. The diagram is done when nothing can be removed.
The skill selects from 44 documented visual types. When behavior, state, or risk carries the meaning, it first chooses one of nine semantic patterns—covering queues, trust boundaries, governance catalogs, lifecycle phases, and others—before choosing a layout type.
Labels, direction, grouping, and trust boundaries
Four components: user, identity provider, application, database. Connected in sequence, that is a layout. Arrow labels—”auth request,” “bearer token,” “query”—specify what flows, not just that something does. Direction on the “bearer token” arrow corrects which component initiates versus receives.
Adding a boundary around the identity provider and application—labeled “trusted zone”—changes the diagram from a sequence to a trust model. A reader now sees which zone handles authentication, which component guards the boundary, and what an unvalidated request encounters. The same four components communicate very different things.
The skill calls this the “secure paved road” semantic pattern: trust boundaries plus permitted or forbidden ingress paths.
A non-development example
A capital expenditure request moving through initiator, finance review, legal review, and executive sign-off is a swimlane diagram. Swimlane shows cross-functional flow: who is responsible at each stage, where the process waits, and what the path looks like when a step fails. Operations directors and finance teams can read this without any coding background.
Who benefits, and who does not
The primary audience is architects and technical writers who produce diagrams frequently enough that plugin setup costs amortize quickly. Consultants and operations leaders who work from existing draw.io files, Mermaid blocks, or process descriptions also have a clear use. The import capability accepts all three sources, redraws at a specified detail level, and adjusts wording rather than node count for executive versus engineer audiences.
Occasional users who need a one-off diagram for a presentation have less reason to install and configure. A general-purpose assistant can produce a serviceable Mermaid block without design enforcement. The question is whether enforcement matters for the use case.
The limitation
A polished visual does not prove the underlying architecture or process is accurate. The skill enforces visual quality but cannot verify that the system described matches the system deployed. A swimlane that omits an exception path is still well-designed. It is also incomplete.
The SKILL.md states: “never invent a component to fill a layout, and never silently drop one.” The fidelity ledger on imports documents what was merged, collapsed, or dropped. Accuracy is the human’s responsibility. A simplified diagram that does not disclose what it omits is a design risk.
Where this sits in the series
This series has argued that most of the agent-skill ecosystem is built for engineering workflows. Diagram Design does not fit that characterization neatly. An architect writing a system design document and an operations director documenting a procurement approval both have a use for a tool that produces editorial-quality visuals from a described structure.
The narrower argument holds: a plugin format with brand onboarding and style guide configuration is more setup than an occasional diagram warrants. For teams producing diagrams at volume, across multiple formats and audiences, that overhead amortizes. For everyone else, it is a judgment call.
Source: github.com/cathrynlavery/diagram-design — README and SKILL.md (version 2.6). Retrieved 8 October 2026.
#TechnicalWriting #DiagramDesign #AgentSkills