Agents365-ai/drawio-skill: turning Terraform, SQL and whiteboards into editable draw.io models

The problem: diagrams that go stale the week after you draw them

Most architecture diagrams are drawn once and then diverge from the system. The README frames the goal as maintainable `.drawio` architecture models rather than one-off pictures, and the feature list is organised around that distinction: incremental sync, multi-view projection, drift diff, and architecture rules enforced in CI. The target user is an engineer who already has a diagramming habit (draw.io specifically) and a source of truth that changes: a Terraform tree, a Kubernetes manifest set, SQL DDL, an OpenAPI or AsyncAPI spec, Protobuf, or GraphQL SDL. It is also aimed at people who want an agent to produce the diagram rather than hand-place 40 boxes. The skill works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Autohand Code, Hermes, and any agent compatible with the Agent Skills format, so the pitch is not tied to one assistant.

How the model works: meaning, provenance and geometry kept apart

The README describes an architecture digital twin, or Diagram IR, that separates meaning, provenance, and geometry. The README lists `diagramctl sync`, which updates changed nodes and relations while preserving tuned coordinates, styles, and annotations, and drift diffs between two diagrams or between two live snapshots. One model can then be projected into executive, system, deployment, data-flow, and security views instead of maintaining five files. Generation is not a single pass: the skill plans the layout, writes the XML, exports a PNG, and self-checks that PNG, auto-fixing overlaps, clipped labels, and stacked edges for up to two rounds, with up to five rounds of user feedback. For sequence diagrams the README claims computed lifelines and activation bars rather than hand-placed ones. The CLI surface is `diagramctl doctor/build/sync/views/query/test/review/whatif/story/publish/transform`, and the README states core workflows are stdlib-only and offline. An optional MCP server exposes the same commands to Claude Desktop, Cursor, VS Code, Codex, and other MCP hosts.

Installing the draw.io CLI and the skill, then a first build

There are two install steps and the order matters: the skill shells out to the draw.io desktop CLI, so the binary has to exist first. On macOS the README gives `brew install --cask drawio`; on Windows it points at the drawio-desktop releases page; on Linux it points at the `.deb`/`.rpm` packages in those releases and notes that headless use needs `sudo apt install xvfb`. Verify the binary before going further, and note the version guidance: version 30 or newer is recommended because it unlocks Mermaid to `.drawio` conversion and the ELK `--layout` pass, both unavailable on 29 or below.

brew install --cask drawio
drawio --version

On WSL2 the CLI is the Windows desktop executable reached through `/mnt/c`, and the README says the skill detects this automatically. With the CLI in place, install the skill itself. The one-liner works for any Agent Skills compatible agent; the manual fallback the README documents is to clone the repository to a persistent path such as ~/src and link its skills/drawio-skill subdirectory into the skills directory (copying it on hosts that do not follow symlinks).

npx skills add Agents365-ai/drawio-skill -g

git clone https://github.com/Agents365-ai/drawio-skill.git ~/src/drawio-skill
mkdir -p ~/.claude/skills
ln -s ~/src/drawio-skill/skills/drawio-skill ~/.claude/skills/drawio-skill

The workflow it describes is: point the agent at a source (for example a Terraform directory or a SQL DDL file), let it plan and write the `.drawio`, then let it export and self-check the PNG. When a source changes, `diagramctl sync` is the command that updates the existing file instead of regenerating it from scratch.

Where the drawio-skill approach breaks down

The dependency on the draw.io desktop CLI is the sharpest constraint. That binary is a desktop application, so headless Linux needs xvfb, and the README points to a troubleshooting reference for WSL2 path detection. If your CI runner is a minimal container, you are installing a desktop app and a virtual framebuffer before you can render anything. Version skew is a second failure mode: on draw.io 29 or below, Mermaid conversion and the ELK layout pass simply are not available, so a diagram that works on a maintainer's machine may fail elsewhere. Third, the self-check loop is bounded. The README states up to two automatic fix rounds and up to five rounds of user feedback, which means a sufficiently tangled graph will still come out with problems for a human to fix. Finally, this is the wrong tool if you want a hosted, browser-only diagramming service with no local binary, or if your team has standardised on a different file format and does not want `.drawio` as the artifact of record.

Compared with Mermaid and diagrams-as-code tools

Mermaid is the obvious alternative and the difference is not cosmetic. Mermaid is text in, layout out: you write the graph and the renderer decides placement, and you cannot drag a box afterwards. drawio-skill inverts part of that. The README positions Mermaid as an input format (28 standard types including mindmap, gantt, timeline, journey, pie, sankey and kanban, converted by the draw.io CLI into a laid-out, editable `.drawio`), so the output is a file a human can open and adjust, and those adjustments survive the next sync. That is the real distinction: a diagrams-as-code tool treats the text as the source of truth and the picture as disposable, while this project treats the `.drawio` file as a durable artifact with provenance attached. The cost is weight. Mermaid needs a renderer; this needs a desktop application, a skill installation, and a CLI. If your diagrams are short-lived and live inside Markdown files, Mermaid is the lighter answer. If they are reviewed, annotated, and expected to persist across releases, the editable output is the point.

Licence, maintenance and what upgrading costs you

The repository is MIT licensed, which permits commercial use and modification.. The last push was on 2026-10-02, and the most recent releases are v3.4.2 on 2026-10-11, v3.4.0 on 2026-09-14 and v3.3.0 on 2026-09-11. The version numbers also tell you the practical upgrade cost: this is a 3.x project shipping point releases, and the feature set includes a `sync` command that updates existing diagrams. Before upgrading, check the CHANGELOG.md at the repository root, which the top-level layout shows is present. If you have hand-tuned coordinates in production diagrams, treat an upgrade as something to test against a copy rather than a routine bump.

Editorial conclusion

Adopt drawio-skill if your team already edits .drawio files by hand and wants generation, sync and CI checks to run against the same model. Skip it if you need a hosted diagramming service or you cannot install the draw.io desktop CLI, since the skill depends on that binary for export and for Mermaid conversion. Before committing to it, verify three things: that your draw.io desktop build is version 30 or newer so Mermaid conversion and the ELK layout pass are available, that `diagramctl sync` preserves the coordinates in one of your own hand-tuned files, and that your CI runner can run the CLI headlessly, which on Linux means xvfb is installed.

Frequently asked questions

Official sources

1. Agents365-ai/drawio-skill on GitHub
2. License: MIT
3. Project website
4. README
5. Releases