Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

Initial drawio-skill: XML generation + native CLI export for PNG/SVG/PDF

Agents365-ai3addf7a7c351
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..2028913
--- /dev/null
+++ b/README.md
@@ -0,0 +1,123 @@
+# drawio-skill
+
+Claude Code skill for generating Draw.io diagrams and exporting to PNG/SVG/PDF locally.
+
+[中文文档](README_CN.md)
+
+## What it does
+
+- Generates `.drawio` XML files from natural language descriptions
+- Exports diagrams to PNG, SVG, PDF, or JPG using the native draw.io desktop CLI
+- Supports multi-page diagrams and layered grouping
+- Triggers automatically when diagrams would help explain complex systems
+
+## Dependencies
+
+| Tool | Purpose |
+|------|---------|
+| `draw.io` desktop app | Native CLI to export `.drawio` → PNG/SVG/PDF |
+
+No browser automation or Node.js dependency required.
+
+## Install
+
+### macOS
+
+```bash
+# Recommended — Homebrew
+brew install --cask drawio
+
+# Verify
+draw.io --version
+```
+
+### Windows
+
+Download and install from: https://github.com/jgraph/drawio-desktop/releases
+
+```powershell
+# Verify
+"C:\Program Files\draw.io\draw.io.exe" --version
+```
+
+### Linux
+
+Download `.deb` or `.rpm` from: https://github.com/jgraph/drawio-desktop/releases
+
+```bash
+# Headless export (required on Linux servers without display)
+sudo apt install xvfb # Debian/Ubuntu
+xvfb-run -a draw.io --version
+```
+
+### Platform notes
+
+| Platform | Extra step |
+|----------|------------|
+| **macOS** | No extra steps after Homebrew install |
+| **Windows** | Use full path if not in PATH |
+| **Linux** | Wrap commands with `xvfb-run -a` for headless export |
+
+## Usage
+
+Just describe what you want:
+
+```
+Create a microservices e-commerce architecture with API Gateway, auth/user/order/product/payment services,
+Kafka message queue, notification service, and separate databases for each service
+```
+
+Claude will generate the `.drawio` XML file and export it to PNG automatically.
+
+## Example
+
+**Prompt:**
+> Create a microservices e-commerce architecture with Mobile/Web/Admin clients, API Gateway,
+> Auth/User/Order/Product/Payment services, Kafka message queue, Notification service,
+> and User DB / Order DB / Product DB / Redis Cache / Stripe API
+
+**Output:**
+
+![Microservices Architecture](assets/microservices-example.png)
+
+## Files
+
+- `SKILL.md` — skill instructions loaded by Claude Code
+- `README.md` — this file (English)
+- `README_CN.md` — Chinese documentation
+- `assets/` — example diagrams
+
+## License
+
+MIT
+
+## Support
+
+If this skill helps you, consider supporting the author:
+
+<table>
+ <tr>
+ <td align="center">
+ <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/wechat-pay.png" width="180" alt="WeChat Pay">
+ <br>
+ <b>WeChat Pay</b>
+ </td>
+ <td align="center">
+ <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/alipay.png" width="180" alt="Alipay">
+ <br>
+ <b>Alipay</b>
+ </td>
+ <td align="center">
+ <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/buymeacoffee.png" width="180" alt="Buy Me a Coffee">
+ <br>
+ <b>Buy Me a Coffee</b>
+ </td>
+ </tr>
+</table>
+
+## Author
+
+**Agents365-ai**
+
+- Bilibili: https://space.bilibili.com/441831884
+- GitHub: https://github.com/Agents365-ai
diff --git a/README_CN.md b/README_CN.md
new file mode 100644
index 0000000..d770023
--- /dev/null
+++ b/README_CN.md
@@ -0,0 +1,124 @@
+# drawio-skill
+
+用于在 Claude Code 中生成 Draw.io 图表并本地导出为 PNG/SVG/PDF 的 skill。
+
+[English](README.md)
+
+## 功能说明
+
+- 根据自然语言描述生成 `.drawio` XML 文件
+- 使用 draw.io 桌面版原生 CLI 将图表导出为 PNG、SVG、PDF 或 JPG
+- 支持多页图表和分层分组
+- 当图表有助于解释复杂系统时自动触发
+
+## 依赖项
+
+| 工具 | 用途 |
+|------|------|
+| `draw.io` 桌面应用 | 原生 CLI,用于将 `.drawio` 导出为 PNG/SVG/PDF |
+
+无需浏览器自动化或 Node.js 依赖。
+
+## 安装
+
+### macOS
+
+```bash
+# 推荐方式 — Homebrew
+brew install --cask drawio
+
+# 验证安装
+draw.io --version
+```
+
+### Windows
+
+从以下地址下载安装包:https://github.com/jgraph/drawio-desktop/releases
+
+```powershell
+# 验证安装
+"C:\Program Files\draw.io\draw.io.exe" --version
+```
+
+### Linux
+
+从以下地址下载 `.deb` 或 `.rpm` 包:https://github.com/jgraph/drawio-desktop/releases
+
+```bash
+# 无头导出(Linux 服务器无显示器时必须)
+sudo apt install xvfb # Debian/Ubuntu
+xvfb-run -a draw.io --version
+```
+
+### 平台说明
+
+| 平台 | 额外步骤 |
+|------|----------|
+| **macOS** | Homebrew 安装后无需额外操作 |
+| **Windows** | 如不在 PATH 中,使用完整路径 |
+| **Linux** | 无头导出时命令前加 `xvfb-run -a` |
+
+## 使用方式
+
+直接描述你想要的图表:
+
+```
+画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway,
+Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,
+以及各自独立的数据库
+```
+
+Claude 会自动生成 `.drawio` 文件并导出为 PNG。
+
+## 示例
+
+**提示词:**
+> 画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway(含认证+限流+路由),
+> Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,
+> User DB / Order DB / Product DB / Redis Cache / Stripe API
+
+**输出效果:**
+
+![微服务架构图](assets/microservices-example.png)
+
+## 文件说明
+
+- `SKILL.md` — Claude Code 加载的 skill 指令文件
+- `README.md` — 英文说明
+- `README_CN.md` — 本文件(中文)
+- `assets/` — 示例图表
+
+## 开源协议
+
+MIT
+
+## 支持作者
+
+如果这个 skill 对你有帮助,欢迎支持作者:
+
+<table>
+ <tr>
+ <td align="center">
+ <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/wechat-pay.png" width="180" alt="微信支付">
+ <br>
+ <b>微信支付</b>
+ </td>
+ <td align="center">
+ <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/alipay.png" width="180" alt="支付宝">
+ <br>
+ <b>支付宝</b>
+ </td>
+ <td align="center">
+ <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/buymeacoffee.png" width="180" alt="Buy Me a Coffee">
+ <br>
+ <b>Buy Me a Coffee</b>
+ </td>
+ </tr>
+</table>
+
+## 作者
+
+**Agents365-ai**
+
+- Bilibili: https://space.bilibili.com/441831884
+- GitHub: https://github.com/Agents365-ai
diff --git a/SKILL.md b/SKILL.md
new file mode 100644
index 0000000..acd557d
--- /dev/null
+++ b/SKILL.md
@@ -0,0 +1,201 @@
+---
+name: drawio
+description: Use when user requests diagrams, flowcharts, architecture charts, or visualizations. Also use proactively when explaining systems with 3+ components, complex data flows, or relationships that benefit from visual representation. Generates .drawio XML files and exports to PNG/SVG/PDF locally using the native draw.io desktop CLI.
+---
+
+# Draw.io Diagrams
+
+## Overview
+
+Generate `.drawio` XML files and export to PNG/SVG/PDF/JPG locally using the native draw.io desktop app CLI.
+
+**Supported formats:** PNG, SVG, PDF, JPG — no browser automation needed.
+
+## When to Use
+
+**Explicit triggers:** user says "画图", "diagram", "visualize", "flowchart", "draw", "架构图", "流程图"
+
+**Proactive triggers:**
+- Explaining a system with 3+ interacting components
+- Describing a multi-step process or decision tree
+- Comparing architectures or approaches side by side
+
+**Skip when:** a simple list or table suffices, or user is in a quick Q&A flow
+
+## Prerequisites
+
+The draw.io desktop app must be installed and the CLI accessible:
+
+```bash
+# macOS (Homebrew — recommended)
+brew install --cask drawio
+draw.io --version
+
+# macOS (full path if not in PATH)
+/Applications/draw.io.app/Contents/MacOS/draw.io --version
+
+# Windows
+"C:\Program Files\draw.io\draw.io.exe" --version
+
+# Linux
+draw.io --version
+```
+
+Install draw.io desktop if missing:
+- macOS: `brew install --cask drawio` or download from https://github.com/jgraph/drawio-desktop/releases
+- Windows: download installer from https://github.com/jgraph/drawio-desktop/releases
+- Linux: download `.deb`/`.rpm` from https://github.com/jgraph/drawio-desktop/releases
+
+## Workflow
+
+1. **Check deps** — verify `draw.io --version` succeeds; note platform for correct CLI path
+2. **Plan** — identify shapes, relationships, layout (LR or TB), group by tier/layer
+3. **Generate** — write `.drawio` XML file to disk (output dir same as user's working dir)
+4. **Export** — run CLI to produce PNG, SVG, or PDF
+5. **Report** — tell user the output file paths (source + image)
+
+## Draw.io XML Structure
+
+### File skeleton
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<mxfile host="drawio" version="26.0.0">
+ <diagram name="Page-1">
+ <mxGraphModel>
+ <root>
+ <mxCell id="0" />
+ <mxCell id="1" parent="0" />
+ <!-- user shapes start at id="2" -->
+ </root>
+ </mxGraphModel>
+ </diagram>
+</mxfile>
+```
+
+**Rules:**
+- `id="0"` and `id="1"` are required root cells — never omit them
+- User shapes start at `id="2"` and increment sequentially
+- All shapes have `parent="1"`
+- All text uses `html=1` in style for proper rendering
+
+### Shape types (vertex)
+
+| Style keyword | Use for |
+|--------------|---------|
+| `rounded=0` | plain rectangle (default) |
+| `rounded=1` | rounded rectangle — services, modules |
+| `ellipse;` | circles/ovals — start/end, databases |
+| `rhombus;` | diamond — decision points |
+| `shape=mxgraph.aws4.resourceIcon;` | AWS icons |
+| `shape=cylinder3;` | cylinder — databases |
+| `swimlane;` | group/container with title bar |
+
+### Required properties
+
+```xml
+<!-- Rectangle / rounded box -->
+<mxCell id="2" value="Label" style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;" vertex="1" parent="1">
+ <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
+</mxCell>
+
+<!-- Cylinder (database) -->
+<mxCell id="3" value="DB" style="shape=cylinder3;whiteSpace=wrap;html=1;fillColor=#f5f5f5;strokeColor=#666666;fontColor=#333333;" vertex="1" parent="1">
+ <mxGeometry x="350" y="100" width="120" height="80" as="geometry" />
+</mxCell>
+
+<!-- Diamond (decision) -->
+<mxCell id="4" value="Check?" style="rhombus;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;" vertex="1" parent="1">
+ <mxGeometry x="100" y="220" width="160" height="80" as="geometry" />
+</mxCell>
+```
+
+### Connector (edge)
+
+```xml
+<!-- Directed arrow between shapes -->
+<mxCell id="10" value="" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" parent="1" source="2" target="3">
+ <mxGeometry relative="1" as="geometry" />
+</mxCell>
+
+<!-- Arrow with label -->
+<mxCell id="11" value="HTTP/REST" style="edgeStyle=orthogonalEdgeStyle;html=1;" edge="1" parent="1" source="2" target="4">
+ <mxGeometry relative="1" as="geometry" />
+</mxCell>
+```
+
+### Color palette (fillColor / strokeColor)
+
+| Color name | fillColor | strokeColor | Use for |
+|-----------|-----------|-------------|---------|
+| Blue | `#dae8fc` | `#6c8ebf` | services, clients |
+| Green | `#d5e8d4` | `#82b366` | success, databases |
+| Yellow | `#fff2cc` | `#d6b656` | queues, decisions |
+| Orange | `#ffe6cc` | `#d79b00` | gateways, APIs |
+| Red/Pink | `#f8cecc` | `#b85450` | errors, alerts |
+| Grey | `#f5f5f5` | `#666666` | external/neutral |
+| Purple | `#e1d5e7` | `#9673a6` | security, auth |
+
+### Layout tips
+
+- Allocate ~200px per node horizontally, ~150px vertically to avoid overlaps
+- Plan a grid before assigning x/y coordinates
+- Group related nodes in the same horizontal or vertical band
+- Use `swimlane` cells for logical grouping with visible borders
+
+## Export
+
+### Commands
+
+```bash
+# macOS — Homebrew (draw.io in PATH)
+draw.io -x -f png -s 2 -o diagram.png input.drawio
+
+# macOS — full path (if not in PATH)
+/Applications/draw.io.app/Contents/MacOS/draw.io -x -f png -s 2 -o diagram.png input.drawio
+
+# Windows
+"C:\Program Files\draw.io\draw.io.exe" -x -f png -s 2 -o diagram.png input.drawio
+
+# Linux (headless — requires xvfb-run)
+xvfb-run -a draw.io -x -f png -s 2 -o diagram.png input.drawio
+
+# SVG export
+draw.io -x -f svg -o diagram.svg input.drawio
+
+# PDF export
+draw.io -x -f pdf -o diagram.pdf input.drawio
+```
+
+**Key flags:**
+- `-x` — export mode (required)
+- `-f` — format: `png`, `svg`, `pdf`, `jpg`
+- `-s` — scale: `1`, `2`, `3` (2 recommended for PNG)
+- `-o` — output file path
+- `--page-index 0` — export specific page (default: all)
+
+### Checking if draw.io is in PATH
+
+```bash
+# Try short command first
+if command -v draw.io &>/dev/null; then
+ DRAWIO="draw.io"
+elif [ -f "/Applications/draw.io.app/Contents/MacOS/draw.io" ]; then
+ DRAWIO="/Applications/draw.io.app/Contents/MacOS/draw.io"
+else
+ echo "draw.io not found — install from https://github.com/jgraph/drawio-desktop/releases"
+fi
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Missing `id="0"` and `id="1"` root cells | Always include both at the top of `<root>` |
+| Shapes not connected | `source` and `target` on edge must match existing shape `id` values |
+| Export command not found on macOS | Try full path `/Applications/draw.io.app/Contents/MacOS/draw.io` |
+| Linux: blank/error output headlessly | Prefix command with `xvfb-run -a` |
+| PDF export fails | Ensure Chromium is available (draw.io bundles it on desktop) |
+| Background color wrong in CLI export | Known CLI bug; add `--transparent` flag or set background via style |
+| Overlapping shapes | Plan a 200px grid before placing x/y coordinates |
+| Special characters in `value` | Use XML entities: `&amp;` `&lt;` `&gt;` `&quot;` |