--- name: diagrams-drawio description: 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. license: Proprietary metadata: author: workspace-swiss-knife version: "2.0" spec: agentskills.io/specification origin-repository: git@github.ibm.com:CTOTools-skills-code-agent/diagrams-drawio.git origin-path: $HOME/projects-skills-code-agent/ws-skills-code-agent/diagrams-drawio repository: https://gitea.lego-cloud.eu/home-v1-skills-code-agent/diagrams-drawio compatibility: 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](./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=` 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](./references/capabilities.md) — full list of capabilities and all CLI analysis actions an agent can execute - [references/rules-layout.md](./references/rules-layout.md) — mandatory layer model, connector-crossing avoidance, waypoint patterns, overlap verification, layout checklist - [references/rules-style.md](./references/rules-style.md) — mandatory visual appearance and sizing rules (colors, dimensions, connector dash styles, shape sizing) - [references/xml-references.md](./references/xml-references.md) — complete draw.io XML reference (styles, routing, containers, layers, dark mode, well-formedness) - [references/negative-space-diagram.md](./references/negative-space-diagram.md) — rules for generating negative space companion diagrams from `page-negative-space-summary` output - [references/routing-best-practices.md](./references/routing-best-practices.md) — corridor planning, routing patterns, overlap verification, swimlane routing, validation workflow - [references/maintenance.md](./references/maintenance.md) — maintaining and rebuilding the skill itself - [references/semantic-lifecycle.md](./references/semantic-lifecycle.md) — import, edit, views, query, policy, what-if, sync, story, and doctor workflows - [references/agents365-capability-coverage.md](./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`): ```bash cd /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](./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`: ```bash grep -qi microsoft /proc/version 2>/dev/null && echo "WSL2" ``` On WSL2, use the Windows draw.io Desktop executable via `/mnt/c/...`: ```bash 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: ```bash # 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 ```bash /Applications/draw.io.app/Contents/MacOS/draw.io ``` #### Linux (native) ```bash 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 ```bash drawio -x -f -e -b 10 -o ``` **WSL2 example:** ```bash "/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 ` | | Linux (native) | `xdg-open ` | | WSL2 | `cmd.exe /c start "" "$(wslpath -w )"` | | Windows | `start ` | **WSL2 notes:** - `wslpath -w ` 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:** ```bash 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: ```xml ``` - 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](./references/xml-references.md). No network access is required.[^xml-upstream] [^xml-upstream]: 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 ## 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 `` 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](./references/rules-layout.md) (grid, 40pt spacing, parent sizing, layer model, connector routing, legends, swimlanes, sequence diagrams) and [references/rules-style.md](./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](./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](./references/rules-layout.md).