DEV Community

CodeCow
CodeCow

Posted on

A Codex Skill That Generates Editable Draw.io Diagrams Instead of Screenshots

#opensource #architecture #showdev #ai

Most AI diagram workflows end with a PNG or a screenshot. It may look fine, but the moment the architecture changes, you have to redraw it or regenerate the whole image.

I wanted a different workflow: describe a system in natural language, receive a real Draw.io file, and keep editing every node, label, connector, group, and icon.

That is why I built drawio-mxgraph, an open-source Codex Skill that turns architecture and process descriptions into validated, editable .drawio files.

Repository: https://github.com/clawcode3-bit/drawio-mxgraph-skill

What the Skill does

The Skill generates mxGraph XML that opens directly in Draw.io/diagrams.net. It is designed for architecture diagrams, business processes, agent workflows, and integration maps.

Key capabilities include:

  • Natural-language descriptions to editable .drawio XML
  • Stable node IDs for reliable incremental updates
  • Add, remove, move, resize, rename, and regroup operations
  • Layout direction switching: left-to-right, right-to-left, top-to-bottom, or bottom-to-top
  • Orthogonal connector routing with explicit entry and exit points
  • Portable embedded SVG icons, including cloud and enterprise-style icon sets
  • XML structure and reference validation before delivery
  • Example diagrams that can be opened and modified immediately

Why stable IDs matter

A common failure mode in generated diagrams is treating every edit as a full redraw. That makes small requests surprisingly destructive.

With stable IDs, a request such as:

Move the ticketing system below the CRM, add an observability group, and change the layout to left-to-right.

can update only the affected cells. Existing labels, styles, icons, connections, and manually adjusted positions can remain intact.

This makes the diagram behave more like source code than a disposable image.

Example: an AgentBuilder customer-service architecture

The repository includes an editable example for an intelligent customer-service system built with AgentBuilder. It connects:

  • Web, mobile, messaging, and voice channels
  • An intent-routing and orchestration layer
  • LLM and knowledge retrieval services
  • CRM customer context
  • ERP order, inventory, and finance data
  • Ticketing and human-agent handoff
  • Guardrails, security, observability, and audit services

The same file can be revised incrementally. For example, you can ask the Skill to add a fraud-check service, move ERP into an enterprise-systems group, switch the diagram to a vertical layout, or replace generic blocks with AWS-style icons.

Validation before delivery

Generating XML is easy. Generating XML that remains useful after several edits is harder.

The included validator checks for issues such as:

  • Missing mxGraph roots
  • Duplicate IDs
  • Broken edge references
  • Invalid parent relationships
  • Missing geometry
  • Unsupported layout values
  • References to nodes that no longer exist

This catches many problems before the file reaches Draw.io.

Quick start

Clone the repository into your Codex skills directory, then ask Codex for a diagram in plain language.

Example prompt:

Create an editable Draw.io architecture for an AI customer-service platform.
Use AgentBuilder, connect CRM, ERP, and ticketing systems, group external systems,
use a left-to-right layout, and select suitable enterprise icons automatically.
Enter fullscreen mode Exit fullscreen mode

You can then continue with incremental instructions:

Move the ticketing system below CRM, add an observability group,
and change the layout to top-to-bottom without recreating unrelated nodes.
Enter fullscreen mode Exit fullscreen mode

What I would like feedback on

This is the first public release, and I would especially value feedback on:

  1. Connector routing in dense enterprise diagrams
  2. Which AWS, Azure, GCP, or Visio-style icon libraries should be supported next
  3. Useful templates for agent systems, SaaS platforms, and business processes
  4. Edge cases that should be added to the XML validator

If editable AI-generated diagrams are useful to you, please try the examples, open an issue, or star the repository so I know which direction to prioritize.

GitHub: https://github.com/clawcode3-bit/drawio-mxgraph-skill

Release v1.0.0: https://github.com/clawcode3-bit/drawio-mxgraph-skill/releases/tag/v1.0.0

Top comments (0)