drawio-diagram-builder: an agent skill for editable draw.io figures

The gap drawio-diagram-builder fills between a prompt and a usable figure

Ask a language model to emit draw.io XML and you get XML. Whether the result is readable is a separate question, and the README lists the usual failures directly: text overlapping or escaping its box, arrows routed through the wrong region, loop arrows that look wrong, missing or inconsistent icons, and reference figures embedded as flat images instead of redrawn as editable objects. It also notes that large diagrams crash on Windows with long-URL failures, which is a rendering-path problem rather than a modelling one.

The skill exists to close that gap with a repeatable loop rather than a better prompt. Its audience is narrow and identifiable: people producing method overviews from papers, architecture and data-flow figures from repositories, and ML pipeline diagrams showing stages, models, datasets and training loops. If your output has to survive an editor opening the .drawio file afterwards, that is the target case. If a rough sketch would do, the machinery here is heavier than the job.

Brief, XML, local preview, screenshot, defect log: the actual loop

The pipeline described in the README runs in one direction. Inputs (text, images, code, screenshots, one or more visual references) are synthesized into a diagram brief. The agent writes editable XML from that brief. The XML is previewed through a local URL rather than a giant encoded one, which is the fix for the Windows long-URL crash. The preview is screenshotted, the agent reviews what it sees for visible and semantic defects, fixes them, and repeats. A validation script runs at the end.

Two protocols sit on top of that loop. For reference-image replication the skill requires the agent to write a visual spec, a coordinate layout grid, an asset ledger and a defect log before drawing, and the handoff must include a screenshot-reviewed defect log rather than merely valid XML. For prompt, paper, codebase or mixed-input work there is a self-supervision protocol: classify each input as content, structure, style, layout or asset evidence, define connector semantics before drawing any arrow, then inspect screenshots for requirement mismatches, arrow meaning, text overlap, icon coherence, style drift and regressions.

That classification step is the most opinionated part of the design. It forces the agent to decide what a connector means (fan-in, fan-out, feedback loop, grouped route, arrowhead direction) before it draws one, which is where most generated figures quietly go wrong. It is also where the skill's main cost lives, since every pass needs a rendered screenshot to judge.

Installing the skill with npx skills add, or by hand

The README gives a single-command install for agents that support the skills convention. Run it from a shell where npx is available:

npx skills add Will-hxw/drawio-diagram-builder-skill

The repository layout shows the payload under skills/drawio-diagram-builder/, which is the directory npx skills add is meant to discover. If you would rather hand the job to a coding agent, the README supplies a prompt to paste into Codex, Claude Code or another local agent, asking it to install, run the smoke test and report the exact skill path.

Manual installation is a clone plus a copy. For Claude Code, the README copies the skill directory into ~/.claude/skills/:

git clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git
cp -R drawio-diagram-builder-skill/skills/drawio-diagram-builder ~/.claude/skills/

On Windows the Codex path uses PowerShell and copies into $env:USERPROFILE\.codex\skills\:

git clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git
New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
Copy-Item -Recurse -Force .\drawio-diagram-builder-skill\skills\drawio-diagram-builder "$env:USERPROFILE\.codex\skills\"

macOS and Linux use mkdir -p "$HOME/.codex/skills" followed by the same cp -R, and the README says to restart the agent after copying. Verification is a script that compares the installed copy against the canonical repository:

python <installed-skill-dir>\scripts\check_skill_update.py

If that reports OUTDATED or UNKNOWN, the README's instruction is to reinstall from the canonical repository rather than hunting for specific files or text snippets. A first real use is a prompt, and the README's examples are the safest starting point:

Use $drawio-diagram-builder to read this paper section and create an editable draw.io method overview.

Expect the agent to produce XML, open a local preview, screenshot it and start listing defects. The prerequisites table is explicit: Python 3.7+ for the preview and validation scripts, browser automation (Playwright MCP, Puppeteer or similar) for the screenshot loop, and internet access because the preview loads https://embed.diagrams.net/. All the helper scripts are plain Python 3 and need no pip packages.

Where the skill stops: no browser, no loop, no decomposed icons

The README states the limitation plainly: without browser automation the agent can still generate .drawio XML but cannot visually verify the result, and the iterative refinement loop is described as the skill's main value. Strip the browser out and you are left with the same unverified XML you could have asked any model for. That is the sharpest failure mode here, and it is a hard dependency rather than a configuration preference.

There is a second, subtler limit in the icon set. The bundled Tabler SVG assets are vector, but the README says their internals are not decomposed into draw.io primitive cells, so they do not behave as fully editable object trees inside the canvas. The documented workaround is to use the primitive recipes when object-level editability matters, which means a choice per icon between visual fidelity and editability.

The README also declines to promise one-shot perfection, saying high-fidelity reproduction takes multiple screenshot-feedback passes. Treat that as a budget statement: each pass costs a render, a screenshot and a review. And the skill is not a draw.io replacement, nor affiliated with diagrams.net or JGraph. If you need a hosted editor with collaboration or a general diagramming application, this is not it.

How this differs from opening draw.io and drawing, or from a plain MCP server

The obvious alternative is draw.io itself. diagrams.net gives you a canvas, shape libraries, manual routing and instant visual feedback from your own eyes; the drawio-diagram-builder skill gives you no canvas to draw on and instead automates the generate, render, inspect, fix cycle. The difference is who does the looking. With the editor, you do. With this skill, the agent does, and it needs a screenshot to do it. That makes the skill better for figures derived from a paper or a codebase where the structure is already written down, and worse for anything where you would rather nudge a box two pixels left.

A generic browser-automation or MCP setup is the other comparison, and it is closer than it looks. An MCP server gives an agent the ability to drive a browser; it says nothing about what a good research figure looks like, what a connector means, or when a reference image should be redrawn rather than embedded. The skill's contribution is the protocol layer: the visual spec, coordinate grid, asset ledger and defect log for replication, and the input classification and connector-semantics step for everything else. If you already have a capable agent and a browser tool, you are supplying the transport; the skill supplies the discipline.

Maintenance, version checking and the MIT licence

The repository is not archived, and the last push was on 2026-07-02, which is roughly two and a half months before today. There are no retrieved releases, so upgrades are tracked through the repository rather than a versioned release channel. The skill carries a VERSION file as an installed marker, and check_skill_update.py is the supported way to compare an installed copy against the canonical repository. That script is the upgrade mechanism you should plan around: run it after a reinstall, and treat OUTDATED or UNKNOWN as a signal to reinstall rather than to patch files by hand.

Because installation is a directory copy, an upgrade is a re-copy, and any local edits inside the skill directory will be overwritten. Keep customisations outside skills/drawio-diagram-builder/ if you make any.

The project is MIT licensed, and the bundled Tabler icon subset is described as MIT-licensed too. MIT is permissive, but the README does not discuss attribution requirements for the icon subset in generated figures or what happens to licence notices when the skill directory is copied into an agent's skills folder. If you are publishing figures commercially, read the LICENSE file and the icon set's own terms rather than assuming the top-level licence settles it. Nothing here is legal advice.

Editorial conclusion

Adopt it if you already run Codex, Claude Code or a similar local coding agent with browser automation and you need research-style figures that stay editable in draw.io, because the screenshot loop is where the value sits. Skip it if you want a one-shot diagram, if you cannot give the agent a browser, or if you only need icons pasted into a canvas. Before trusting it on real work, clone the repository, run the bundled smoke test, then run python <installed-skill-dir>/scripts/check_skill_update.py against the installed copy and confirm it does not report OUTDATED or UNKNOWN.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Will-hxw/drawio-diagram-builder on GitHub