bybit-exchange/svg-diagram

svg‑diagram – a house‑style and linter for SVGs generated by AI agents

What it is – A tiny, zero‑dependency Node tool that defines a strict visual style for hand‑written SVG diagrams and provides a command‑line linter (svg‑lint) that checks a finished SVG against that style. The repository ships the skill (a markdown file SKILL.md) that can be installed into many popular coding agents (Claude, Gemini, Copilot, etc.) so the agent knows exactly how to size boxes, place text, draw connectors, and pick colours.

Why it matters for AI agents – Modern code‑generation agents often need to output diagrams (architecture sketches, flowcharts, benchmarks). By giving the agent a concrete arithmetic recipe instead of a vague “make it look nice”, the skill makes the output deterministic, reviewable as plain text, and automatically verifiable with the linter. This reduces post‑generation hand‑editing and ensures consistency across agents.

Key features

• House style – fixed viewBox margins, font sizes, colour triples, arrowhead geometry, CJK‑safe font stack, and explicit escape rules. All rules are documented in SKILL.md.
• Zero‑dependency linter – a single Node script (tools/svg‑lint/bin/svg‑lint.mjs) that runs on any machine without npm install. It performs 12 checks (escaping, viewBox, font stack, box dimensions, baseline, spacing, arrow markers, overflow, overlap, palette, connector geometry, plus a document‑model sanity check).
• Agent‑agnostic install – npx skills add bybit-exchange/svg-diagram -g copies the skill and the linter into the appropriate directory for dozens of agents. The skill’s front‑matter name determines the install path, so the repo can be moved without breaking installs.
• Human‑readable fixes – each lint failure reports the current value, the allowed range/value, and a one‑line “repair” suggestion, e.g. font-family: absent → 'PingFang SC', ….
• Gallery of compliant diagrams – ten example SVGs illustrate every rule (layout, authoring loop, lint gate, data flow, skill lifecycle, repo architecture, multi‑agent install, CJK font handling, tiered routing, A/B benchmark).
• Test suite – npm run lint:svg:all validates the shipped SVGs; npm test runs 984 unit tests, ensuring the linter and skill stay reliable.

How to use

1. Install the skill for your agent:

   npx skills add bybit-exchange/svg-diagram -g   # global install for all agents
   

2. In a new agent session, request a diagram; the agent will announce it is using the svg‑diagram skill and will follow the arithmetic defined there.
3. After the agent outputs diagram.svg, run the linter to verify compliance:

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

   Add --json for machine‑readable output.
4. If any checks fail, edit the SVG according to the repair hints or adjust the skill description and re‑run.

Why the project exists – To make AI‑generated diagrams reviewable as code: every coordinate is explicit, every style is a presentation attribute, and the linter guarantees the output matches a shared visual language without relying on a layout engine or external CSS. This improves reproducibility, simplifies diff‑based reviews, and ensures CJK characters render correctly across platforms.

License – MIT.