Automate Draw.io Diagrams with the New Open‑Source drawio‑chart Skill

Why draw.io

Technical articles often need to adjust titles, node labels, or arrows after publication. Keeping the .drawio source file allows direct edits without recreating PNGs, and the files are small enough to store in version control.

Why not rely on pure image generation

Alternative projects were evaluated: tt-a1i/archify – generates self‑contained HTML diagrams with theme switching and multi‑format export. coleam00/excalidraw-diagram-skill – produces whiteboard‑style diagrams and uses Playwright to check text overlap, arrow misalignment, and spacing. DayuanJiang/next-ai-draw-io – an AI‑driven draw.io product with online demo, Docker, and multi‑model support; observed performance was inconsistent.

For JavaGuide articles the recurring needs are frequent Chinese terminology tweaks, consistent styling across a batch of diagrams, easy Markdown embedding, and incremental updates. Editable .drawio files satisfy these requirements better than a one‑shot image generation approach.

Current drawing workflow

Write the article or outline its main concepts.

Let an Agent identify sections that merit diagrams.

Invoke $drawio-chart to generate a .drawio source file.

Export the diagram as PNG, SVG, or PDF for publishing.

If higher visual fidelity is required, post‑process the export with GPT‑IMG2.

This separation of structure ( $drawio-chart) and visual polish (GPT‑IMG2) keeps the workflow concise and maintainable.

What the drawio-chart Skill does

The Skill encapsulates the task of creating draw.io diagrams. Its main descriptor SKILL.md lists:

When to use it (flowcharts, architecture diagrams, state machines, mind maps, etc.).

When not to use it (simple Mermaid code, bitmap illustrations, poster‑style graphics).

Required inputs (theme, diagram type, key nodes, relationships, export flag).

Generation order (title → container → core nodes → edges → labels).

Pre‑delivery checks (node completeness, correct relationships, label length, file naming).

Reference files

style-spec.md

– color palette, fonts, node semantics, line styles. xml-and-layout.md – draw.io XML schema, node/edge templates, layout advice. export-and-files.md – export commands (PNG/SVG/PDF), naming conventions, delivery rules. use-cases.md – common prompts, multi‑diagram patterns, page‑naming suggestions.

Constraints added to the Skill

Semantic color assignment: entry, service, infra, client, external, DB, cache, MQ, error states each have a fixed color.

Node values ( mxCell.value) must be plain text; line breaks use XML entities; HTML tags such as <br> or <b> are prohibited.

Edge labels must be short; detailed explanations belong in nodes or side notes.

The original .drawio file is retained even if export fails.

Installation and usage

Repository root: https://github.com/Snailclimb/AIGuide/tree/main/skills Skill directory:

https://github.com/Snailclimb/AIGuide/tree/main/skills/drawio-chart

Install via the Skills CLI:

npx skills add Snailclimb/AIGuide/skills/drawio-chart

Install for the Codex agent:

npx -y skills add Snailclimb/AIGuide/skills/drawio-chart --agent codex --yes

Install directly from GitHub with the provided Python script:

python3 ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py \
  --repo Snailclimb/AIGuide \
  --path skills/drawio-chart

Usage examples

Login‑flow diagram:

使用 $drawio-chart 画一个用户登录流程图，包含：
输入账号密码 -> 验证账号密码 -> 成功跳转首页 -> 失败提示错误并允许重试。
要求导出 PNG。

Full‑article illustration:

使用 $drawio-chart 读取这篇文章，为文章生成几张合适的技术配图。
所有配图放到同一个 draw.io 文件里，每张子图作为一个 diagram page。
主文件名和文章文件名保持一致，页面名用英文小写中横线。
配图风格遵循 drawio-chart 的统一规范。

Which diagrams suit draw.io

Process diagrams (e.g., Spec Coding, CLAUDE.md maintenance flow, multi‑agent pipelines) where steps and branches are clear and later tweaks are common.

Architecture and module‑relationship diagrams that benefit from consistent colors and symbols.

Frequently updated diagrams where titles, node names, or arrows may change after publication.

Cover images, posters, or whiteboard‑style sketches are better handled by GPT‑IMG2, Excalidraw, or Archify.

References

drawio-chart

: https://github.com/Snailclimb/AIGuide/tree/main/skills/drawio-chart

Archify: https://github.com/tt-a1i/archify

Excalidraw-diagram-skill: https://github.com/coleam00/excalidraw-diagram-skill

next-ai-draw-io: https://github.com/DayuanJiang/next-ai-draw-io

Agent Skills article: https://javaguide.cn/ai/agent/skills.html