KEEP IT HANDS-ON functional βœ“ tested 2026-10-02
// sandboxed in macOS (host) Β· aarch64 Β·install log Β·functional log

drawio-skill

by Agents365-ai · https://github.com/Agents365-ai/drawio-skill · MIT · vv3.4.0 · updated 2026-10-01
Don't install your next skill blind. One email a week: what's worth installing.

Twenty of twenty probes passed, including the hard ones: layout-preserving sync and a policy gate that fails closed.

⚙ ⚙ ⚙ ⚙ ⚙ 4 / 5
quality 5/5
documentation 4/5
setup 4/5
value 5/5
ecosystem fit 4/5
// bottom line

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.

Get the skill digest The best and the broken from 100+ hands-on tests. One email a week.
install via skills CLI
$npx skills add Agents365-ai/drawio-skill -g

README default, verified from GitHub source

or clone directly
$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.

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.

Full sandbox log β†’

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.

Full sandbox log β†’

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.

Full functional log β†’

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

  1. 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-skill works the same.
  2. Check the environment: python3 scripts/diagramctl.py doctor from the skill directory. Core workflows need only Python 3; the doctor reports optional binaries without launching them.
  3. Optional, for the full experience: brew install --cask drawio (native export, Mermaid conversion; version 30+ recommended) and brew install graphviz (automatic layout for large graphs). Linux headless needs xvfb.
  4. First diagram: python3 scripts/diagramctl.py build model.json --from ir -o out.drawio, then python3 scripts/validate.py out.drawio --score. Policy rules via diagramctl.py test --rules policy.yml and the composite GitHub Actions for CI.

Alternatives

  1. 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.
  2. 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.
  3. Mermaid in your README - zero-install, text-first, diff-friendly. Prefer when editability in a GUI matters less than version-control nativeness.
  4. 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.
// review provenance
reviewed by
GearScope
tested
2026-10-02 · macOS (Apple Silicon)
last verified
2026-10-02
depth
HANDS-ON
sponsorship
none, ever
// share this review
// feedback
was this review helpful?

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.