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.
Python agent-skillsarchitecturearchitecture-diagramasyncapibpmnc4-modelclaude-codediagramdiagrams-as-codedrawioflowchartgithub-actionsgraphqlimage-to-diagramkubernetesmcp-serverprotobufsysmlterraformuml
Initial drawio-skill: XML generation + native CLI export for PNG/SVG/PDF
Agents365-ai3addf7a7c351
diff --git a/README.md b/README.mdnew file mode 100644index 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:**++++## 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-aidiff --git a/README_CN.md b/README_CN.mdnew file mode 100644index 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++**输出效果:**++++## 文件说明++- `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-aidiff --git a/SKILL.md b/SKILL.mdnew file mode 100644index 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: `&` `<` `>` `"` |