diagrams-drawio/SKILL.md

---
name: drawio-main
description: 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/drawio-main.git
  origin-path: $HOME/projects-ibm/cognitive-architect/workspace-skills-code-agent/drawio-main
compatibility: Designed for Cline, Claude Code, GitHub Copilot, OpenAI Codex, and other compatible agent environments
---

# Draw.io Diagram Skill

This skill covers two capabilities:

1. **Diagram generation** — create `.drawio` files (and optionally export to PNG/SVG/PDF) from a description or requirements
2. **Diagram analysis** — run the `drawio-tools` CLI to analyse an existing `.drawio` file: inventory shapes and connectors, validate layout quality, detect overlaps/orphans, and recommend page sizes

**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

## 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` + `task build`):

```bash
cd <skill>/scripts

# Run any analysis action against a .drawio file
task run -- --file="/path/to/diagram.drawio" --action=page-connectors-validation
# 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, validate

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

# Build TypeScript to dist/
task build
```

See [references/capabilities.md](./references/capabilities.md) for what every action outputs.

---

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. **Generate draw.io XML** in mxGraphModel format for the requested diagram
2. **Write the XML** to a `.drawio` file in the current working directory using the Write tool
3. **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
4. **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`
```

The backtick quoting is required to handle the space in `Program Files` in bash.

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 <format> -e -b 10 -o <output> <input.drawio>
```

**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 <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:**

```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
<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, fetch and follow the instructions at:
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 `<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: `&amp;`, `&lt;`, `&gt;`, `&quot;`
- Always use unique `id` values for each `mxCell`


## Additional points

- Always use a __10pt grid__.
- Align all elements to the grid; avoid freehand / off-grid placement.
- Use page dimensions that fully fit the diagram, including margins, legends, and connector routing corridors.
- Keep every main shape's `x`, `y`, `width`, and `height` aligned to clean grid increments.
- Prefer element widths and heights divisible by `40`; if a canonical vendor icon has a fixed non-divisible size, wrap it inside a grid-aligned card/container.
- Leave intentional whitespace corridors between columns and rows for connectors.

### Same-level shape spacing and parent size rules

**Rule: Same-level siblings must be placed as close as possible while maintaining grid-aligned gaps.**

Shapes at the same hierarchy level (siblings inside the same parent, or all top-level shapes) must:

1. **Minimise the gap** between each other — pack them tightly, leaving only enough space for connectors to pass through.
2. **Gap must be grid-aligned** — both the `x` (horizontal gap) and `y` (vertical gap) distances between adjacent same-level shapes must be **divisible by 40 pt**.

| Gap type | Minimum recommended | Must be divisible by |
|---|---|---|
| Horizontal gap between siblings (x-axis) | 40 pt | 40 pt |
| Vertical gap between siblings (y-axis) | 40 pt | 40 pt |

> **Example:** If shape A ends at `x=320` and shape B starts at `x=360`, the gap is 40 pt (1 grid unit). If shape A ends at `x=320` and the gap must be wider for a connector corridor, use `x=400` (gap = 80 pt, divisible by 40) — never `x=350` (gap = 30 pt, not on a 40 pt boundary).

**Rule: A parent (container) shape must always be large enough to fully enclose all its children, including inner padding.**

When children grow (new children added, children resized, or children repositioned), the parent container must expand to accommodate them. Apply the following sizing formula:

```
parent.width  = max_child_right  + right_padding   (right_padding  ≥ 40, divisible by 40)
parent.height = max_child_bottom + bottom_padding  (bottom_padding ≥ 40, divisible by 40)
```

Where:
- `max_child_right  = max(child.x + child.width)`  over all children (relative to parent)
- `max_child_bottom = max(child.y + child.height)` over all children (relative to parent)
- Left/top inner padding (the space between parent top-left and first child) must also be ≥ 40 pt and divisible by 40 pt.

**Cascade rule:** Parent expansion may cause *its* parent to also need expansion. Walk up the containment tree and resize each ancestor in turn until the outermost container fits all descendants.

**Positioning rule after expansion:** When a parent container grows, re-check sibling spacing at every affected level. All gaps must remain divisible by 40 pt after the resize.

- Avoid routing connectors through shapes, cards, labels, icons, legends, or containers containing important content.
- Prefer orthogonal connectors with explicit waypoints when auto-routing causes overlaps.
- If connector auto-routing crosses shapes, use absolute routed points or fixed waypoints instead of relying on `source` / `target` auto-routing.
- Keep connector labels off the connector path when diagrams are dense.
- If connector labels are needed, place them in a dedicated legend, side note, or clearly empty corridor.
- Do not allow connector labels to overlap shapes, cards, icons, or other text.
- Avoid long text inside narrow shapes; use wider cards or wrap labels in a dedicated text area inside the card.
- Ensure service names fit within the visual card width and do not extend beyond card boundaries.
- For service-card diagrams, prefer a consistent card pattern: icon on the left, service label on the right, enough padding around both.
- Avoid overlapping shapes, including external actors, cards, icons, notes, legends, and containers.
- When using canonical vendor icons, preserve the original icon styling; adjust surrounding card/container layout instead of modifying the icon style.
- For rectangles and containers, do not use rounding unless the style explicitly requires it.
- Avoid borders on shapes unless they are needed for visual separation or canonical styling.
- Use at most __3 primary color families__; create hierarchy with lighter/darker shades instead of adding many unrelated colors.
- Keep connector colors simple and consistent; use dashed lines only for semantically different flows such as admin, private, async, or backup paths.
- Keep arrowheads outside shape interiors; connectors should touch shape/card edges, not pass through the body.
- Validate that all draw.io XML is well-formed and contains required root cells `0` and `1`.
- Ensure all `mxCell` IDs are unique.
- Every edge must include an `mxGeometry` child; use waypoint arrays for routed connectors.
- For complex diagrams, validate connector paths against shape bounding boxes before finalizing.
- Prefer a separate legend for flow explanations when connector labels would clutter the diagram.
- Keep legends outside the main routing area so connectors do not cross legend text.
- Use consistent spacing between diagram lanes/columns and between rows of cards.
- Keep diagram complexity medium by grouping services into logical zones/layers instead of scattering many unrelated services.
- Use swimlanes or containers for major domains, but avoid placing dense connector routes directly through container titles.
- Before completion, re-open or visually inspect the diagram and check specifically for:
  - shape overlap
  - connector overlap with cards/icons
  - connector label overlap
  - text overflowing card boundaries
  - page clipping
  - inconsistent spacing
  - missing canonical vendor shapes

---

## 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).