The Problem

Teams that need architecture, UML, or workflow diagrams spend hours manually placing shapes, hunting vendor icons, and converting code or IaC into a visual form. The process is error‑prone, repeats across projects, and rarely produces an editable draw.io file that can be further refined.

What This Does

drawio-skill turns a natural‑language prompt (or a code/IaC artifact) into a native .drawio XML file and optionally exports PNG, SVG, PDF or JPG via the draw.io desktop CLI.

  • Presets for 11 diagram families live under skills/drawio-skill/references/ (e.g., diagram-types.md, style-presets.md).
  • Shape lookup (assets/shape-search-example.png) and brand‑specific icons are stored in skills/drawio-skill/data/ (databricks-icons.json, lobe-icons.json).
  • Core conversion scripts live in skills/drawio-skill/scripts/ – each script is a thin CLI wrapper around a functional module (e.g., drawio2mermaid.py, prdiff.py, buildup.py).

The skill can:

  1. Generate a full ERD, UML class diagram, C4 system view, BPMN flow, or network map from a single prompt.
  2. Parse Python, JavaScript/TS, Go, Rust source trees (pyimports.py, jsimports.py, goimports.py, rustimports.py) to produce import‑graph layouts.
  3. Convert Terraform, Kubernetes, or Docker‑Compose manifests into architecture diagrams with official cloud icons (tfimports.py, k8simports.py, dockerimports.py).
  4. Turn SQL DDL into crow‑foot ER diagrams (sqlerd.py).

All outputs are editable in draw.io because the scripts generate the underlying XML rather than a raster image.

How It Is Wired

Entry point – The skill is invoked through the Agent‑Skills runtime, which reads the metadata in skills/drawio-skill/SKILL.md. The runtime calls the appropriate script based on the action field in the request payload.

Core dispatch – Each script follows a common pattern:

# example: skills/drawio-skill/scripts/drawiodiff.py
from drawio_skill import drawiodiff   # internal module
if __name__ == "__main__":
    drawiodiff.main()
  • drawiodiff.main() (in skills/drawio-skill/scripts/drawiodiff.py) parses CLI arguments, loads the source .drawio files, calls drawiodiff.compute_diff() (same file), and writes a diff diagram.
  • The drawio2mermaid.py script calls drawio2mermaid.convert() which reads a .drawio XML, extracts graph elements, and emits Mermaid text that the draw.io CLI later renders back to a .drawio file.
  • IaC scripts (tfimports.py, k8simports.py, dockerimports.py) share the helper composeimports.py for building a resource‑graph model, then feed it to autolayout.py which runs Graphviz to compute node positions.
  • Shape resolution is centralized in scripts/shapesearch.py, which loads data/shape-index.json.gz (a 10 k+ shape catalog) and returns the exact mxgraph identifier for a given vendor+type pair.

Data flow –

  1. Input (prompt, source files, or IaC) → script argument parser.
  2. Parsing → language‑specific module (pyimports, tfstate, sqlerd).
  3. Model → generic graph objects (autolayout, buildup).
  4. Layout → Graphviz (autolayout.py) or deterministic algorithms (seqlayout.py).
  5. Export → drawiohtml.py writes .drawio XML; optional drawio2pptx.py or encode_drawio_url.py produce PNG/SVG via the draw.io CLI.

The only module with a wide blast radius is autolayout.py – it is called by every script that produces a diagram, so changes to its layout heuristics affect all 11 presets and every import‑graph use case.

No circular imports were detected; the script directory forms a clear star topology around autolayout.py and the shape‑search helper.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/drawio-skill.git
cd drawio-skill

# Install Python dependencies (present in pyproject.toml)
pip install -r requirements.txt   # or `uv pip install -r requirements.txt`

# Verify the CLI works (example: generate a UML class diagram)
python -m skills.drawio-skill.scripts.drawio2mermaid \
    --prompt "UML class diagram of an e‑commerce order service" \
    --output demo-uml-class.drawio

Configuration – The skill reads optional JSON files in skills/drawio-skill/data/ for custom icon sets; no environment variables are required for the core functionality.

Running as an Agent Skill – Deploy the skills/drawio-skill folder to any Agent‑Skills runtime. The runtime will locate SKILL.md for metadata and invoke the appropriate script based on the action field.

Real‑World Use

A CI pipeline can generate up‑to‑date architecture diagrams on every merge:

# .github/workflows/drawio-pr-diff.example.yml (provided)
- name: Generate IaC diagram
  run: |
    python -m skills.drawio-skill.scripts.tfimports \
      --dir terraform/ \
      --output infra.drawio
- name: Publish diagram
  uses: actions/upload-artifact@v3
  with:
    name: infra-diagram
    path: infra.drawio

The diff workflow (.github/actions/drawio-diff/action.yml) then posts a visual diff to the PR comment, surfacing unintended infrastructure changes.

Code Health & Issues

  • No structural red flags: tests (tests/), CI (.github/workflows/tests.yml), license (LICENSE), and lockfile (requirements.txt) are present.
  • Test coverage is limited to a subset of scripts (test_buildup.py, test_compress.py, etc.); many conversion scripts lack direct unit tests.
  • The repository does not include a pyproject.toml or setup.cfg; dependency management relies on a plain requirements.txt, which can cause version drift.
  • No explicit runtime configuration file; all behavior is driven by CLI arguments, which may hinder automated configuration in larger deployments.

The Bottom Line

drawio-skill provides a pragmatic, script‑driven bridge from natural language or code/IaC artifacts to fully editable draw.io diagrams, with solid test scaffolding and CI. The core layout engine (autolayout.py) is the primary change surface; extending or customizing presets will most often involve editing the reference markdown files or adding new icon JSON. Teams that already use draw.io and need repeatable diagram generation from codebases or infrastructure definitions will find this repository immediately useful, though they should augment the test suite and consider formalizing dependency management before production deployment.