drawio-skills

drawio-skills

An open-source, deterministic diagram engineering skill for AI coding agents.

drawio-diagram-engineer turns a compact Diagram IR into editable .drawio XML, validates the result with a measurable quality gate, and exports through draw.io Desktop when available. The project is intentionally compiler-oriented: the structured IR is reviewable source, and .drawio is a reproducible build artifact.

Status: v1.7. The stable Diagram IR v1 contract now adds date-scoped delegated reviewer trust, append-only Merkle evidence, a searchable static architecture portal, Prometheus/OTLP governance metrics, and Structurizr/ADR exchange while retaining ERD, HA, federated review, round-trip editing, and signed attestations.

Why another draw.io skill?

Agents365-ai/drawio-skill is an excellent broad toolbox and a key inspiration for this project. This repository explores a different center of gravity:

• IR-first: natural language and future code/IaC importers target one versioned schema.
• Deterministic: semantic IDs and stable layout make diffs and regeneration predictable.
• Quality-gated: structural defects and layout collisions produce machine-readable findings and a 0–100 score.
• Agent-portable: the core JSON workflow uses only the Python standard library.
• Safe evolution: the editable source and generated artifact can be reviewed independently.

This is an independent implementation. No source code from the inspiration repository is included.

Five-minute quick start

git clone https://github.com/uulab-official/drawio-skills.git
cd drawio-skills
python3 scripts/install_skill.py
python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py doctor

Create a starter, edit the JSON to describe your system, and build the complete deliverable:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  init architecture -o my-system.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  build my-system.json -o build/my-system --strict

The bundle is ready to review or commit:

build/my-system/
├── my-system.drawio   # editable diagram
├── diagram.json       # normalized Diagram IR
├── previews/          # dependency-free SVGs, one per page
├── audit.json         # quality score, findings, and repairs
├── security.json      # credentials, unsafe links, and XML safety gate
└── bundle.json        # stable artifact manifest

Use init blueprint, init erd, or init ha for an architecture definition pack, database model, or HA/failover design. SQL DDL works without a starter:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  build schema.sql -o build/database --strict

Desktop-quality PNG/SVG/PDF/JPG export requires draw.io Desktop. The core bundle workflow does not. Native output is structurally verified before render succeeds:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  render build/my-system/my-system.drawio -o my-system.png \
  --report my-system.export.json

Use verify-export to validate an artifact made on another machine. See the Desktop export contract.

Round-trip draw.io editing

Generated .drawio files carry versioned semantic metadata for pages, groups, nodes, edges, ERD fields, cardinalities, HA relationships, and cross-page links. Move, rename, reconnect, or restyle supported elements in draw.io, then recover reviewable Diagram IR:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  extract architecture.drawio \
  -o architecture.diagram.json \
  --report architecture.extraction.json \
  --strict

lossless: true means every semantic page and cell was recovered from supported compiler metadata. Older or hand-authored files are still converted using deterministic shape, style, geometry, and containment inference; strict mode exits 3 so those assumptions cannot silently enter source control. See the round-trip editing contract.

Portable collaborative review

Turn any complete bundle into a script-free HTML/SVG review site:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  publish build/my-system \
  -o build/my-system-review \
  --strict

The site provides multi-page navigation, stable semantic links such as #node-api-gateway, audit/security/extraction/export status, machine-readable evidence, reviewer-decision lifecycle, composed policy evaluation, owner-routed SARIF, source provenance, and a Markdown check summary. It opens locally and requires neither draw.io Desktop nor a web service.

Carry reviewer decisions across regeneration and apply accepted/resolved updates by stable annotation ID:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  publish build/my-system \
  -o build/my-system-review-v2 \
  --carry-review build/my-system-review \
  --annotations review-updates.json \
  --strict

Compose organization and team policy packs, route findings, and fail only on explicit gates:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  publish build/my-system \
  -o build/my-system-review \
  --policy organization-policy.json \
  --policy team-policy.json \
  --ownership review-ownership.json \
  --evaluation-date 2026-07-29 \
  --fail-on-policy \
  --fail-on-unowned-findings \
  --strict

Scoped exceptions record a reason, owner, expiry, and optional page/cell selectors. Waived rules remain visibly non-compliant, and expired error-level exceptions block policy. Every site includes reports/policy.json, reports/ownership.json, reports/summary.md, and SARIF 2.1.0 reports/findings.sarif. A pinned GitHub Pages workflow recipe appends the summary to the job, retains an immutable diagram-review-<commit-sha> artifact, and deploys the same evidence directory.

Use repository ownership only as a fallback after semantic routes and emit a ready-to-send GitHub Checks request:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  publish build/my-system \
  -o build/my-system-review \
  --ownership review-ownership.json \
  --codeowners .github/CODEOWNERS \
  --source-path architecture/my-system.json \
  --source-revision "$GITHUB_SHA" \
  --source-repository "$GITHUB_REPOSITORY" \
  --github-checks \
  --strict

Every review now includes an in-toto statement that binds review.json to the source revision and bundle digest. Sign and verify it locally with OpenSSH:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  attest-review build/my-system-review --signing-key review-signing-key

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  verify-review-attestation build/my-system-review \
  --allowed-signers .github/review-signers \
  --identity architecture@example.com

Test policy behavior before publication:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  policy-test architecture/policies/tests.json \
  -o build/policy-tests.json --strict

Record independently signed architecture and security approvals, then verify quorum:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  record-approval build/my-system-review \
  --ledger build/my-system-approvals.json \
  --identity architect@example.com --role architecture \
  --timestamp 2026-07-29T03:00:00Z \
  --reason "Architecture reviewed" \
  --signing-key architecture-review-key \
  --minimum-approvals 2 \
  --required-role architecture --required-role security

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  verify-approval-ledger build/my-system-review \
  --ledger build/my-system-approvals.json \
  --allowed-signers .github/architecture-reviewers

Federate immutable reviews and export dashboard-ready governance history:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  catalog-reviews services/*/review -o build/architecture-catalog.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  governance-trends \
  --snapshot 2026-06-30=history/june/review \
  --snapshot 2026-07-29=history/july/review \
  -o build/governance-trends.json \
  --csv-output build/governance-trends.csv

Organization rules use a data-only protocol. The engine emits bounded review facts and validates the returned JSON without importing or executing provider code:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  rule-provider-request build/my-system-review -o build/provider-request.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  verify-rule-provider-result \
  build/provider-request.json build/provider-result.json \
  -o build/provider-report.json

See the governance lifecycle and federation contract.

Organization-scale trust and discovery

Every publish site now carries a one-review evidence catalog, governance JSON/CSV, Prometheus text, OTLP JSON, a metrics manifest, a bounded rule-provider request, and a verified Merkle transparency log. The following commands extend those portable defaults across repositories and organization trust roots.

Pin reviewer authority to organization roles, teams, trust epochs, and exact OpenSSH trust-root files:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  verify-delegated-approvals build/my-system-review \
  --ledger build/my-system-approvals.json \
  --trust-policy architecture/review-trust.json \
  --trust-root .github/review-trust \
  -o build/delegated-approval-report.json

Create independently verifiable, append-only evidence and a searchable static catalog:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  transparency-log build/architecture-catalog.json \
  build/my-system-approvals.json \
  -o build/transparency-log.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  catalog-portal build/architecture-catalog.json \
  -o build/architecture-portal

Export governance telemetry without embedding a network client:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  export-governance-metrics build/governance-trends.json \
  --prometheus build/governance.prom \
  --otlp build/governance.otlp.json \
  --report build/governance-metrics.json

Exchange bounded C4 hierarchy and architecture decisions with adjacent tools:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  import-structurizr workspace.json -o architecture.blueprint.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  export-adrs architecture.blueprint.json -o docs/decisions

See the organization-scale contract, trust policy example, Structurizr example, and checked-in architecture portal.

Use an approved review site or bundle as a deterministic visual baseline:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  publish build/my-system \
  -o build/my-system-review \
  --baseline approved-review \
  --fail-on-visual-change

Exit code 7 means at least one page was added, removed, or changed; exit code 8 means an error-level architecture policy failed; exit code 9 means the explicit ownership gate found an unassigned finding. The diagnostic site is still written for CI retention. See the collaborative review contract, governance annotation example, composable policy examples, and ownership example.

Open the checked-in Commerce Platform review site or inspect its machine-readable review manifest.

Architecture blueprint pack

Generate six coordinated architecture pages—System Context, Logical Architecture, Data Flow, Deployment, Network & Security, and Architecture Decisions—from one model:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  blueprint skills/drawio-diagram-engineer/assets/example.blueprint.json \
  -o commerce-blueprint.drawio \
  --ir-output commerce-blueprint.diagram.json \
  --preview-dir commerce-blueprint-previews \
  --strict

The model uses hierarchy, bounded domains, deployment mappings, and security zones to project each view without duplicating its source of truth. See the Blueprint reference.

Preview the generated pages: Context, Logical, Data, Deployment, Network & Security, and Architecture Decisions.

The complete example pack is available as an editable draw.io file, generated Diagram IR, and 100-point audit report.

Crow's Foot ERD

Generate a field-level ERD from the structured model or directly from SQL DDL:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  erd skills/drawio-diagram-engineer/assets/example.erd.json \
  -o commerce-erd.drawio \
  --ir-output commerce-erd.diagram.json \
  --preview-dir commerce-erd-previews \
  --strict

The ERD profile validates primary and foreign keys, composite-key field order, data-type compatibility, nullable/unique flags, and endpoint cardinalities. The editable output uses official draw.io Crow's Foot markers. See the ERD reference.

Open the editable ERD, generated IR, SVG preview, or 100-point audit.

High-availability architecture

Generate separate HA topology and failover views:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  ha skills/drawio-diagram-engineer/assets/example.ha.json \
  -o checkout-ha.drawio \
  --ir-output checkout-ha.diagram.json \
  --preview-dir checkout-ha-previews \
  --strict

The HA profile validates independent failure domains, replica counts, quorum shape, stateful replication, automatic-failover health checks, cross-domain promotion, RTO, and RPO. See the HA reference.

Open the editable HA pack, generated IR, topology, failover flow, or 100-point audit.

Infrastructure and pipeline intelligence

Generate editable topology directly from Terraform, Kubernetes, GitHub Actions, or GitLab CI:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  import ./infra --type terraform -o terraform.diagram.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  import ./manifests --type kubernetes -o kubernetes.diagram.json

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  import . --type github-actions -o delivery.diagram.json

Terraform references become dependency edges. Kubernetes namespaces become groups, with Ingress → Service → workload and workload → configuration/storage relations derived from declared selectors and references. Secret values are redacted. CI jobs are grouped by workflow or stage and ordered from prerequisite to dependent job.

See the complete importer contract, the 20-case infrastructure/CI corpus, and the 25-case legacy importer corpus. Every importer now has at least five deterministic strict-valid fixtures.

Open the editable and audited examples:

• Terraform diagram, SVG, and 100-point audit.
• Kubernetes diagram, SVG, and 100-point audit.
• GitHub Actions and GitLab CI, each with a generated SVG and 100-point audit.

Semantic architecture drift

Compare two Diagram IR versions while ignoring layout-only movement:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  diff approved.diagram.json generated.diagram.json \
  -o drift.report.json \
  --diagram-output drift.drawio \
  --preview-dir drift-previews \
  --fail-on-drift

The report classifies page, group, node, and edge changes by stable semantic ID. The editable view uses green for additions, red dashed shapes for removals, and amber for changes, with text status markers for non-color-only review. See the drift contract, example report, editable view, SVG preview, and 100-point audit.

Deterministic ports and routing

Automatic edges select the side facing their target, distribute fan-out/fan-in attachment points, and choose an orthogonal corridor by node intersections, unrelated edge crossings, bend count, and length. Assign a fixed interface only when the topology requires it:

{
  "id": "monitor-api",
  "from": "monitor",
  "to": "api",
  "style": {
    "source_port": "south",
    "source_offset": 0.5,
    "target_port": "north",
    "target_offset": 0.75
  }
}

The generated draw.io file contains editable waypoints, while the SVG preview and validator consume the same route plan. See the routing contract, source IR, editable example, SVG preview, and 100-point audit.

Organization themes and visual audit

Apply a reusable theme pack and generate a machine-readable QA report:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  audit skills/drawio-diagram-engineer/assets/example.blueprint.json \
  -o commerce-blueprint.audit.json \
  --preview-dir commerce-blueprint-audit \
  --theme-file skills/drawio-diagram-engineer/assets/themes/corporate.json \
  --strict

The audit checks the source plus generated draw.io geometry for contrast, text density, clipping, overlap, and routing risks. It groups findings with targeted repair suggestions and a visual-review checklist. See the style system reference.

Install as an agent skill

In Codex, ask the built-in skill installer to install the skill folder:

$skill-installer install https://github.com/uulab-official/drawio-skills/tree/main/skills/drawio-diagram-engineer

For a cloned repository, the tested installer copies the skill, runs its self-check, and reports whether the agent must restart:

python3 scripts/install_skill.py

Use --mode symlink while developing the skill or --target <skills-directory> for another Agent Skills-compatible client. Existing installations are never replaced unless --force is explicit.

The distributable ZIP is reproducible:

python3 scripts/package_skill.py

This writes dist/drawio-diagram-engineer.zip and its .sha256 checksum.

Tagged releases also include GitHub/Sigstore build provenance. Verify a downloaded ZIP with:

shasum -a 256 -c drawio-diagram-engineer-<version>.zip.sha256
gh attestation verify drawio-diagram-engineer-<version>.zip \
  --repo uulab-official/drawio-skills

Verify the release tag itself from a clone:

git fetch --tags origin
python3 scripts/verify_release_tag.py v1.0.0

The verifier requires an annotated SSH signature trusted by .github/release-signers, confirms the tag subject, and matches the tag version against the tool, package metadata, and changelog. Published releases are immutable: their tag and assets cannot be changed while the release exists.

Compatibility and security

Check or migrate an older unversioned Diagram IR before editing it:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  migrate legacy.json --check

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  migrate legacy.json -o diagram.json --report migration.json

Scan a model, generated .drawio, or complete delivery bundle:

python3 skills/drawio-diagram-engineer/scripts/drawio_tool.py \
  security build/my-system -o build/my-system/security.json --strict

The security gate rejects likely embedded credentials, private keys, unsafe link schemes, DTD/entity declarations, and oversized compressed pages without echoing suspected secret values. HTTP/HTTPS/mail links are listed for review and never fetched. See the compatibility policy and security contract.

Diagram IR

{
  "version": "1",
  "diagram": {"title": "Payments", "direction": "LR", "theme": "colorblind"},
  "groups": [{"id": "platform", "label": "Platform"}],
  "nodes": [
    {"id": "api", "label": "API", "kind": "service", "group": "platform"},
    {"id": "ledger", "label": "Ledger", "kind": "database", "group": "platform"}
  ],
  "edges": [
    {"id": "api-ledger", "from": "api", "to": "ledger", "label": "write", "kind": "data"}
  ]
}

See the IR reference for supported fields.

CLI

drawio_tool.py doctor [--format human|json]
drawio_tool.py init <architecture|blueprint|erd|ha|routing|terraform|kubernetes|github-actions|gitlab-ci> [-o <starter>]
drawio_tool.py build <model|source> [-o <bundle-dir>] [--type auto|...] [--strict]
drawio_tool.py merge-annotations <prior-review|annotations> <updates> -o <merged.json>
drawio_tool.py policy-test <suite.json> [-o <report.json>] [--baseline <report>] [--fail-on-change] [--strict]
drawio_tool.py publish <bundle-dir> -o <review-dir> [--policy <json>]... [--ownership <json>] [--codeowners <file>] [--source-path <path>] [--github-checks] [--strict]
drawio_tool.py attest-review <review-dir> --signing-key <private-key>
drawio_tool.py verify-review-attestation <review-dir> --allowed-signers <file> --identity <id>
drawio_tool.py record-approval <review-dir> --ledger <json> --identity <id> --role <role> --timestamp <UTC> --reason <text> --signing-key <key>
drawio_tool.py verify-approval-ledger <review-dir> --ledger <json> --allowed-signers <file>
drawio_tool.py catalog-reviews <review-dir>... -o <catalog.json>
drawio_tool.py governance-trends --snapshot <date=review-dir>... -o <trends.json> [--csv-output <csv>]
drawio_tool.py rule-provider-request <review-dir> -o <request.json>
drawio_tool.py verify-rule-provider-result <request.json> <result.json> [-o <report.json>]
drawio_tool.py verify-delegated-approvals <review-dir> --ledger <json> --trust-policy <json> --trust-root <dir>
drawio_tool.py transparency-log <artifact.json>... -o <log.json> [--baseline <log.json>]
drawio_tool.py verify-transparency-log <log.json>
drawio_tool.py catalog-portal <catalog.json> -o <portal-dir>
drawio_tool.py export-governance-metrics <trends.json> [--prometheus <text>] [--otlp <json>]
drawio_tool.py import-structurizr <workspace.json> -o <blueprint.json>
drawio_tool.py export-structurizr <blueprint.json> -o <workspace.json>
drawio_tool.py import-adrs <file|dir> -o <json> [--blueprint <blueprint.json>]
drawio_tool.py export-adrs <blueprint.json> -o <directory>
drawio_tool.py migrate <legacy-ir.json> [-o <v1-ir.json>] [--report <report.json>] [--check]
drawio_tool.py security <model|diagram.drawio|bundle-dir> [-o <report.json>] [--strict]
drawio_tool.py compile <ir.json> -o <diagram.drawio> [--theme-file <theme.json>]
drawio_tool.py extract <diagram.drawio> -o <ir.json> [--report <report.json>] [--strict]
drawio_tool.py blueprint <blueprint.json> -o <pack.drawio> [--ir-output <ir.json>] [--preview-dir <dir>] [--theme-file <theme.json>]
drawio_tool.py erd <erd.json|schema.sql> -o <erd.drawio> [--ir-output <ir.json>] [--preview-dir <dir>]
drawio_tool.py ha <ha.json> -o <ha.drawio> [--ir-output <ir.json>] [--preview-dir <dir>]
drawio_tool.py import <source> --type <python|typescript|openapi|sql|compose|terraform|kubernetes|github-actions|gitlab-ci> -o <ir.json>
drawio_tool.py diff <baseline.ir.json> <candidate.ir.json> -o <report.json> [--diagram-output <drift.drawio>] [--preview-dir <dir>] [--fail-on-drift]
drawio_tool.py patch <ir.json> <operations.json> -o <updated.json>
drawio_tool.py preview <ir.json> -o <preview.svg> [--page <id>] [--theme-file <theme.json>]
drawio_tool.py audit <ir.json|blueprint.json|diagram.drawio> [-o <report.json>] [--preview-dir <dir>] [--strict]
drawio_tool.py validate <ir.json|diagram.drawio> [--strict]
drawio_tool.py inspect <diagram.drawio>
drawio_tool.py render <diagram.drawio> -o <output.png|svg|pdf|jpg> [--embed] [--binary <path>] [--report <report.json>]
drawio_tool.py verify-export <output.png|svg|pdf|jpg> [-o <report.json>]

JSON works without third-party packages. YAML input is optional and requires PyYAML.

build auto-detects Diagram IR, Blueprint, ERD, HA, SQL DDL, Terraform, common Kubernetes/OpenAPI/Compose documents, repository source, and supported CI definitions. It does not copy the input into the bundle, which avoids accidentally packaging Kubernetes Secret documents or proprietary source trees.

For every command and exit code, see the CLI reference. For copy-paste workflows, bundle semantics, overwrite behavior, and troubleshooting, see the user workflows guide.

Roadmap

The v0.1–v1.0 roadmap is complete. v1.1–v1.5 added round trips, review publication, policy lifecycle, team governance, and enterprise repository integrations. v1.6 completed signed approval lifecycle and evidence federation. v1.7 completes organization-scale delegated trust, transparency proofs, searchable discovery, observability exports, and C4/ADR interoperability. v1.8 tracks federated automation and model intelligence. See ROADMAP.md.

Development

python3 -m unittest discover -s tests -v
python3 scripts/audit_repository.py
python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py \
  skills/drawio-diagram-engineer

See CONTRIBUTING.md before proposing a schema or output compatibility change.

macOS Python note

If Homebrew Python fails to import pyexpat because its libexpat symbols do not match, use /usr/bin/python3 temporarily or reinstall the affected Python/libexpat packages. This is an interpreter ABI problem; JSON-only compilation may appear to work until XML validation starts.

License

Apache License 2.0. See LICENSE.