---
name: diagramagic
description: Generate and edit SVG diagrams using svg++ and the diagramagic CLI
allowed-tools: Bash(diagramagic *), Read, Write, Glob
---

# diagramagic — svg++ Diagram Skill

Diagramagic helps LLMs create better, larger diagrams more easily by keeping SVG familiar and adding minimal layout extensions.

You generate diagrams using svg++ (SVG with diag: layout extensions) and the
diagramagic CLI tool.

## Setup (first use per session)

Run these commands and use their output as your syntax reference:

- !`diagramagic cheatsheet`
- !`diagramagic patterns`

## Workflow (required)

1. Create or edit a `.svg++` file
2. Run `diagramagic render <file>.svg++` to generate PNG
3. View the PNG to verify correctness
4. If incorrect, fix the source and render again
5. When satisfied, run `diagramagic compile <file>.svg++` for final SVG

## Quality Standard

You are writing SVG. The `diag:` extensions handle layout and sizing — they do not replace your responsibility to create rich, detailed, information-dense diagrams. Write with the same visual quality and detail you would if generating raw SVG. The `diag:` features save you from coordinate math, not from doing the actual design work.

## Layout Rules

- Use `<diag:diagram>` root with `xmlns="http://www.w3.org/2000/svg"` and `xmlns:diag="https://diagramagic.ai/ns"`
- Use `diag:flex` for layout structure (stacks, rows, grids of cards) — but fill those containers with rich, detailed content
- Use `diag:graph` for auto-layout when topology matters (flowcharts, dependency graphs) — but treat it as scaffolding, not the complete design
- Choose graph layout deliberately:
  - `layout="layered"` for flowcharts, request pipelines, dependency chains
  - `layout="radial"` for hub-and-spoke systems
  - `layout="circular"` for peer/cyclic systems
- Choose routing deliberately:
  - `routing="auto"` as default
  - `routing="ortho"`/`"polyline"` for dense technical diagrams where readability matters most
  - `routing="curved"` for lighter conceptual diagrams; avoid it for dense feedback-heavy graphs
- Keep graph nodes content-rich (title + details), not just single-line labels
- For title+body graph nodes, set `diag:node gap="6"` to `gap="12"` to avoid cramped text blocks
- If graph output gets crowded, split into multiple subgraphs with `diag:include` or switch to a hybrid flex + arrows structure
- Use `diag:wrap="true"` on `<text>` for multi-line text (wrapping is a text feature, not a `diag:node` feature)
- Use `diag:arrow` with `id`-tagged elements for connectors
- Use `label-rotate="horizontal"` for readable arrow/edge labels by default; use `follow` only when line-following text is intentionally desired
- Use `diag:anchor` for precise named points (sequence diagrams, etc.)
- Use `diag:include` to compose large diagrams from sub-files
- Use `diag:template` when you have 3+ visually identical elements (e.g., entity cards, service boxes)
- Mix raw SVG freely: `<rect>`, `<line>`, `<circle>`, `<path>` for decorative elements, region backgrounds, custom shapes
- Do NOT stop at first compile — iterate until the render matches intent
- `layout="circular"` and `layout="radial"` require system Graphviz (`dot`) on PATH; layered layout can fall back if unavailable

## Error Recovery

- `E_PARSE_XML`: fix malformed XML and retry
- `E_SVGPP_SEMANTIC`: fix svg++ structure/ids and retry
- `E_INCLUDE_ID_COLLISION`: rename conflicting ids between parent and included files
- `E_GRAPH_UNKNOWN_NODE`: ensure every `diag:edge from/to` id exists as a `diag:node` in the same graph
- `E_GRAPH_SELF_EDGE`: remove or redesign self-referential `diag:edge` (`from == to`)
- `E_GRAPH_TOO_LARGE`: split the graph into smaller sections or compose with `diag:include`
- Always attempt at least one fix before asking for help