drawio-skill
Twenty of twenty probes passed, including the hard ones: layout-preserving sync and a policy gate that fails closed.
This is the most complete diagram skill GearScope has tested: deterministic generation, a fail-closed architecture policy gate, sync that preserves manual layout byte for byte, and a stdlib-only core that runs on stock Python. The polished-export half needs the draw.io desktop binary, and three version surfaces have drifted apart, but neither changes the verdict. Install it if your diagrams describe real systems that change.
$npx skills add Agents365-ai/drawio-skill -g
README default, verified from GitHub source
$git clone --depth 1 https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill
9.2MB, skill payload itself is 1.2MB
install if
- Platform and DevOps engineers maintaining architecture diagrams. The Terraform/K8s/compose importers plus layout-preserving sync directly attack diagram rot, and the policy actions enforce rules on every PR.
- Teams that need editable .drawio artifacts, not screenshots. Output stays a real drawio file your architects can hand-tune, with provenance and semantic metadata preserved through syncs.
- Bilingual English/Chinese teams. The README, demo assets, and label variants (per-node zh labels in the IR) treat Chinese as a first-class case.
- Anyone wiring diagram workflows into an MCP host. The stdlib-only MCP server exposes all 9 semantic tools with no daemon and no npm/pip dependencies.
skip if
- Diagrams-as-code purists. If you want git-diffable text that renders on commit, plain Mermaid or PlantUML with no binary dependency does that with less machinery.
- Users who just want a quick PNG and will never edit it. The polished export path needs the draw.io desktop CLI; without it you get valid .drawio XML and a DOM-verification workflow, not rendered images.
- Locked-down headless CI that cannot run Electron. The policy and validation gates work fine there, but export and diff-image rendering need the desktop binary plus xvfb.
What It Does
drawio-skill is a single Agent Skills package (one 148-line SKILL.md routing to 55 Python scripts at 11,436 lines, 20 reference docs at 2,282 lines, a 10,446-entry shape index, and 5 style presets) that produces editable .drawio files rather than flattened pictures. It converts natural language, Diagram IR JSON, Terraform, Kubernetes, docker-compose, SQL DDL, OpenAPI, AsyncAPI, Protobuf, GraphQL, Python, JS, Go, and Rust into diagrams, then keeps them honest over time: incremental sync that preserves manual layout, multi-view projection from one model, YAML architecture policy tests, dependency queries, failure simulation, and accessible HTML walkthroughs. A stdlib-only MCP server exposes the same workflows to Claude Desktop, Cursor, VS Code, and Codex. The repo sits at 9,792 stars and 687 forks (API-verified 2026-10-02), was created 2026-03-03, has roughly 286 commits from 10+ contributors, 16 tagged releases, and zero open issues.
The Good
Every gate we attacked failed closed, and every determinism claim held. Building the same IR twice produced byte-identical files (md5 46f83c38d3f06d0f1d5fbf6055eb5480). A planted policy violation (public actor reaching a database directly) made diagramctl test exit 1 with a named rule, a severity, and a suggested fix ("insert an authenticated gateway/service boundary"), while the compliant fixture passed at exit 0. A drawio file with a dangling edge made validate.py exit 1 with a structured E-DANGLING-END error naming the missing cell. Tools that check things but always exit 0 are decoration; these are real gates.
The headline sync claim is true at the byte level. We built the repo's own sync baseline, then synced the v2 source (one new node, one new edge) into it. The output grew from 12 to 16 cells while the coordinates of every unchanged node stayed byte-identical (x="60" y="80", x="290" y="80", x="60" y="230" before and after). Incremental updates that discard your hand-tuned layout are the failure mode that makes generated diagrams abandoned diagrams, and this skill addresses it directly.
The test culture is the deepest in the diagram lane. 218 stdlib-only unit tests run in 4.6 seconds on the macOS system Python 3.9.6, with 10 skips that are documented opt-ins for the Electron-based export binary. tests/README.md maps each script to what its tests lock in (Soundex codes, CJK URL round trips, title-exact shape ranking). docs/DOGFOOD_V3.md is a committed self-test of the skill against its own scripts directory; we replicated it and got 45 nodes and a clean validation. CI runs the suite on every push touching skill paths, and the repo ships two reusable composite GitHub Actions (architecture-test and diff) for enforcing diagram rules in your own PRs.
Honesty is baked into the contracts. doctor reports the drawio and Graphviz binaries as missing without probing them ("safe in macOS sandboxes"). The MCP server deliberately does not expose native PNG export because it launches the Electron GUI. The whatif reference states the simulation "is deterministic reachability, not a production reliability simulation," and the SKILL.md instructs agents not to present inferred semantic findings as verified runtime facts. The whatif semantics are exact in our probes: failing the order service impacted its database and Stripe while an edge marked isolates_failure: true correctly spared inventory, and failing the sink database impacted nothing.
Provenance and packaging are clean. The shape index carries a NOTICE file attributing its 10,446 shapes to jgraph/drawio-mcp under Apache-2.0 with a regenerate-and-regzip recipe. The README is bilingual (English plus a full Chinese README), the GitHub Pages docs site is live (HTTP 200), the changelog holds 56 entries across 16 lockstep releases, and PR #135 (2026-10-01) documents its frontmatter-only disable-model-invocation change as deliberately version-free. The skills.sh canonical entry carries 4,379 installs.
The Bad
Three version surfaces have drifted apart. SKILL.md metadata says 3.4.0, the MCP initialize handshake reports 3.1.0 (hardcoded SERVER_INFO at line 23 of diagramctl_mcp.py, stale through four releases), and .codex-plugin/plugin.json says 2.3.0. The repo's own test_declared_versions_match only pins SKILL.md against the changelog, so the other two surfaces rot silently. Anyone auditing installed versions over MCP or through the Codex plugin directory sees months-old numbers.
The polished half of the pipeline depends on an Electron binary we could not test. Final PNG/SVG/PDF export, the self-check-and-auto-fix vision loop, Mermaid-to-drawio conversion (needs draw.io 30+), and Graphviz autolayout all require the draw.io desktop CLI, which is not installed on this host; headless Linux additionally needs xvfb per the README. The core IR/XML/policy/sync/query workflows are stdlib-only and fully verified, but reviewers should know the render path is a GUI-adjacent dependency, and the skill's own SKILL.md is upfront about sandbox crashes there.
AI logo insertion points at a CDN by default. aiicons.py emits drawio image styles referencing unpkg URLs (@lobehub/icons-static-svg@1.91.0), so diagrams render with AI logos only when online unless --embed is passed. Everything else in the skill is offline; this one path silently is not.
Auto-trigger is off and one install rail was removed. PR #135 set disable-model-invocation: true, so hosts will not auto-select the skill; users must invoke it explicitly (a defensible anti-nuisance choice, but a discovery cost). The 3.4.0 changelog also removed the Claude plugin marketplace distribution in favor of npx skills add, which works, but plugin-marketplace users now have no manifest to point at.
Smoke Test Results
Host-based runs on macOS (aarch64), stock Python 3.9.6, Node 24 for the install rail. No sandbox daemon was available, so scripts ran directly on the host with full logs captured; scripts and logs ship in the repo under sandbox/skills/drawio-skill/.
Run A - Fresh sandbox, no deps preinstalled
$ git clone --depth 1 https://github.com/Agents365-ai/drawio-skill.git
β
PASS: 9.2MB shallow clone
$ python3 scripts/diagramctl.py doctor
β
PASS: exit 0; JSON reports python ok, and honestly lists drawio/graphviz as missing
$ python3 -m unittest discover -s tests
Ran 218 tests in 4.607s ... OK (skipped=10)
β
PASS: stdlib suite green on stock macOS Python, zero pip installs
$ python3 scripts/validate.py assets/demo-erd.drawio --score
0 error(s), 0 warning(s) ... score: 0 (0 through-vertex, 0 crossings, 0 overlaps)
β
PASS: shipped demo validates clean with a zero-defect score
Pass rate: 4 of 4. A bare clone with no dependencies installed delivers working core workflows.
Run B - Sandbox with deps preinstalled
Node and npx available; the skill core needs nothing beyond Python.
$ npx -y skills add /tmp/drawio-skill-review --agent claude-code -y
β
PASS: lands SKILL.md plus the full package at .claude/skills/drawio-skill
$ find .claude/skills/drawio-skill -type f | wc -l
79
β
PASS: all 79 skill files installed
$ diff -rq <repo>/skills/drawio-skill .claude/skills/drawio-skill
(empty output)
β
PASS: installed payload byte-identical to the repository
$ npx -y skills add Agents365-ai/drawio-skill --agent claude-code -y
β
PASS: README's documented GitHub-source install works
$ python3 mcp-stdio-client.py python3 scripts/diagramctl_mcp.py stdio
serverInfo: {"name": "drawio-skill", "version": "3.1.0"} ... tool count: 9
β
PASS: MCP handshake, exactly the 9 documented tools
$ (same client) --call doctor
β
PASS: live tool call returns the doctor JSON
Pass rate: 7 of 7. This is the badge run: install is byte-faithful from both local and GitHub sources, and the MCP surface matches its documentation. The serverInfo version string (3.1.0) is the drift evidence cited in The Bad.
Run C - Functional verification (does it do what it claims?)
$ diagramctl.py build checkout.ir.json --from ir (twice) && md5 a1 a2
46f83c38d3f06d0f1d5fbf605eb5480 (both files)
β
PASS: byte-deterministic generation
$ diagramctl.py test bad.drawio --rules policy.yml
errors: 1 ... no-direct-internet-to-database ... "fix": "insert an authenticated gateway..." (exit 1)
β
PASS: policy gate fails closed with named rule and fix
$ validate.py broken.drawio --score
error: [E-DANGLING-END] edge 'e1' target 'missing-node' does not exist (exit 1)
β
PASS: structural validator fails closed
$ diagramctl.py sync base.drawio sync-source-v2.ir.json --from ir
12 -> 16 cells; unchanged coordinates byte-identical
β
PASS: sync preserves manual geometry while adding content
$ diagramctl.py build main.tf --from terraform --group && validate.py
6 nodes, 6 edges, 0 errors
β
PASS: Terraform import validates clean
$ diagramctl.py whatif ir.json --fail orders / --fail orders-db
impacted: [orders-db, stripe] / impacted: []
β
PASS: failure propagation exact, isolates_failure honored, sink fails silently
$ diagramctl.py story ir.json -o walkthrough.html
0 external URLs, 7 aria-labels, 6 tabindex attributes
β
PASS: self-contained, keyboard-accessible story HTML
$ diagramctl.py build scripts --from python --group (self-index)
45 nodes, 1 edge, 0 errors
β
PASS: replicates the repo's committed DOGFOOD_V3 self-test
$ (plus the compliant policy pass at exit 0)
β
PASS
Functional pass rate: 9 of 9.
What the runs tell you
Everything testable without the draw.io desktop binary works, fails closed where it should, and reproduces byte for byte. The untested surface is exactly the Electron-dependent half: native export, the vision self-check loop, Mermaid conversion, and autolayout. One initial FAIL in our own harness (story HTML accessibility count) turned out to be a probe counting lines instead of occurrences; corrected, the output has 7 aria-labels on 4 dense lines.
Setup Walkthrough
- Install the skill:
npx skills add Agents365-ai/drawio-skill -g(verified from GitHub source; lands all 79 files byte-identical). Manual clone into~/.claude/skills/drawio-skillworks the same. - Check the environment:
python3 scripts/diagramctl.py doctorfrom the skill directory. Core workflows need only Python 3; the doctor reports optional binaries without launching them. - Optional, for the full experience:
brew install --cask drawio(native export, Mermaid conversion; version 30+ recommended) andbrew install graphviz(automatic layout for large graphs). Linux headless needs xvfb. - First diagram:
python3 scripts/diagramctl.py build model.json --from ir -o out.drawio, thenpython3 scripts/validate.py out.drawio --score. Policy rules viadiagramctl.py test --rules policy.ymland the composite GitHub Actions for CI.
Alternatives
- archify (reviewed 4.5/5) - validated, self-contained HTML diagrams from typed JSON IR. Prefer it when you want web-native output and browser viewing rather than drawio editing.
- jgraph/drawio-mcp - the official draw.io makers' MCP server (3,097 skills.sh installs). Smaller scope; notably, drawio-skill vendors and attributes its shape search index from this project.
- Mermaid in your README - zero-install, text-first, diff-friendly. Prefer when editability in a GUI matters less than version-control nativeness.
- nicobailon/visual-explainer (reviewed 4.5/5) - styled HTML pages for diff reviews, tables, and recaps. Adjacent lane: explainer output rather than maintained architecture models.
Reviews stay honest because nobody pays us to publish them. If this one saved you time, throw a coin.
Tip the reviewer- reviewed by
- GearScope
- tested
- 2026-10-02 · macOS (Apple Silicon)
- last verified
- 2026-10-02
- depth
- HANDS-ON
- sponsorship
- none, ever
Don't install your next skill blind.
Every week: the shortlist of skills worth installing β and the ones to skip β from 100+ hands-on tests. No spam, no affiliate links.