By name: "diagram-as-code" description: "Author, review, and maintain diagrams as code across Mermaid, PlantUML, Structurizr DSL, Graphviz DOT, and draw.io XML. Covers swimlane/cross-functional workflows, C4 architecture, sequence, state, ER, dependency, and network diagrams. Use when any agent needs to create or update a diagram in a PRD, ADR, spec, UX flow, or architecture doc." metadata: author: "AgentX" version: "1.0.0" created: "2026-04-21" updated: "2026-04-21"
Diagrams as Code
Purpose: One conventions layer for all diagrams produced across AgentX roles. Principle: Text-first, diffable, reviewable, rendered at read-time. Binary formats (PNG, JPG, VSDX) are an export, never the source of truth. Scope: This skill is the convention layer. The
diagram-specialistsub-agent (.github/agents/internal/diagram-specialist.agent.md) owns spawn-and-execute behavior. Each reference file covers one format or quality concern.
When to Use
Load this skill any time an agent needs to:
- Create a swimlane / cross-functional workflow (e.g. the contract-lifecycle template)
- Draw a C4 context / container / component diagram for an ADR or spec
- Capture an API or event sequence
- Document a state machine or lifecycle
- Render an ER diagram or data model
- Produce a network / infra / pipeline topology
- Convert a legacy Visio file into a diffable code artifact
- Review an existing diagram for clarity and correctness
Default Format Policy (Mermaid-First)
Mermaid is the default for all AgentX templates and artifacts. It renders natively in GitHub, VS Code preview, most markdown tooling, and is the lowest-friction option for reviewers.
Use another format ONLY when one of these is true:
- Mermaid cannot express the diagram intent (e.g. true swimlanes with role columns, native Visio
.vsdxround-trip, complex cluster layouts). - The user explicitly asks for PlantUML, draw.io, Structurizr, or Graphviz.
- The artifact must round-trip to Visio (
.vsdx) -- in that case use draw.io.
When falling back, record the reason in the diagram's header comment (e.g. <!-- Format: draw.io; reason: Visio round-trip required -->).
Decision Matrix (pick-the-format)
| Intent | Primary format | Fallback (only if Mermaid cannot express it) | Visio round-trip |
|---|---|---|---|
| System context (C4 L1) / containers (C4 L2) | Mermaid C4 | Structurizr DSL | Mermaid -> Visio web |
| Component / class structure (C4 L3, UML) | Mermaid class / flowchart | PlantUML | draw.io |
| Sequence (API, message, handoff) | Mermaid sequence | PlantUML sequence | Mermaid -> Visio web |
| State machine / lifecycle | Mermaid state | PlantUML state | draw.io |
| ER / data model | Mermaid ER | PlantUML ER | draw.io |
| Journey map / capability map | Mermaid flowchart (LR) or journey | draw.io | Mermaid -> Visio web |
| Dependency / call graph | Mermaid flowchart | Graphviz DOT | SVG -> draw.io -> .vsdx |
| Gantt / roadmap timeline | Mermaid gantt | draw.io | draw.io |
| Cross-functional workflow / swimlane / RACI | Mermaid flowchart with subgraph lanes | PlantUML activity beta, then draw.io CFF | draw.io -> .vsdx |
| Role-phase matrix (roles as columns, phases as bands) | Mermaid flowchart with subgraph lanes | draw.io CFF | Native .vsdx export |
| Network / infra topology with many cluster boundaries | Mermaid flowchart with subgraphs | draw.io | Native .vsdx export |
Rule: Mermaid first. If the intent fits the matrix fallback column, justify it in the header comment. If the deliverable must round-trip to native Visio (.vsdx), draw.io is the only allowed format.
Five Non-Negotiables
- Mermaid-first -- use Mermaid unless the intent cannot be expressed in Mermaid, Visio round-trip is required, or the user explicitly requests another format. Record the reason in the diagram header comment when falling back.
- Text-first source -- the diagram code is committed in git; any PNG/SVG/VSDX is an export next to it, not a replacement.
- Titled and legended -- every diagram has a title, a legend for non-obvious shapes/colors, and a link back to the PRD/ADR/spec it supports.
- Intent-matched format -- if a non-Mermaid format is chosen, it must match the Decision Matrix and the justification must be recorded.
- Rendered before merge -- the author validated the render in the target surface (GitHub markdown, Visio web, draw.io, PlantUML) before handoff.
Load Order
- This
SKILL.md(decision matrix + non-negotiables) - Pick the relevant reference:
- references/swimlane-patterns.md -- cross-functional / CFF / RACI flows
- references/mermaid-patterns.md -- flowchart, sequence, state, ER, C4, journey
- references/plantuml-patterns.md -- activity beta, sequence, component, deployment
- references/c4-structurizr.md -- C4 model levels + Structurizr DSL
- references/graphviz-dot.md -- dependency / network graphs
- references/visio-interop.md --
.vsdximport/export paths
- references/diagram-review-checklist.md -- review gate
Authoring Rules
- Filename:
<artifact>-<issue>-<short-name>.<ext>(e.g.ADR-42-context.mmd,PRD-17-contract-workflow.drawio) - Location: under a
diagrams/subfolder inside the parent artifact's directory - Header comment: title, owner artifact, date, AgentX issue number
- ASCII only -- no emoji, no Unicode symbols (per AgentX golden principle). Use
->, not arrow glyphs - Contrast -- avoid pastel-on-pastel; favor default theme colors over custom palettes unless the target surface requires branding
Consumer Checklist (any reviewer)
Before approving a diagram-bearing artifact:
- Source is text (Mermaid, PlantUML, DSL, DOT, or draw.io XML), not a raw image
- Format matches intent (check against the decision matrix)
- Title + legend + source-link present
- Renders in the target surface
- For swimlanes: every activity in one lane; handoffs labeled; lane count <= 7
- For C4: one level per diagram (no mixing context with component)
- For sequences: arrows carry action + payload, not just direction
- Any binary export (.vsdx, .png, .svg) is co-located with its source