svg-diagram

A house style for hand-written SVG diagrams your agent can follow — the layout arithmetic, the colour system, and a zero-dependency linter that proves it did.

Install

Paste this to your coding agent:

Install the svg-diagram skill from https://github.com/bybit-exchange/svg-diagram
for me by running: npx skills add bybit-exchange/svg-diagram -g

Or run it yourself:

npx skills add bybit-exchange/svg-diagram -g

The CLI detects which agents you have installed and writes each one's path. Drop -g to install into the current project instead.

Every path is named from the skill's frontmatter name, not from where the skill sits here, so moving files in this repository doesn't change them.

SKILL.md is at the repository root, so the install copies the root and svg-lint comes along with the skill text. The linter has no dependencies, so it runs from wherever it landed:

node ~/.claude/skills/svg-diagram/tools/svg-lint/bin/svg-lint.mjs diagram.svg

If you only want the skill text, take the one file the agent reads:

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.md

The skill works on its own that way; svg-lint is what you give up.

Then start a new session and ask for a diagram — the agent should announce that it's using svg-diagram.

Gallery

Ten diagrams, all drawn under this skill and all lint clean. Each one is here for the rule it demonstrates.

How an agent loads a skill

Two dashed containers side by side. Connectors cross the channel between them, and a colour change marks the point where a request matches.

The authoring loop

A cross-layer loop-back line, painted after the boxes so they don't cover it.

Where the lint gate sits

A self-call that leaves its lifeline and curves back to it, its second control point sharing the end point's y so the arrowhead closes level and points at the participant rather than down the lifeline.

From a data API to a document figure

CJK labels sized from the CJK column of the width table — one full font size per character, 12px rather than 7.

The life of a skill in this repo

One semantic colour triple per state. Each forward arrow carries the colour of the state it leaves.

What's in this repository

A dashed border only where the contents are actually drawn — gallery/ and assets/ are directories too, but their members aren't in the figure, so they stay plain boxes.

One command, every agent

A one-to-many fan-out whose branch curves keep each second control point level with the end point, so every arrowhead lands pointing right.

Why the font stack cannot be dropped

A contrast pair built from two semantic triples: the working paths in green, the branch that fails in pink.

Tiered model routing behind one gateway

A symmetric fan-out and convergence, one triple per tier. Only the middle leg leaves the rule box's bottom edge; the two outer ones leave its sides.

A/B benchmark with a model as judge

A dashed group box around exactly the steps that repeat. The return edge is painted last, so it stays legible where it crosses the wall.

What the skill pins down

Every diagram also paints its own white canvas rect as the first element, so it reads as a light card on GitHub's dark theme instead of dark text on a dark background. That isn't theme switching. The diagram carries one colour set, and the rect exists only so that set stays readable wherever the file is embedded.

The full rules — the character width tables, the six arrowhead colour variants, the coordinate bookkeeping, and a twenty-item verification checklist — are in SKILL.md, which is the single source of truth.

Why

• Checked on the real artifact. The linter reads the finished SVG, not an intermediate format. Nothing sits between the receipt and the file you ship.
• Zero dependencies. svg-lint is plain Node with no packages. It runs in a fresh clone, with no install step and no lockfile.
• Placed, not auto-laid-out. The skill hands the agent the arithmetic — box height, baseline offset, arrow clearance, block spacing — so every element lands somewhere chosen rather than somewhere a layout engine picked.
• Findings name the fix. A failure reports the value it found and the value it should hold: viewBox: 11 → 20–25, not "the margin looks wrong".
• CJK-safe by default. A mandatory font stack, plus separate character-width tables for Latin and CJK, so labels are checked for overflow before they're placed.
• Reviewable as text. Every coordinate is a literal, annotated with a comment explaining why it holds that value, so a change to a diagram reads as a diff instead of a re-render.
• Plain SVG out. No runtime, no viewer, no JavaScript. It renders in a README, a docs site, a PDF and a terminal preview.

The lint gate

svg-lint reads the finished SVG and reports what the house style forbids. It's a maintainer tool, run by hand. Nothing invokes it for you, so run it before you hand a diagram over.

node tools/svg-lint/bin/svg-lint.mjs diagram.svg
node tools/svg-lint/bin/svg-lint.mjs diagram.svg --json

Try it on a deliberately broken file:

printf '%s' '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 200 60" width="200"><text x="50" y="20" font-size="12">Load & Save</text></svg>' > /tmp/broken.svg
node tools/svg-lint/bin/svg-lint.mjs /tmp/broken.svg

That reports 3 errors and 7 warnings and exits 1: the unescaped &, the missing font stack, the missing white canvas rect, an off-palette fill, four viewBox margins outside the 20–25px range, and asymmetric margins on both axes. Each finding carries the id of the check that raised it and a repair line:

  1:1  error  No <style> rule declares font-family for text  [font-stack/missing-font-stack]
         repair: font-family: absent → 'PingFang SC', 'Microsoft YaHei', 'Noto Sans CJK SC', system-ui, sans-serif · SKILL.md marks this non-negotiable

The 12 checks cover XML escaping, viewBox clipping, the font stack, box height, baseline offset, block spacing, arrow markers, text overflow, overlap, light-background fallback, palette conformance and connector geometry. A thirteenth id, document-model, raises no findings of its own. It's how the model layer reports what it couldn't read, so the geometry checks never draw conclusions from coordinates they got wrong.

0 errors, 0 warnings is the only pass; a warning is a failure.

Exit codes, the --json shape, and what each check does and doesn't catch are in tools/svg-lint/README.md. SKILL.md carries a troubleshooting table for the symptoms that reach you before the linter does.

Contributing

This repository holds one skill, and the SKILL.md at the root is it.

Frontmatter takes name and description; license and a metadata map (version, author, requirements) are welcome too. name is what every install path keys off. The description is what the agent matches on, so write it as "what it covers + when to use it" — that line is the trigger, and the body costs nothing until the work matches it.

Before you open a PR, use the skill for a real task in a fresh session. If the agent didn't load it on its own, the description needs work; if the output still needed manual correction, the body is missing a rule — or the linter is missing a check.

Diagrams committed here must pass clean, and the test suite has to stay green:

npm run lint:svg:all   # the 11 SVGs this repo ships
npm test               # 933 tests

Everything under tools/svg-lint/test/fixtures/ is excluded from the lint run — for the 14 under fail/, failing is their job, and the 2 under pass/ are asserted by the test suite instead.

License

MIT