Skip to content
Back to search

bruce-drawio

SkillWorks with Claude CodeGitHub

**Use this skill** when the user wants to create any diagram: flowchart, architecture, UML (sequence/class), ER, mindmap, network topology, or any visual diagram. Trigger words: "draw", "diagram", "flowchart", "architecture", "UML", "sequence diagram", "mindmap", "ER diagram", "network topology", "visualize", "draw.io", "drawio". Workflow: understand requirements -> generate drawio XML directly -> validate -> CLI export PNG/SVG/PDF, falling back to an app.diagrams.net browser link when draw.io desktop is unavailable.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bruc3van--bruce-drawio/badge.svg)](/listings/bruc3van--bruce-drawio)

HTML

<a href="/listings/bruc3van--bruce-drawio"><img src="/api/listings/bruc3van--bruce-drawio/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

向你的 AI 编程 Agent 发送以下提示词:

帮我安装这个skill:https://github.com/bruc3van/bruce-drawio

Agent 会自动克隆仓库并完成配置。

如果你的 Agent 不支持自动安装,手动克隆到对应的 skills 目录即可:

| Agent | skills 目录 | | --------------------------------------- | ------------------- | | Claude Code | `~/.claude/skills/` | | codex / zcode / workbuddy / OpenClaw 等 | `~/.agents/skills/` |

# Claude Code
git clone https://github.com/bruc3van/bruce-drawio ~/.claude/skills/bruce-drawio

# 其他 Agent
git clone https://github.com/bruc3van/bruce-drawio ~/.agents/skills/bruce-drawio

Windows 上把 `~` 换成 `$HOME`(PowerShell)或 `%USERPROFILE%`(cmd)。技能没有构建步骤,克隆完就能用。

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 524 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. name: bruce-drawio
  3. description: |
  4. **Use this skill** when the user wants to create any diagram: flowchart, architecture, UML (sequence/class), ER, mindmap, network topology, or any visual diagram.
  5. Trigger words: "draw", "diagram", "flowchart", "architecture", "UML", "sequence diagram", "mindmap", "ER diagram", "network topology", "visualize", "draw.io", "drawio".
  6. Workflow: understand requirements -> generate drawio XML directly -> validate -> CLI export PNG/SVG/PDF, falling back to an app.diagrams.net browser link when draw.io desktop is unavailable.
  7. ---
  8. # Draw.io Diagram Generator
  9. ## Workflow
  10. Each numbered step below has a matching `## Step N` section. Follow them in order.
  11. ```
  12. 1. Understand requirements -> determine diagram type, elements, relationships
  13. 2. Generate XML directly -> write drawio XML; read the matching reference section first
  14. 3. Apply layout rules -> coordinates, spacing, sizes, cell order
  15. 4. Save + validate (DO NOT SKIP) -> write the .drawio file, run the validator, fix every error
  16. 5. CLI export (optional) -> call draw.io desktop CLI to export an image (skip if not installed)
  17. 6. Browser link (conditional) -> only when the export failed, or the user asks for it
  18. 7. Deliver to user -> image + .drawio file path, kept short
  19. ```
  20. Steps 5 and 6 are two routes to the same goal, not two deliverables to stack up. Export is
  21. the default. The browser link is the fallback that needs nothing installed — it guarantees
  22. the user can always see the diagram, so it is never a dead end, but it is also a detached
  23. copy of the file (Step 6d) and should not be pushed on a user who already has an image.
  24. ## Step 1: Understand Requirements
  25. Determine:
  26. - **Diagram type**: flowchart / architecture / uml-sequence / uml-class / er / mindmap / network
  27. - **Key elements**: nodes, components, participants, entities
  28. - **Relationships**: connections, dependencies, flow direction
  29. - **Output format**: PNG (default) / SVG / PDF
  30. - **Language**: match the user's language for labels
  31. ## Step 2: Generate XML
  32. **You MUST write the XML directly.** Do not call any script to generate it.
  33. ### Read the matching reference first
  34. | Diagram type | Read before writing |
  35. |--------------|--------------------|
  36. | Architecture | `references/best-practices.md` → *Architecture Diagram Templates*, then `references/examples.md` → *Example 2* |
  37. | Flowchart | `references/examples.md` → *Example 1* |
  38. | Mindmap | `references/examples.md` → *Example 3* |
  39. | ER | `references/examples.md` → *Example 4* |
  40. | UML sequence/class, network, anything else | `references/best-practices.md` → *General Rules*, then write from your own knowledge |
  41. `references/examples.md` holds complete, validated diagrams — copying the structure of the
  42. closest example is faster and more reliable than composing one from scratch. Read only the
  43. sections you need, not the whole file.
  44. ### Base XML Structure
  45. ```xml
  46. <?xml version="1.0" encoding="UTF-8"?>
  47. <mxfile host="app.diagrams.net" agent="drawio-skill" version="21.0.0" type="device">
  48. <diagram name="DiagramName" id="diagram-1">
  49. <mxGraphModel dx="1422" dy="762"
  50. grid="1" gridSize="10"
  51. guides="1" tooltips="1" connect="1"
  52. arrows="1" fold="1"
  53. page="1" pageScale="1"
  54. pageWidth="1600" pageHeight="1200"
  55. math="0" shadow="0">
  56. <root>
  57. <mxCell id="0" />
  58. <mxCell id="1" parent="0" />
  59. <!-- nodes and edges here -->
  60. </root>
  61. </mxGraphModel>
  62. </diagram>
  63. </mxfile>
  64. ```
  65. ### Node Template
  66. ```xml
  67. <mxCell id="node-1" value="Label"
  68. style="rounded=1;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;fontSize=14;"
  69. vertex="1" parent="1">
  70. <mxGeometry x="100" y="100" width="160" height="60" as="geometry" />
  71. </mxCell>
  72. ```
  73. ### Text Content Rules
  74. - For multi-line labels, encode line breaks as `&#xa;` inside `value`, for example `value="API&#xa;Gateway"`
  75. - Do not write literal `\n` inside `value`; draw.io will render it as backslash + n text
  76. - Keep `html=1` on nodes, but still use `&#xa;` as the default line-break form for predictable output
  77. ### Edge Template
  78. ```xml
  79. <mxCell id="edge-1" value=""
  80. style="edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;exitX=0.5;exitY=1;exitDx=0;exitDy=0;entryX=0.5;entryY=0;entryDx=0;entryDy=0;"
  81. edge="1" parent="1" source="node-1" target="node-2">
  82. <mxGeometry relative="1" as="geometry" />
  83. </mxCell>
  84. ```
  85. ### Cell Order Is Z-Order (CRITICAL)
  86. draw.io paints cells **in document order**: whatever comes later in `<root>` is drawn on top.
  87. Emit cells back-to-front:
  88. ```
  89. 1. Background plate (the big gray rectangle, if any)
  90. 2. Layer containers (semi-transparent blocks)
  91. 3. Sub-group containers
  92. 4. Leaf nodes / labels
  93. 5. Edges
  94. ```
  95. Writing the background rectangle after the nodes hides the entire diagram behind a gray
  96. block — this is the single most destructive ordering mistake, and it renders as a blank
  97. image with no error anywhere.
  98. ### Parent and Coordinate System
  99. A cell's `x`/`y` are **relative to its parent**. That gives you two valid approaches, and
  100. mixing them is what produces diagrams where everything is shifted off-screen:
  101. | Approach | When | `parent` | Coordinates |
  102. |----------|------|----------|-------------|
  103. | **Flat + absolute** (default) | Everything except ER/UML tables, including the Layered Block Style — visual nesting comes from the numbers, not the tree | always `"1"` | absolute canvas coordinates |
  104. | **True nesting** | Only when the shape genuinely owns its children: `swimlane` tables (ER, UML class), `childLayout=stackLayout` rows | the container's ID | relative to the container's top-left, so a child at `y="30"` sits 30px below the container's top |
  105. **Default to flat + absolute.** The Layered Block Style puts every leaf node at `parent="1"`
  106. with absolute coordinates even though it looks nested — see `references/examples.md` Example 2.
  107. Only ER/UML table rows use true nesting, where a row's `x` is omitted and `y` is its offset
  108. inside the swimlane — see Example 4.
  109. ## Step 3: Layout Rules (CRITICAL for beautiful output)
  110. ### General Principles
  111. 1. **Grid alignment**: anchor top-level blocks (background plate, layer containers, sidebars,
  112. the primary column/row of a flowchart) to multiples of 10. Positions *derived* from the
  113. centering formulas below may land off the grid — that is fine and expected. The hard rule
  114. is that **every coordinate must be a whole number**; never emit fractional values.
  115. 2. **Generous spacing**: minimum 80px gap between node edges (not centers)
  116. 3. **Center alignment**: nodes in the same column share the same x; nodes in the same row share the same y
  117. 4. **Consistent sizing**: same-type nodes use identical width and height
  118. 5. **Page margins**: keep at least 60px from the canvas edge (pageWidth/pageHeight)
  119. 6. **Use `whiteSpace=wrap;html=1;`** on all nodes so long text wraps instead of overflowing
  120. 7. **Balanced gutters**: outer padding around a row/column should visually match the internal gaps; avoid one oversized blank side
  121. 8. **Symmetry first**: centered groups should have roughly equal left/right and top/bottom whitespace
  122. 9. **Dense fill**: containers, sub-groups, and sidebars should fit content plus consistent padding; do not leave large dead zones just because the canvas is large
  123. ### Layout by Diagram Type
  124. | Type | Direction | Primary axis | Spacing (between edges) | Alignment |
  125. |------|-----------|-------------|------------------------|-----------|
  126. | Flowchart | Top-to-bottom | Y increases | 100px vertical | Center x |
  127. | Architecture | Layered block (preferred) | Y increases | 20px between layers | Left label + container rows |
  128. | UML Sequence | Left-to-right participants | X increases | 200px horizontal | Top-aligned |
  129. | UML Class | Grid / top-to-bottom | Y increases | 100px vertical, 80px horizontal | Left-aligned columns |
  130. | ER Diagram | Spread / grid | Both axes | 120px both | Grid-aligned |
  131. | Mindmap | Center-outward radial | Both axes | 150px from center per level | Radial symmetric |
  132. | Network | Hierarchical layers | Y increases | 100px vertical, 120px horizontal | Center each layer |
  133. ### Anti-Overlap Checklist
  134. Before finalizing coordinates, verify:
  135. - No two nodes' bounding boxes overlap (check x, y, width, height)
  136. - Edge labels don't overlap with nodes
  137. - Decision branches (Yes/No) go in clearly different directions
  138. - For flowcharts with branches: main path goes down, alternate path goes right (or left)
  139. - For wide diagrams: increase `pageWidth` in mxGraphModel; for tall ones increase `pageHeight`
  140. ### Calculating Coordinates
  141. Use this formula to center N items horizontally in a row:
  142. ```
  143. total_width = N * node_width + (N - 1) * gap
  144. start_x = round((pageWidth - total_width) / 2)
  145. item[i].x = start_x + i * (node_width + gap)
  146. ```
  147. Round the result to a whole number. Do not then "fix" it to a multiple of 10 by nudging
  148. individual items — that breaks the equal-gap invariant, which matters far more than the grid.
  149. For vertical centering in a column, apply the same logic to Y axis.
  150. For rows inside a fixed-width container, also check fill density:
  151. ```
  152. inner_width = container_width - 2 * side_pad
  153. gap = (inner_width - N * item_width) / (N - 1)
  154. ```
  155. If `gap` is much larger than the item width, or side padding is much larger than `gap`, adjust one of:
  156. - increase item width moderately
  157. - increase item count per row only if still readable
  158. - reduce container width
  159. - split into multiple balanced rows
  160. For incomplete last rows, center the remaining items instead of left-aligning them and leaving a large blank tail.
  161. ### Standard Sizes
  162. | Element | Width | Height |
  163. |---------|-------|--------|
  164. | Standard node | 160 | 60 |
  165. | Decision (rhombus) | 160 | 80 |
  166. | Database (cylinder) | 140 | 80 |
  167. | Actor (UML) | 40 | 60 |
  168. | Start/End (rounded) | 160 | 60 |
  169. | Mindmap center | 180 | 80 |
  170. | Mindmap branch | 140 | 50 |
  171. | Mindmap leaf | 120 | 40 |
  172. | ER table header | 200 | varies |
  173. | Group/container | auto | auto |
  174. Pick one size per role and keep it identical for every node of that role in the diagram. A
  175. start node that is 20px wider than the process nodes below it reads as a mistake, not as
  176. emphasis — use color and `fontStyle=1` to emphasize instead.
  177. ## Step 4: Save and Validate (DO NOT SKIP)
  178. Write the `.drawio` file to the user's working directory, then run the validator on it.
  179. ### 4a. Run the validator
  180. ```bash
  181. python scripts/validate_drawio.py diagram.drawio
  182. ```
  183. Use `python3` if `python` is missing. It exits non-zero when it finds errors.
  184. **Fix every ERROR and re-run until it exits clean.** Do not export or deliver a file that
  185. still reports errors — each one is a diagram that renders wrong or not at all. The validator
  186. catches what re-reading your own XML reliably misses:
  187. | Reported as | Checks |
  188. |-------------|--------|
  189. | ERROR | malformed XML, duplicate IDs, missing root cells, dangling `parent`/`source`/`target`, missing `as="geometry"`, literal `\n` in a label, partially overlapping nodes |
  190. | WARN | missing `whiteSpace=wrap` / `html=1`, `fontSize` under 12, fractional coordinates, content past `pageWidth`/`pageHeight` |
  191. Treat WARNs as defects too unless you have a specific reason — a "content extends past
  192. pageWidth" warning means part of the diagram falls outside the page.
  193. Note what the validator **cannot** see: it reports partial overlaps only, since full
  194. containment is how the Layered Block Style expresses nesting. It says nothing about whether
  195. the layout is balanced or the diagram is readable. That is 4b.
  196. ### 4b. Review what the validator cannot check
  197. Re-read your XML and confirm:
  198. - [ ] Cells are in back-to-front order: background → containers → sub-groups → leaves → edges
  199. - [ ] Sibling items in the same row/column use equal sizes and equal gaps unless there is a clear reason not to
  200. - [ ] Left/right and top/bottom padding inside each container are visually balanced; no obvious one-sided blank area
  201. - [ ] Containers, sub-groups, and sidebars are sized to content plus padding; if a blank region is larger than a normal item gap or roughly a full item row, tighten the layout
  202. - [ ] Incomplete last rows are centered, not stuck to one side with a large empty remainder
  203. - [ ] Decision branches (Yes/No) leave in clearly different directions
  204. - [ ] Edges use `edgeStyle=orthogonalEdgeStyle` for clean routing (except mindmaps, which use `curved=1`)
  205. - [ ] Decision nodes use `rhombus`; database nodes use `shape=cylinder3`
  206. - [ ] Labels are in the user's language and read naturally
  207. ## Step 5: CLI Export (Optional, Cross-Platform)
  208. This step needs the draw.io **desktop app**, and it is the preferred route: it renders an
  209. image the user can see immediately, and the `.drawio` it reads is the same file the desktop
  210. app edits in place. If the app is not installed, do not stop and do not block on an install —
  211. go to Step 6, which needs nothing but a browser.
  212. ### 5a. Detect draw.io
  213. **Use the syntax of the shell you actually have.** On Windows the default shell is usually
  214. PowerShell, where `which` and `ls "/c/..."` do not exist and the check fails for the wrong
  215. reason. Stop at the first command that succeeds.
  216. **Windows (PowerShell):**
  217. ```powershell
  218. (Get-Command draw.io, drawio -ErrorAction SilentlyContinue | Select-Object -First 1).Source
  219. # then the default install locations
  220. "$env:ProgramFiles\draw.io\draw.io.exe", "$env:LOCALAPPDATA\Programs\draw.io\draw.io.exe" |
  221. Where-Object { Test-Path $_ } | Select-Object -First 1
  222. ```
  223. **macOS / Linux (bash):**
  224. ```bash
  225. which drawio 2>/dev/null || which draw.io 2>/dev/null
  226. ```
  227. If PATH lookup fails, check the platform default paths:
  228. ```bash
  229. # macOS
  230. ls /Applications/draw.io.app/Contents/MacOS/draw.io 2>/dev/null
  231. # Linux
  232. ls /usr/bin/drawio 2>/dev/null || ls /snap/bin/drawio 2>/dev/null
  233. ```
  234. **Windows (bash/MSYS2)**, if that is what you are running in:
  235. ```bash
  236. ls "/c/Program Files/draw.io/draw.io.exe" 2>/dev/null || \
  237. ls "$LOCALAPPDATA/Programs/draw.io/draw.io.exe" 2>/dev/null
  238. ```
  239. ### 5b. If not found, fall back to the browser
  240. **Do not stall the task on an install.** Go to Step 6 and deliver the diagram through
  241. app.diagrams.net, then mention the desktop app as an optional extra for offline editing
  242. and image export:
  243. | Platform | Install Command |
  244. |----------|----------------|
  245. | macOS | `brew install --cask drawio` |
  246. | Windows | `winget install JGraph.Draw` |
  247. | Linux | `snap install drawio` |
  248. | All | Download from https://github.com/jgraph/drawio-desktop/releases |
  249. Do NOT auto-install without user confirmation.
  250. ### 5c. Export
  251. Use the detected path (stored as `$DRAWIO`) to export:
  252. ```bash
  253. "$DRAWIO" -x -f png --scale 2 --border 20 -o output.png diagram.drawio
  254. ```
  255. On a headless Linux box the Electron app needs a display and a sandbox opt-out:
  256. ```bash
  257. xvfb-run -a "$DRAWIO" -x -f png --scale 2 --border 20 --no-sandbox -o output.png diagram.drawio
  258. ```
  259. ### 5d. Verify the output file exists
  260. **Do not trust the exit code.** draw.io desktop is a GUI application; when launched from a
  261. shell it often returns 0 immediately, before (or without) writing anything. Always confirm
  262. the file landed and is non-empty:
  263. ```bash
  264. ls -l output.png # bash
  265. ```
  266. ```powershell
  267. Get-Item output.png | Select-Object Length # PowerShell
  268. ```
  269. If the file is missing or 0 bytes, treat the export as failed: say so, and deliver via the
  270. Step 6 browser link instead. Never report an export you did not verify.
  271. ### 5e. If the user wants to keep editing
  272. When the desktop app is present, the best way to hand off an editable diagram is the local
  273. file itself — `"$DRAWIO" diagram.drawio` opens it and saves edits back to the same path. Only
  274. reach for the Step 6 link when the desktop app is unavailable or the user explicitly wants
  275. the browser.
  276. ### Export flags
  277. | Flag | Purpose |
  278. |------|---------|
  279. | `-x` | Export mode (no GUI) |
  280. | `-f png/svg/pdf` | Output format |
  281. | `-o path` | Output file path |
  282. | `--scale 2` | 2x resolution for crisp PNG |
  283. | `--border 20` | Add border padding (px) |
  284. | `--width 1600` | Constrain output width |
  285. | `-p 0` | Export specific page (0-indexed) |
  286. | `--crop` | Crop to diagram content |
  287. Default to `--scale 2 --border 20` for PNG. Reach for `--crop` when the diagram is much
  288. smaller than the `pageWidth`/`pageHeight` you set and the export comes out with wide empty
  289. margins; drop `--scale` for SVG and PDF, where it does nothing useful.
  290. ## Step 6: Open in draw.io Online (Conditional)
  291. An app.diagrams.net link opens the finished diagram in the official web editor with no
  292. install and no account. It is the fallback that guarantees delivery when Step 5 could not
  293. produce an image — but it is **not** something to attach to every diagram.
  294. ### 6a. Decide whether to build a link
  295. | Situation | What to do |
  296. |-----------|-----------|
  297. | Step 5 exported successfully | **Do not build a link.** The user already has an image plus a `.drawio` their desktop app opens natively. Close with one short line: "需要在线打开/编辑的链接就说一声。" |
  298. | Step 5 was skipped or failed | **Build the link** — it is now the only way the user can see the diagram |
  299. | The user asks for it | Build it. Triggers: "打开看看", "我想改一下", "在浏览器里打开", "发给同事", "share this", "open it" |
  300. Why not always: the link is a **snapshot copy**, not a reference to the file (see 6d). Handing
  301. one out unprompted invites the user to edit a fork of a diagram they already have locally.
  302. The link format is `https://app.diagrams.net/?title=<name>#R<data>`, where `<data>` is
  303. `base64(deflateRaw(encodeURIComponent(xml)))`. draw.io decodes the `#R` fragment in the
  304. browser — the diagram never leaves the user's machine, and no account or upload is needed.
  305. ### 6b. Build the link
  306. Run the bundled script on the saved file (paths are relative to this skill's directory):
  307. ```bash
  308. python scripts/open_in_drawio.py diagram.drawio
  309. ```
  310. If `python` is missing or is a stub, use `python3`, then fall back to Node:
  311. ```bash
  312. node scripts/open_in_drawio.js diagram.drawio
  313. ```
  314. Both print the URL on stdout and share the same flags:
  315. | Flag | Purpose |
  316. |------|---------|
  317. | *(none)* | Print the URL only — the default; use this and let the user click |
  318. | `--open` | Also launch the default browser on that URL |
  319. | `--html PATH` | Write a click-to-open launcher page instead of relying on the terminal |
  320. | `--title NAME` | File name shown in draw.io (defaults to the input file name) |
  321. **Only pass `--open` when the user asked to open it** ("打开看看", "open it in the browser").
  322. Launching a browser unprompted is intrusive. Default to printing the link.
  323. ### 6c. Long diagrams
  324. The whole diagram travels inside the URL, so big diagrams produce very long links. A link
  325. over ~2000 characters can be mangled by terminals and by the OS URL handler:
  326. - With `--open`, the script handles this automatically — it writes a temporary launcher page
  327. and opens that instead, so nothing is truncated.
  328. - Without `--open`, if the URL exceeds ~2000 characters, write a launcher next to the diagram
  329. with `--html diagram-open.html` and tell the user to open that file, **or** fall back to 6e.
  330. ### 6d. Warn that browser edits do not sync back (REQUIRED)
  331. The `#R` link carries a **copy** of the diagram. draw.io opens it as a new, unsaved file with
  332. no connection to the `.drawio` on disk. Anything the user changes in the browser lives only
  333. in that browser tab — the local file silently becomes the older version.
  334. Whenever you hand over a link, say so in one line and give the two ways forward:
  335. > 浏览器里的修改不会同步回本地文件。改完请用 **File → Save as → Device** 下载并覆盖
  336. > `diagram.drawio`;或者直接告诉我要改什么,我改本地文件再重新导出。
  337. Never present the link as "the editable version" of the local file. It is a detached copy.
  338. ### 6e. Manual fallback
  339. If the script cannot run at all (no Python, no Node), tell the user to:
  340. 1. Open https://app.diagrams.net
  341. 2. Choose **File → Open From → Device** (or just drag the `.drawio` file onto the page)
  342. 3. Select the generated `.drawio` file
  343. This route has no fork problem — draw.io keeps working against the file the user picked.
  344. ## Step 7: Deliver to User
  345. Keep it short. The diagram is the deliverable; everything else is one line each.
  346. **When the export succeeded:**
  347. 1. The exported image
  348. 2. The `.drawio` file path, and the format exported
  349. 3. One closing line offering the browser link — do not paste a link that was not asked for
  350. **When the export was skipped or failed:**
  351. 1. The `.drawio` file path
  352. 2. The app.diagrams.net link, as the primary way to view the diagram
  353. 3. The fork warning from 6d
  354. 4. One line on why there is no image (desktop app missing / export produced no file), with
  355. the install commands only if the user seems to want them
  356. Do not pad the delivery with a recap of the diagram's contents — the user can see it.
  357. ## File Naming
  358. - Lowercase + hyphens: `ecommerce-order-flow.drawio`
  359. - No Chinese characters, spaces, or special characters in filenames
  360. - Output image uses same base name: `ecommerce-order-flow.png`
  361. ## Architecture Diagram: Layered Block Style
  362. For architecture diagrams, use the **Layered Block Style** — see `references/best-practices.md` for full templates and layout constants. This is the preferred style: structured block layout with no arrows, horizontal layers, left label column, and optional cross-cutting sidebar.
  363. ## Modifying Existing Diagrams
  364. When the user is not satisfied with the result and asks for modifications:
  365. 1. **Read the existing .drawio file** first to understand current structure
  366. 2. **Edit based on the existing XML** — do not regenerate from scratch
  367. 3. Apply the user's requested changes while preserving the overall layout and style
  368. 4. Re-run steps 4 → 7
  369. **Check first whether the local file is stale.** If you previously handed the user an
  370. app.diagrams.net link, they may have edited that copy in the browser — those changes never
  371. reach the local `.drawio` (Step 6d). If the user describes the current diagram in a way that
  372. does not match the file you just read, say so and ask them to save their browser version over
  373. the local file before you continue. Do not silently rebuild from the stale version.
  374. If you do hand over a new link, always regenerate it — the old one still encodes the
  375. previous version of the diagram.
  376. ## Reference
  377. `references/best-practices.md`:
  378. - **General Rules** — ID management, cell order, parent/coordinate system, style essentials, common mistakes
  379. - **Architecture Diagram Templates (Layered Block Style)** — the preferred architecture style with full XML templates and layout constants
  380. `references/examples.md` — four complete, validated diagrams to copy the structure of:
  381. - Example 1: flowchart · Example 2: layered block architecture · Example 3: mindmap · Example 4: ER
  382. - Also holds the **Color Palette Reference** — use these fill/stroke pairs instead of inventing colors
  383. `scripts/`:
  384. - `validate_drawio.py` — mechanical checks on a `.drawio` file (Step 4). Run it every time.
  385. - `open_in_drawio.py` / `open_in_drawio.js` — build the app.diagrams.net `#R` link for a
  386. `.drawio` file (Step 6). Identical CLIs; use whichever runtime is available.
  387. For diagram types without an example (UML sequence/class, network topology, etc.), read the
  388. "General Rules" section and generate the XML from your own knowledge.
README.md · README · 190 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. [English](README_EN.md) | 中文
  2. # Draw.io 图表生成技能
  3. 跨平台的 draw.io (diagrams.net) 图表生成技能,适用于 Claude Code、codex、zcode、workbuddy、OpenClaw 等各类 AI 编程 Agent。Agent 直接生成 drawio XML,校验后通过 CLI 导出图片;没有桌面版时自动降级为 draw.io 官网打开链接。
  4. 技能本身是纯 Markdown + 两个零依赖脚本,不绑定任何特定 Agent 的运行时。
  5. ## 安装
  6. 向你的 AI 编程 Agent 发送以下提示词:
  7. ```
  8. 帮我安装这个skill:https://github.com/bruc3van/bruce-drawio
  9. ```
  10. Agent 会自动克隆仓库并完成配置。
  11. 如果你的 Agent 不支持自动安装,手动克隆到对应的 skills 目录即可:
  12. | Agent | skills 目录 |
  13. | --------------------------------------- | ------------------- |
  14. | Claude Code | `~/.claude/skills/` |
  15. | codex / zcode / workbuddy / OpenClaw 等 | `~/.agents/skills/` |
  16. ```bash
  17. # Claude Code
  18. git clone https://github.com/bruc3van/bruce-drawio ~/.claude/skills/bruce-drawio
  19. # 其他 Agent
  20. git clone https://github.com/bruc3van/bruce-drawio ~/.agents/skills/bruce-drawio
  21. ```
  22. Windows 上把 `~` 换成 `$HOME`(PowerShell)或 `%USERPROFILE%`(cmd)。技能没有构建步骤,克隆完就能用。
  23. ## 支持的图表类型
  24. | 类型 | 说明 | 触发词示例 |
  25. | ---------- | ---------------------------- | ------------------ |
  26. | 流程图 | 业务流程、审批流程、算法逻辑 | "画一个流程图" |
  27. | 架构图 | 系统架构、微服务、部署架构 | "画一个架构图" |
  28. | UML 时序图 | 组件之间的交互时序 | "画一个时序图" |
  29. | UML 类图 | 类关系、继承结构 | "画一个类图" |
  30. | ER 图 | 数据库设计、实体关系 | "画一个 ER 图" |
  31. | 思维导图 | 头脑风暴、知识梳理 | "画一个思维导图" |
  32. | 网络拓扑图 | 网络架构、设备连接 | "画一个网络拓扑图" |
  33. ## 平台支持
  34. draw.io 桌面版仅用于导出图片,属于可选项;不安装也能通过[在浏览器打开](#在浏览器打开)查看和编辑图表。
  35. | 平台 | 安装命令 | 包管理器 |
  36. | ------- | ------------------------------ | ------------------- |
  37. | macOS | `brew install --cask drawio` | Homebrew |
  38. | Windows | `winget install JGraph.Draw` | winget / Chocolatey |
  39. | Linux | `snap install drawio` | snap / 手动安装 |
  40. 所有平台也支持从 [draw.io releases](https://github.com/jgraph/drawio-desktop/releases) 手动下载安装。
  41. Linux 无头环境(容器、CI)下导出需要 `xvfb-run -a` 并加 `--no-sandbox`,Agent 会自动处理。
  42. ## 工作流程
  43. 1. 用户描述想要的图表
  44. 2. Agent 判断图表类型和关键元素
  45. 3. Agent 参照对应示例直接生成完整的 drawio XML
  46. 4. 应用布局规则(坐标、间距、尺寸、单元格顺序)
  47. 5. 保存 `.drawio` 并跑校验脚本,错误清零
  48. 6. 通过 CLI 导出为 PNG/SVG/PDF(未安装桌面版则跳过)
  49. 7. 需要时生成 draw.io 官网打开链接
  50. 8. 交付图片和源文件路径
  51. ## XML 校验
  52. 保存后 Agent 会跑一遍 `scripts/validate_drawio.py`,把靠肉眼复读必然会漏的问题机械地查出来:
  53. ```bash
  54. python scripts/validate_drawio.py diagram.drawio
  55. ```
  56. | 级别 | 检查项 |
  57. | ----- | --------------------------------------------------------------------------------------------------- |
  58. | ERROR | XML 不良构、ID 重复、缺根节点、`parent`/`source`/`target` 指向不存在的节点、缺 `as="geometry"`、`value` 里的字面 `\n`、节点部分重叠 |
  59. | WARN | 缺 `whiteSpace=wrap`/`html=1`、`fontSize` 小于 12、小数坐标、内容超出 `pageWidth`/`pageHeight` |
  60. 有 ERROR 时退出码为 1。重叠检测只报**部分重叠**——完全包含是分层块状风格表达嵌套的方式,不算问题。
  61. ## 在浏览器打开
  62. Agent 可以给出一条 `https://app.diagrams.net/?title=xxx#R...` 链接,点开就是这张图,能继续编辑或导出——**不需要安装桌面版,也不需要注册登录**。
  63. 原理:图表 XML 经过 `encodeURIComponent → deflate raw → base64` 后放进 URL 的 `#R` 片段。片段部分不会发送给服务器,由 draw.io 前端在浏览器本地解码,因此**图表内容不会上传到任何服务器**。
  64. ### 什么时候会给链接
  65. 这条链接是**兜底和按需**,不是每张图都附赠:
  66. | 情况 | 行为 |
  67. | ------------------- | ------------------------------------------------------ |
  68. | 导出成功 | 不主动给,只在结尾提一句「需要在线打开就说一声」 |
  69. | 没装桌面版/导出失败 | 链接作为主交付——这也是它存在的意义:任何环境都能看到图 |
  70. | 你开口要 | 立刻生成("打开看看"、"我想改一下"、"发给同事") |
  71. ### ⚠️ 链接是副本,不是本地文件的入口
  72. `#R` 链接把整张图**复制**进了 URL,draw.io 打开的是一个和磁盘文件毫无关联的新文件。**在浏览器里的修改不会同步回本地 `.drawio`。**
  73. 改完有两条路:
  74. - 在 draw.io 里 **File → Save as → Device** 下载,覆盖本地的 `.drawio`
  75. - 或者直接告诉 Agent 要改什么,让它改本地文件再重新导出
  76. 如果装了桌面版,想继续编辑更推荐直接打开本地文件(`draw.io diagram.drawio`),改动原地保存,没有分叉问题。从官网用 **File → Open From → Device** 打开本地文件也同样没有这个问题。
  77. ### 脚本用法
  78. 链接由 `scripts/` 下的脚本生成,Python / Node 二选一即可:
  79. ```bash
  80. python scripts/open_in_drawio.py diagram.drawio # 仅打印链接
  81. python scripts/open_in_drawio.py diagram.drawio --open # 打印并直接打开浏览器
  82. node scripts/open_in_drawio.js diagram.drawio # 没有 Python 时的等价实现
  83. ```
  84. | 参数 | 说明 |
  85. | -------------- | -------------------------------------------------------- |
  86. | 无参数 | 只打印链接(默认行为) |
  87. | `--open` | 同时用默认浏览器打开 |
  88. | `--html PATH` | 生成一个点击即跳转的本地 HTML 启动页 |
  89. | `--title NAME` | 指定在 draw.io 中显示的文件名,默认取输入文件名 |
  90. **超长图表**:整张图都编码在 URL 里,节点很多时链接会非常长(超过约 2000 字符),可能被终端或系统的 URL 处理器截断。使用 `--open` 时脚本会自动改走本地 HTML 启动页,不会被截断;也可以用 `--html` 手动生成启动页。
  91. **兜底方案**:如果环境里既没有 Python 也没有 Node,打开 [app.diagrams.net](https://app.diagrams.net),选择 **File → Open From → Device**,或者直接把 `.drawio` 文件拖进页面。
  92. ## 导出格式
  93. | 格式 | 参数 | 适用场景 |
  94. | ---- | ---------- | ------------------ |
  95. | PNG | `-f png` | 默认格式,通用性强 |
  96. | SVG | `-f svg` | 可缩放矢量图 |
  97. | PDF | `-f pdf` | 打印 / 嵌入文档 |
  98. PNG 默认带 `--scale 2 --border 20`(高清 + 留白)。画布远大于图形、导出后四周空白过多时,加 `--crop` 裁到内容。SVG / PDF 不需要 `--scale`。
  99. 导出后 Agent 会确认输出文件确实存在且非空——draw.io 桌面版是 GUI 程序,从命令行调用时经常立刻返回 0 但并没有写出文件,退出码不可信。导出失败会如实告知,并改用浏览器链接交付。
  100. ## 项目结构
  101. ```
  102. bruce-drawio/
  103. SKILL.md # 主技能文档(工作流程 + 规则)
  104. skill.json # 技能元数据
  105. references/
  106. best-practices.md # XML 模板、样式、布局规则、常见错误
  107. examples.md # 4 个完整可用的示例(流程图/架构图/思维导图/ER)+ 配色表
  108. scripts/
  109. validate_drawio.py # .drawio 机械校验(ID、引用、几何、重叠)
  110. open_in_drawio.py # 生成 draw.io 官网一键打开链接(Python)
  111. open_in_drawio.js # 同上(Node 版,无 Python 时使用)
  112. evals/
  113. evals.json # 测试用例
  114. ```
  115. ## 架构图风格
  116. 架构图默认采用**分层块状布局**风格:
  117. - 灰色背景底板
  118. - 左侧标签列标注每一层(如"场景层"、"应用层")
  119. - 蓝色半透明层容器,内含子分组
  120. - 白色叶子节点,灰色边框
  121. - 可选的右侧跨层侧边栏(如安全、监控等横切关注点)
  122. - 纯块状图,不使用箭头连线,通过空间嵌套表达层次关系
  123. ## 依赖检测
  124. draw.io 桌面版是**可选**依赖,只用于导出 PNG/SVG/PDF。Agent 按照 SKILL.md 中的步骤自动检测,并且会用当前 shell 的语法:PowerShell 下用 `Get-Command` / `Test-Path $env:LOCALAPPDATA\Programs\draw.io\draw.io.exe`,bash 下用 `which drawio` 加默认安装路径。未安装时不会卡住流程,也不会追着让你装,而是直接走浏览器打开链接这条路,安装方式只作为可选项提一句。
  125. 校验和生成打开链接只依赖 Python 3 或 Node 之一(全部使用标准库,无需 `pip install` / `npm install`)。
  126. ## 使用示例
  127. 安装完成后,用自然语言描述你想要的图表即可,例如:
  128. - "画一个电商下单流程图"
  129. - "画一个微服务架构图"
  130. - "画一个用户注册的时序图"
  131. - "画一个博客系统的 ER 图"
  132. - "画一个 AI Agent 的思维导图"

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.