diagrams-drawio/SKILL.md

name, description, license, metadata, compatibility

name	description	license	metadata	compatibility
diagrams-drawio	Generate, analyse, edit and publish draw.io diagrams. Always use when user asks to create, generate, draw, or design a diagram, flowchart, architecture diagram, ER diagram, sequence diagram, class diagram, network diagram, mockup, wireframe, or UI sketch, or mentions draw.io, drawio, drawoi, .drawio files, or diagram export to PNG/SVG/PDF.	Proprietary	author version spec origin-repository origin-path repository workspace-swiss-knife 2.0 agentskills.io/specification git@github.ibm.com:CTOTools-skills-code-agent/diagrams-drawio.git $HOME/projects-skills-code-agent/ws-skills-code-agent/diagrams-drawio https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio	Designed for Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments

Draw.io Diagram Skill

This skill covers seven capability families (same headings and order as references/capabilities.md):

1. Deterministic YAML generation — validate v1/v2 semantic Diagram IR and build native multi-page .drawio XML with stable IDs, dependency-aware layout, and obstacle-aware routing. Invoked as CLI action build / task generate
2. Direct XML generation — create .drawio files (and optionally export to PNG/SVG/PDF) from a description or requirements. Agent-authored XML (this file), then CLI action validate / task validate
3. Diagram analysis — analyse an existing .drawio file: inventory shapes and connectors, validate layout quality, detect overlaps/orphans, and recommend page sizes. Invoked as CLI actions summary, page-*, quality, validate via task run -- --action=<name>
4. Semantic lifecycle — loss-aware Draw.io import, transactional stable-ID edits, linked views, semantic query/policy/what-if analysis, three-way synchronization, and self-contained offline story publishing. Invoked as CLI actions import, edit, views, query, test, what-if, sync, story, doctor (each has a same-named task)
5. Safe source importers — bounded native TypeScript subsets for Python, JavaScript/TypeScript, Go, Rust, Terraform, Kubernetes, Docker Compose, SQL, OpenAPI, and CI dependency graphs. Library only: import { importSource } from 'dist/services/source-importers/index.js'; not reachable as a CLI action
6. Toolbox transforms — themes, offline generic shape search, reverse Mermaid/Markdown, semantic diff, strict relabeling, and accessible heatmaps. Library only: import ... from 'dist/services/transforms/{reverse,semantic-diff,relabel,heatmap}.js', 'dist/services/themes/theme-service.js', 'dist/services/shape-catalog/shape-catalog.js'; not reachable as a CLI action
7. Specialized profiles — C4, sequence, tube map, compression, runbook, timelapse, and dependency-ordered build-up services. Library only: import ... from 'dist/services/profiles/index.js'; not reachable as a CLI action

Reference files (read these when using this skill):

• references/capabilities.md — full list of capabilities and all CLI analysis actions an agent can execute
• references/rules-layout.md — mandatory layer model, connector-crossing avoidance, waypoint patterns, overlap verification, layout checklist
• references/rules-style.md — mandatory visual appearance and sizing rules (colors, dimensions, connector dash styles, shape sizing)
• references/xml-references.md — complete draw.io XML reference (styles, routing, containers, layers, dark mode, well-formedness)
• references/negative-space-diagram.md — rules for generating negative space companion diagrams from page-negative-space-summary output
• references/routing-best-practices.md — corridor planning, routing patterns, overlap verification, swimlane routing, validation workflow
• references/maintenance.md — maintaining and rebuilding the skill itself
• references/semantic-lifecycle.md — import, edit, views, query, policy, what-if, sync, story, and doctor workflows
• references/agents365-capability-coverage.md — internal comparison matrix against a 42-entry peer-tool feature list (not independently verifiable), including partial and deferred scope

Available scripts

This skill ships the drawio-tools TypeScript CLI under scripts/. All commands run via task from the scripts/ directory (one-time setup: pnpm install --frozen-lockfile + task build):

cd <skill>/scripts

# Run any action against a .drawio file or Diagram IR model
task run -- --file="/path/to/diagram.drawio" --action=page-connectors-validation
# Analysis actions: summary, page-summary, page-hierarchy, page-connectors-summary,
#   page-connectors-validation, page-labels-validation, page-shape-bbox-validation,
#   page-orphans, page-recommendations, page-hierarchy-full,
#   page-negative-space-summary, quality, validate
# Lifecycle actions: import, edit, views, query, test, what-if, sync, story, doctor
#   (see references/semantic-lifecycle.md)
# Authoring action: build (task generate)

# Validate a .drawio file (mandatory final gate)
task validate -- --file="/path/to/diagram.drawio"

# Build a native .drawio file from a YAML Diagram IR
task generate -- --file="/path/to/spec.yaml" --output="/path/to/diagram.drawio"

# Import an editable Draw.io file to loss-aware semantic IR
task import -- --file="/path/to/diagram.drawio" --output="/path/to/model.yaml"

# Apply one atomic stable-ID edit batch (examples/edit-batch.yaml targets examples/platform-v2.yaml)
task edit -- --file="/path/to/model.yaml" --spec="/path/to/edit-batch.yaml" --output="/path/to/edited.drawio"

# Query, policy-test, and what-if analyse a model
task query -- --file="/path/to/model.yaml" --kind=service
task test -- --file="/path/to/model.yaml" --strict
task what-if -- --file="/path/to/model.yaml" --fail=api

# Three-way sync: --base = previous generated, --file = manually edited, --spec = newly generated
task sync -- --base="/path/to/before.yaml" --file="/path/to/edited.yaml" --spec="/path/to/after.yaml" --output="/path/to/synced.drawio"

# Generate linked audience views or a self-contained offline story
task views -- --file="/path/to/model.yaml" --views="executive,system,security" --output="/path/to/views.drawio"
task story -- --file="/path/to/model.yaml" --output="/path/to/story.html"

# Report optional local backends (no --file needed)
task doctor

# Build TypeScript to dist/
task build

See references/capabilities.md for what every action outputs.

Source importers, toolbox transforms, and specialized profiles (families 5–7 above) are native TypeScript service APIs, not CLI actions. Do not invent action names for them; import the listed dist/services/... modules or use the documented lifecycle actions.

---

Generate draw.io diagrams as native .drawio files. Optionally export to PNG, SVG, or PDF with the diagram XML embedded (so the exported file remains editable in draw.io).

How to create a diagram

1. Prefer YAML Diagram IR for repeatable diagrams — use v1 for simple single-page diagrams or v2 for multiple pages, semantic kinds, explicit geometry/waypoints, provenance, and deterministic linear, layered, tree, grid, or manual layout; then run task generate (CLI action build). See examples/platform-v2.yaml and schemas/diagram-ir-v2.schema.json
2. Generate draw.io XML in mxGraphModel format for the requested diagram
3. Write the XML to a .drawio file in the current working directory using the Write tool
4. Run the mandatory validation actions against the generated file
5. If the user requested an export format (png, svg, pdf), locate the draw.io CLI (see below), export with --embed-diagram, then delete the source .drawio file. If the CLI is not found, keep the .drawio file and tell the user they can install the draw.io desktop app to enable export, or open the .drawio file directly
6. Open the result — the exported file if exported, or the .drawio file otherwise. If the open command fails, print the file path so the user can open it manually

Choosing the output format

Check the user's request for a format preference. Examples:

• /drawio create a flowchart → flowchart.drawio
• /drawio png flowchart for login → login-flow.drawio.png
• /drawio svg: ER diagram → er-diagram.drawio.svg
• /drawio pdf architecture overview → architecture-overview.drawio.pdf

If no format is mentioned, just write the .drawio file and open it in draw.io. The user can always ask to export later.

Supported export formats

Format	Embed XML	Notes
png	Yes (-e)	Viewable everywhere, editable in draw.io
svg	Yes (-e)	Scalable, editable in draw.io
pdf	Yes (-e)	Printable, editable in draw.io
jpg	No	Lossy, no embedded XML support

PNG, SVG, and PDF all support --embed-diagram — the exported file contains the full diagram XML, so opening it in draw.io recovers the editable diagram.

draw.io CLI

The draw.io desktop app includes a command-line interface for exporting.

Locating the CLI

First, detect the environment, then locate the CLI accordingly:

WSL2 (Windows Subsystem for Linux)

WSL2 is detected when /proc/version contains microsoft or WSL:

grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2"

On WSL2, use the Windows draw.io Desktop executable via /mnt/c/...:

DRAWIO_CMD="/mnt/c/Program Files/draw.io/draw.io.exe"

Double quotes preserve the executable path containing the space in Program Files.

If draw.io is installed in a non-default location, check common alternatives:

# Default install path
"/mnt/c/Program Files/draw.io/draw.io.exe"

# Per-user install (if the above does not exist)
"/mnt/c/Users/$WIN_USER/AppData/Local/Programs/draw.io/draw.io.exe"

macOS

/Applications/draw.io.app/Contents/MacOS/draw.io

Linux (native)

drawio   # typically on PATH via snap/apt/flatpak

Windows (native, non-WSL2)

"C:\Program Files\draw.io\draw.io.exe"

Use which drawio (or where draw.io on Windows) to check if it's on PATH before falling back to the platform-specific path.

Export command

drawio -x -f <format> -e -b 10 -o <output> <input.drawio>

WSL2 example:

"/mnt/c/Program Files/draw.io/draw.io.exe" -x -f png -e -b 10 -o diagram.drawio.png diagram.drawio

Key flags:

• -x / --export: export mode
• -f / --format: output format (png, svg, pdf, jpg)
• -e / --embed-diagram: embed diagram XML in the output (PNG, SVG, PDF only)
• -o / --output: output file path
• -b / --border: border width around diagram (default: 0)
• -t / --transparent: transparent background (PNG only)
• -s / --scale: scale the diagram size
• --width / --height: fit into specified dimensions (preserves aspect ratio)
• -a / --all-pages: export all pages (PDF only)
• -p / --page-index: select a specific page (1-based)

Opening the result

Environment	Command
macOS	open <file>
Linux (native)	xdg-open <file>
WSL2	cmd.exe /c start "" "$(wslpath -w <file>)"
Windows	start <file>

WSL2 notes:

• wslpath -w <file> converts a WSL2 path (e.g. /home/user/diagram.drawio) to a Windows path (e.g. C:\Users\...). This is required because cmd.exe cannot resolve /mnt/c/... style paths.
• The empty string "" after start is required to prevent start from interpreting the filename as a window title.

WSL2 example:

cmd.exe /c start "" "$(wslpath -w diagram.drawio)"

File naming

• Use a descriptive filename based on the diagram content (e.g., login-flow, database-schema)
• Use lowercase with hyphens for multi-word names
• For export, use double extensions: name.drawio.png, name.drawio.svg, name.drawio.pdf — this signals the file contains embedded diagram XML
• After a successful export, delete the intermediate .drawio file — the exported file contains the full diagram

XML format

A .drawio file is native mxGraphModel XML. Always generate XML directly — Mermaid and CSV formats require server-side conversion and cannot be saved as native files.

Basic structure

Every diagram must have this structure:

<mxGraphModel adaptiveColors="auto">
  <root>
    <mxCell id="0"/>
    <mxCell id="1" parent="0"/>
    <!-- Diagram cells go here with parent="1" -->
  </root>
</mxGraphModel>

• Cell id="0" is the root layer
• Cell id="1" is the default parent layer
• All diagram elements use parent="1" unless using multiple layers

XML reference

For the complete draw.io XML reference including common styles, edge routing, containers, layers, tags, metadata, dark mode colors, and XML well-formedness rules, read and follow the local copy at references/xml-references.md. No network access is required.¹

Troubleshooting

Problem	Cause	Solution
draw.io CLI not found	Desktop app not installed or not on PATH	Keep the .drawio file and tell the user to install the draw.io desktop app, or open the file manually
Export produces empty/corrupt file	Invalid XML (e.g. double hyphens in comments, unescaped special characters)	Validate XML well-formedness before writing; see the XML well-formedness section below
Diagram opens but looks blank	Missing root cells id="0" and id="1"	Ensure the basic mxGraphModel structure is complete
Edges not rendering	Edge mxCell is self-closing (no child mxGeometry element)	Every edge must have <mxGeometry relative="1" as="geometry" /> as a child element
File won't open after export	Incorrect file path or missing file association	Print the absolute file path so the user can open it manually

CRITICAL: XML well-formedness

• NEVER include ANY XML comments (<!-- -->) in the output. XML comments are strictly forbidden — they waste tokens, can cause parse errors, and serve no purpose in diagram XML.
• Escape special characters in attribute values: &, <, >, "
• Always use unique id values for each mxCell

Layout and style non-negotiables

The full mandatory rule sets live in references/rules-layout.md (grid, 40pt spacing, parent sizing, layer model, connector routing, legends, swimlanes, sequence diagrams) and references/rules-style.md (dimensions, colors, borders, text fit, single-port and corner rules). Read both before generating XML. The short version:

• 10pt grid, 40pt rhythm — every shape aligned to the grid; dimensions and sibling gaps divisible by 40 (gap ≥ 40); parents enclose children with ≥ 40pt padding on all sides and grow (cascading upward) when children grow.
• Connectors overlap only Layer 0 (containers) — never shapes, labels, icons, legends, or swimlane headers; use explicit orthogonal waypoints (edgeStyle=orthogonalEdgeStyle) when auto-routing would clip; no crossings unless unavoidable, then 90°.
• One exit point, one entry point per shape, mid-side only — never a corner; arrowheads stop at the shape edge; first/last waypoint ≥ 20px clear of any shape.
• ≤ 3 color families, rounded=0, no decorative borders, dashed lines only for semantically distinct flows; text must fit inside its shape; keep canonical vendor icons unmodified and wrap them in grid-aligned cards.
• Labels and legends off the routing path — connector labels in a clear corridor or a legend placed outside the routing area; group services into logical zones instead of scattering them.
• Page fits everything including margins, legends, and corridors; before finishing check overlap, connector/label overlap, text overflow, page clipping, inconsistent spacing, and missing canonical shapes, then run page-connectors-validation, page-shape-bbox-validation, and validate.

---

Connector routing

For complex diagrams (many connectors, swimlane zones), read references/routing-best-practices.md — corridor planning, absolute-coordinate calculation, Python overlap verification, routing patterns (top highway, stacked columns, narrow corridors, bypasses, swimlane fan-out/fan-in), waypoint XML format, the port-pin prohibition, and the validation workflow. The mandatory layer model and layout checklist live in references/rules-layout.md.

---

1. Latest upstream source of that reference (only consult if the local copy is suspected to be stale): https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md ↩︎