How to use drawio-skill: install, generate and sync diagrams

What you need before you start

drawio-skill runs inside an AI agent. It needs an agent that supports the Agent Skills format, such as Claude Code or Cursor, and it needs the draw.io desktop CLI. The README treats the CLI as a core requirement, so plan to install it rather than trying to skip it.

Python is also listed as a prerequisite.

• An agent that supports Agent Skills, such as Claude Code or Cursor
• The draw.io desktop CLI, version 30 or later recommended
• Python

Install the draw.io desktop CLI

On macOS the README gives a single Homebrew command. Windows users download the installer from the jgraph drawio-desktop releases page. On Linux you install the .deb or .rpm package from the same releases page, and the README suggests installing xvfb for headless use.

Check the install with drawio --version. Version 30 or later is recommended because it unlocks Mermaid to .drawio conversion and the ELK --layout pass, which are unavailable on version 29 and older. On WSL2 the CLI is the Windows desktop exe reached through /mnt/c, and the skill detects this automatically.

Install the skill into your agent

The simplest route is the skills CLI, which the README says works with any agent. Run it once, using the -g flag as shown.

If you prefer a manual install, clone the repository to a persistent path and link the skill subdirectory into your agent's skills folder. The skill lives in skills/drawio-skill/, so SKILL.md must sit directly under the host entry. Do not clone the repository root into a skills directory. Use cp -R instead of ln -s on hosts that do not follow symlinks.

• Updates via the skills CLI: npx skills update drawio-skill -g
• Linked installs update with git pull in your clone
• Copied installs need a manual refresh

Make your first diagram from a description

After installation, describe the system you want in plain language. The README's example asks for a Transformer encoder-decoder, with layer counts, tensor shapes and colour coding. The more specific the description, the closer the first result tends to be.

The skill plans the layout, generates the .drawio XML, exports the diagram, then checks its own PNG for overlaps, clipped labels and stacked edges. The README says it auto-fixes these for up to 2 rounds and accepts up to 5 rounds of your feedback. Expect to make some manual tweaks at the end.

• Name the components and how they connect
• State the diagram type you want, such as architecture or sequence
• Ask for the export format you need: HTML, PowerPoint or Mermaid

Generate diagrams from real sources

Instead of describing a system, you can point the skill at source files. The README lists Terraform, Kubernetes and docker-compose configs, which become diagrams with official AWS, Azure, GCP and Kubernetes icons. It also lists SQL DDL (turned into an ER diagram), OpenAPI or Swagger, AsyncAPI, Protocol Buffers, GraphQL SDL and GitHub Actions or GitLab CI pipelines.

For live infrastructure, the README mentions snapshots from terraform show -json, docker inspect and kubectl get -o json.

• Terraform, Kubernetes and docker-compose files
• SQL DDL to ER diagram
• OpenAPI/Swagger, AsyncAPI, Protocol Buffers, GraphQL SDL
• GitHub Actions and GitLab CI pipelines

Keep diagrams in sync and check architecture rules

When the source changes, diagramctl sync updates changed nodes and relations while keeping tuned coordinates, styles and annotations. The README says removals stay reviewable by default, so check them before accepting.

For teams that keep diagrams in version control, the README describes Diagram-as-Test: YAML or JSON architecture rules, such as Internet-to-database access, cycles, orphans and trust boundaries, enforced by an official GitHub Action on each pull request. Drift diffs compare two diagrams or two live snapshots.

• Sync keeps manual layout
• Removals are reviewable by default
• CI rules cover access paths, cycles, orphans and trust boundaries