svg-diagram: a house style and linter for agent-drawn SVG diagrams
Agent skill that draws architecture, flowchart, sequence, data-flow and lifecycle diagrams as hand-placed SVG, to one linted house style.
At a glance
- What is it?
- svg-diagram is an agent skill from bybit-exchange that pins down layout arithmetic, colour triples and typography for hand-written SVG diagrams, then ships a zero-dependency linter to check the result. The style is the product; the linter is the proof.
- Who is it for?
- Adopt svg-diagram if you want diagrams that live as plain SVG files in the repository and are produced by an agent you already run, and if you accept that a 12-check linter, not a renderer, is what keeps them consistent. Do not adopt it if you need a drag-and-drop editor, interactive output, or diagrams that reflow when the underlying system changes; this is a static, hand-placed format with no layout engine behind it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 15 days ago.
- What is it written in?
- Mainly JavaScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 16, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem svg-diagram solves: agents draw SVG badly by default
Ask a coding agent for an architecture diagram and you usually get something that renders but reads as machine output. Boxes overlap, arrowheads sit inside the target, labels collide with connectors, and two diagrams from the same agent on the same day look nothing alike. The README frames the project as "a house style for hand-written SVG diagrams your agent can follow", and that phrasing is accurate: svg-diagram is not a renderer, a CLI that turns a DSL into pictures, or a web editor. It is a set of rules an agent reads before writing SVG, plus a checker that reports whether the rules were followed.
The audience is narrow and specific. It is for people who already use a coding agent (Claude Code, Codex, Cursor, Gemini CLI, Copilot, opencode and others are named in the install table) and who want diagrams committed as .svg files next to the code they describe. If you want a diagramming application with a canvas, this is the wrong shape of tool. If you want diagrams that are text in a diff and can be reviewed, the shape fits.
What the house style actually pins down
The README's table of pinned areas is the most useful part of the project, because it shows how much of diagram quality is arithmetic rather than taste. Box height is derived from the font: one line is font-size times 3, and each extra line adds font-size times 1.5. Text baseline sits at box y plus height divided by two plus font-size times 0.35, which centres glyphs vertically without a dominant-baseline attribute. Arrowheads start 5px clear of the source and end 11px short of the target, and the marker uses markerUnits="userSpaceOnUse" so it scales with stroke width instead of with the viewBox.
Connector geometry is the rule that will surprise people coming from other tools. A straight L path is allowed only when the two ends are co-axial; anything that turns must be a C or Q curve, and right-angle elbows are explicitly out. That single constraint is what makes the gallery diagrams read as diagrams rather than as circuit schematics, and it is also the rule most likely to be broken by an agent that has seen a lot of Mermaid output.
Colour is handled as five semantic fill/stroke/text triples applied through presentation attributes, with no CSS classes and no media queries. That choice makes each SVG self-contained. It also means a theme change is a re-draw, not a stylesheet swap, which the README acknowledges when it explains the white canvas rect: every diagram paints its own white rectangle as the first element so it reads as a light card on GitHub's dark theme. That is not theme switching, and the README says so.
Install svg-diagram and draw a first diagram
The documented install is a single command run through the skills CLI. The README gives both a paste-to-your-agent form and a direct form; the direct one is:
npx skills add bybit-exchange/svg-diagram -gThe README states that the CLI detects which agents you have installed and writes each one's path. The -g flag installs globally; dropping it installs into the current project instead. Documented destinations include ~/.claude/skills/svg-diagram/ for Claude Code, ~/.agents/skills/svg-diagram/ shared by Codex, Cursor, Gemini CLI, Copilot, opencode and Antigravity, ~/.pi/skills/svg-diagram/ for Pi, and ~/.<agent>/skills/svg-diagram/ for Windsurf, Continue, Roo, Goose, Kiro, Trae and others. Paths are derived from the skill's frontmatter name rather than from the file's location in the repository.
If you only want the skill text and not the linter, the README offers a one-file install:
mkdir -p ~/.claude/skills/svg-diagram
curl -fsSL https://raw.githubusercontent.com/bybit-exchange/svg-diagram/main/SKILL.md \
-o ~/.claude/skills/svg-diagram/SKILL.mdThe README is explicit about the trade-off: the skill works on its own that way, and svg-lint is what you give up. Since SKILL.md sits at the repository root, the full install copies the root and the linter comes along with the skill text. The linter has no dependencies, so the README's example invocation runs from wherever it landed:
node ~/.claude/skills/svg-diagram/tools/svg-lint/bin/svg-lint.mjs diagram.svgAfter installing, the README says to start a new session and ask for a diagram; the agent should announce that it is using svg-diagram. For Claude.ai the README notes a different route: zip the folder and upload it under Settings, Capabilities, Skills, with the caveat that this carries the skill text only, since svg-lint needs local Node.
The lint gate and what 12 checks can and cannot catch
The linter is the part of the project with a verifiable surface. package.json defines three scripts: test runs node --test over tools/svg-lint/test/**/*.test.mjs, lint:svg invokes the linter binary, and lint:svg:all pipes every tracked .svg file except the test fixtures through it using git ls-files -z and xargs -0. That last script is the one worth copying into a project, because it turns the style from a suggestion into a gate over the whole repository.
The badge in the README advertises 12 checks, and the gallery describes each of its ten diagrams as lint clean and chosen for the rule it demonstrates. What the linter cannot do is judge whether the diagram says anything true. It can confirm that a box's height matches its line count, that a connector is curved rather than elbowed, that a label clears a line by 10px or a curve by 15px, and that text is escaped. It cannot tell you that the arrow between two services points the wrong way. Treat a clean lint run as a formatting pass, not a correctness pass.
The escaping rule deserves separate attention because it is the one with security consequences. The README states that &, <, >, " and ' are escaped in text and in attributes, and that anything from a database or an API is escaped before it is concatenated into the file. If you generate diagrams from live data, that rule is the difference between a broken figure and an SVG that a browser will parse as markup.
CJK labels and the font stack constraint
Two of the ten gallery diagrams exist specifically because of CJK text. One shows a data flow with CJK labels sized from the CJK column of a width table, described as one full font size per character, 12px rather than 7. The other is a contrast pair showing three platforms rendering CJK correctly and a fourth showing missing glyphs. The README's font row explains the cause: the stack keeps Noto Sans CJK SC so Linux rendering does not fall back to tofu.
This is a real constraint, not a footnote. If you strip the font stack to shorten the file, or if your rendering environment lacks Noto Sans CJK SC, CJK labels degrade to empty boxes. The README's position is that the stack cannot be dropped, and the gallery diagram is there to make that argument visually. Latin-only diagrams do not face this, which is why the rule is easy to miss until someone adds a Chinese label to an existing figure.
Where svg-diagram is the wrong tool
The most important limitation is that there is no layout engine. Every coordinate is placed by hand, by the agent. The style rules constrain those coordinates, but nothing recomputes them. Add a node to a five-box architecture diagram and the agent must re-derive positions, spacing and connector paths for the whole figure. Mermaid and Graphviz take the opposite approach: you describe nodes and edges and the tool computes geometry. If your diagrams change often, or if they are generated from a model that changes per commit, a layout engine will cost you less maintenance than a hand-placed file.
The second limitation is output format. The README's gallery covers architecture, flowchart, sequence, data-flow and lifecycle diagrams, and the sequence example is a real sequence diagram with lifelines, an alt frame and a self-call. But there is no interactivity, no zoom controls, no click targets, and no export path to draw.io XML or Mermaid source. If a downstream consumer expects one of those formats, svg-diagram is the wrong starting point.
The third is the Claude.ai path. The README states that the zip-and-upload route carries skill text only, because svg-lint needs local Node. On that surface you get the style rules without the check, which is a materially weaker version of the project.
Alternatives and the difference in approach
The repository's own topics list mermaid-alternative, which makes the comparison explicit. Mermaid is a text-to-diagram language: you write a graph declaration and a renderer computes the layout, so a diagram survives edits to its content. svg-diagram inverts that. The agent writes the final coordinates, and the skill supplies the arithmetic that keeps those coordinates consistent. You gain control over exact placement, which matters when a figure has to match a document's visual language, and you lose automatic reflow.
Against a general SVG editor, the difference is who does the placing. An editor gives a human a canvas and direct manipulation; svg-diagram gives an agent a rulebook and a linter. The two are not mutually exclusive, since the output is ordinary SVG that an editor can open, but the workflow assumes the agent writes first and the human reviews the diff.
Against diagrams-as-code tools that emit SVG from a DSL, the trade is expressiveness versus determinism. A DSL constrains what you can draw to what the DSL models. Hand-placed SVG constrains nothing except the style rules, which is why the gallery can include a cross-layer loop-back line painted after the boxes so they do not cover it, and a return edge painted last so it stays legible where it crosses a group wall. Those are drawing decisions a DSL would not expose.
Maintenance, licence and upgrade cost
The repository is not archived, and the last push was on 2026-09-03. The only release listed is v0.1.0 from 2026-09-02, so the project is at an early version and the surface described here is the initial one. The MIT licence is declared in the LICENSE file and in package.json, which places the skill text and the linter under a permissive licence; that is a statement about the repository's terms, not advice about your own use.
Upgrade cost is low by construction. The linter has no dependencies, so there is no lockfile to reconcile and no transitive tree to audit. The skill is a single Markdown file at the repository root, which means a version bump is a file replacement plus a re-run of the lint gate. The real upgrade cost is not the install but the diagrams: if a future version changes the box-height formula or the arrowhead offsets, every existing figure will fail the new checks and need re-drawing. Running lint:svg:all before and after an upgrade will tell you the size of that job in one command.
Editorial conclusion
Adopt svg-diagram if you want diagrams that live as plain SVG files in the repository and are produced by an agent you already run, and if you accept that a 12-check linter, not a renderer, is what keeps them consistent. Do not adopt it if you need a drag-and-drop editor, interactive output, or diagrams that reflow when the underlying system changes; this is a static, hand-placed format with no layout engine behind it. Verify first that your agent surface is one the installer writes to, that Node is available where you want to run svg-lint, and that your target renderer is a browser or GitHub rather than a tool that expects draw.io XML or Mermaid source.
Frequently asked questions
What is an SVG diagram?
An SVG diagram is a figure stored as Scalable Vector Graphics, meaning it is markup with explicit coordinates rather than a grid of pixels. In svg-diagram the file is written by hand by an agent, with every box, connector and label placed at a computed position, and the repository's gallery holds ten examples drawn this way.
What is the difference between SVG and PNG?
The README's colour rules depend on SVG being markup: the five semantic fill, stroke and text triples are applied as presentation attributes, and each diagram paints its own white canvas rect as the first element so it reads as a light card on GitHub's dark theme. A PNG would bake those colours into pixels and could not be linted or diffed as text.
How do I view an SVG diagram?
Any browser renders an SVG file directly, which is the assumption behind the white canvas rect that keeps the figure legible on GitHub's dark theme. The repository's own gallery is a set of SVG files meant to be viewed that way.
How can I draw my own SVG?
Install the skill with npx skills add bybit-exchange/svg-diagram -g, start a new session, and ask your agent for a diagram; the README says the agent should announce that it is using svg-diagram. The agent then follows the pinned layout, colour and typography rules, and you can check the result with the bundled svg-lint.
Community notes