Skip to content
Back to search

drawio-diagram-builder

Portable agent skill for research-style editable draw.io diagrams and screenshot-driven refinement

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/will-hxw--drawio-diagram-builder/badge.svg)](/listings/will-hxw--drawio-diagram-builder)

HTML

<a href="/listings/will-hxw--drawio-diagram-builder"><img src="/api/listings/will-hxw--drawio-diagram-builder/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.

Copy this prompt into Codex, Claude Code, or another local coding agent:

Install and test the drawio-diagram-builder skill from:
https://github.com/Will-hxw/drawio-diagram-builder-skill

After installing, run its smoke test and tell me the exact skill path.

After installation, ask the agent to run the bundled update check against its installed skill path:

python <installed-skill-dir>\scripts\check_skill_update.py

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.

README.md · README · 268 lines

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

  1. # Research Draw.io Diagram Skill
  2. A portable agent skill for producing publication-style, editable diagrams.net / draw.io figures from papers, prompts, codebases, project context, screenshots, and one or more visual references.
  3. ```bash
  4. npx skills add Will-hxw/drawio-diagram-builder-skill
  5. ```
  6. > [中文版](README-cn.md)
  7. ## Quick Install With An Agent
  8. Copy this prompt into Codex, Claude Code, or another local coding agent:
  9. ```text
  10. Install and test the drawio-diagram-builder skill from:
  11. https://github.com/Will-hxw/drawio-diagram-builder-skill
  12. After installing, run its smoke test and tell me the exact skill path.
  13. ```
  14. After installation, ask the agent to run the bundled update check against its installed skill path:
  15. ```powershell
  16. python <installed-skill-dir>\scripts\check_skill_update.py
  17. ```
  18. ## Prerequisites
  19. | Requirement | Why |
  20. |-------------|-----|
  21. | **Python 3** (3.7+) | Preview and validation scripts |
  22. | **Browser automation** (Playwright MCP, Puppeteer, browser tools, etc.) | Screenshot feedback loop — the skill is evidence-driven |
  23. | **Internet access** | Preview loads `https://embed.diagrams.net/` |
  24. Without browser automation the agent can still generate `.drawio` XML, but cannot visually verify the result. The iterative refinement loop is the skill's main value.
  25. ## Why This Exists
  26. LLMs can write draw.io XML, but the first result is usually not right:
  27. - text overlaps or escapes boxes
  28. - arrows route incorrectly
  29. - loop arrows look wrong
  30. - icons are missing or inconsistent
  31. - reference figures get embedded as images instead of redrawn as editable objects
  32. - large diagrams crash on Windows with long-URL failures
  33. This skill gives the agent a repeatable workflow: synthesize the user's text and image inputs into a diagram brief → create editable XML → preview through a local URL (not a giant encoded one) → screenshot → self-review visible and semantic defects → fix → repeat → validate.
  34. For reference-image replication, the skill now enforces a stricter protocol: the agent must write a visual spec, coordinate layout grid, asset ledger, and defect log before drawing. Final handoff must include a screenshot-reviewed defect log, not just valid XML.
  35. For prompt, paper, codebase, or mixed-input diagrams, the skill now also requires a self-supervision protocol: classify each input as content, structure, style, layout, or asset evidence; define connector semantics before drawing arrows; inspect screenshots for requirement mismatches, arrow meaning, text overlap, icon coherence, style drift, and regressions.
  36. This is the intended workflow for high-fidelity scientific diagramming: convert the user's inputs into observable requirements and visual constraints, render the editable draw.io result, compare against the brief and references, then fix concrete mismatches.
  37. ## Example Output
  38. ![Editable draw.io workspace showing a research figure with selectable objects](assets/drawio-editable-workspace.png)
  39. ![Refined research-style draw.io figure output](assets/research-figure-output.png)
  40. ## What It Does
  41. - Recreates paper figures as editable draw.io objects
  42. - Draws method overviews from research papers
  43. - Converts repositories into architecture/data-flow diagrams
  44. - Creates ML pipeline diagrams (stages, models, datasets, training loops)
  45. - Combines text requirements with multiple image/style references into one coherent diagram brief
  46. - Audits connector semantics such as fan-in, fan-out, feedback loops, grouped routes, and arrowhead direction
  47. - Iteratively polishes typography, colors, arrows, icons, spacing
  48. - Provides a bundled MIT-licensed Tabler SVG icon inventory for common research-figure symbols
  49. ## What It Doesn't
  50. - It is not a draw.io replacement or affiliated with diagrams.net / JGraph
  51. - It doesn't guarantee one-shot perfection — high-fidelity reproduction takes multiple screenshot-feedback passes
  52. - Bundled SVG icons are vector assets, but their internals are not decomposed into draw.io primitive cells; use primitive recipes when full object-level editability matters
  53. ## Repository Layout
  54. ```text
  55. .
  56. ├── skills/drawio-diagram-builder/ # Agent skill (discovered by npx skills add)
  57. │ ├── SKILL.md # Main workflow
  58. │ ├── VERSION # Installed skill version marker
  59. │ ├── agents/openai.yaml
  60. │ ├── assets/icons/ # Bundled MIT-licensed SVG icon set
  61. │ ├── references/
  62. │ │ ├── drawio-workflow.md
  63. │ │ ├── primitive-icons.md
  64. │ │ ├── reference-replication-protocol.md
  65. │ │ ├── self-supervision-and-intake.md
  66. │ │ ├── topconf-paper-style.md
  67. │ │ └── xml-authoring.md
  68. │ ├── assets/
  69. │ │ ├── icons/
  70. │ │ └── reference-images/
  71. │ └── scripts/
  72. │ ├── check_skill_update.py
  73. │ ├── make_drawio_preview.py
  74. │ ├── serve_drawio_preview.py
  75. │ ├── validate_drawio.py
  76. │ └── validate_replication_artifacts.py
  77. ├── assets/ # README images
  78. ├── examples/minimal.drawio
  79. ├── tests/smoke_test.py
  80. ├── README.md
  81. └── LICENSE
  82. ```
  83. ## Manual Install (without npx skills)
  84. ### Claude Code
  85. ```bash
  86. git clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git
  87. cp -R drawio-diagram-builder-skill/skills/drawio-diagram-builder ~/.claude/skills/
  88. ```
  89. ### Codex
  90. **Windows:**
  91. ```powershell
  92. git clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git
  93. New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\skills" | Out-Null
  94. Copy-Item -Recurse -Force .\drawio-diagram-builder-skill\skills\drawio-diagram-builder "$env:USERPROFILE\.codex\skills\"
  95. ```
  96. **macOS / Linux:**
  97. ```bash
  98. git clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git
  99. mkdir -p "$HOME/.codex/skills"
  100. cp -R drawio-diagram-builder-skill/skills/drawio-diagram-builder "$HOME/.codex/skills/"
  101. ```
  102. Restart the agent after copying.
  103. To verify the installed copy, ask the agent to report its active skill path and run:
  104. ```powershell
  105. python <installed-skill-dir>\scripts\check_skill_update.py
  106. ```
  107. If the script reports `OUTDATED` or `UNKNOWN`, reinstall from the canonical repository instead of checking for specific files or text snippets.
  108. ## Example Prompts
  109. ```text
  110. Use $drawio-diagram-builder to read this paper section and create an editable draw.io method overview.
  111. ```
  112. ```text
  113. Use $drawio-diagram-builder to turn my project context, requirements, and these two style references into a publication-style architecture figure. Preview it locally, screenshot it, self-review arrow semantics and text overlap, then iterate.
  114. ```
  115. ```text
  116. Use $drawio-diagram-builder to reproduce this reference figure as editable draw.io XML. Preview locally, screenshot, compare, and iterate.
  117. ```
  118. ```text
  119. Use the drawio-diagram-builder skill in this repository to draw a system architecture diagram from the codebase.
  120. ```
  121. ## Helper Scripts
  122. All scripts are plain Python 3 — no pip packages needed.
  123. ## Bundled Icon Assets
  124. The skill includes a curated Tabler Icons outline subset under:
  125. ```text
  126. skills/drawio-diagram-builder/assets/icons/tabler/outline/
  127. ```
  128. Read `skills/drawio-diagram-builder/assets/icons/ICON-MANIFEST.md` for the full inventory and license notes. These icons are useful for generic document, media, storage, model, routing, status, metric, and tool symbols. If exact reproduction needs a branded or paper-specific icon, supply the exact asset or record the approximation in `asset-ledger.md`.
  129. ## Bundled Top-Conference Style References
  130. The skill includes several computer-science paper figure references under:
  131. ```text
  132. skills/drawio-diagram-builder/assets/reference-images/
  133. ```
  134. Use them only as style and layout fallback when the user asks for a polished top-conference-style paper figure but does not provide enough visual guidance. The agent should not embed these raster references into the final `.drawio`, and should not invent scientific content to fill the style.
  135. ### Check whether an installed skill is current
  136. ```powershell
  137. python .\skills\drawio-diagram-builder\scripts\check_skill_update.py
  138. ```
  139. The script compares the installed `VERSION` file with the latest `VERSION` on GitHub. Use this for update checks; do not check for one specific feature string because the skill will continue to evolve.
  140. ### Validate a `.drawio` file
  141. ```powershell
  142. python .\skills\drawio-diagram-builder\scripts\validate_drawio.py .\examples\minimal.drawio
  143. ```
  144. Flags embedded raster images by default. Use `--allow-raster` only when image assets are intentional.
  145. The validator also checks duplicate cell ids, missing edge/parent references, missing or invalid geometry, external images, oversized base64 payloads, off-page vertices, empty labels, and placeholder-like text. Use CI-friendly output and warning-as-error mode when needed:
  146. ```powershell
  147. python .\skills\drawio-diagram-builder\scripts\validate_drawio.py --strict --json .\examples\minimal.drawio
  148. ```
  149. ### Validate reference-replication artifacts
  150. Before drawing from a reference image:
  151. ```powershell
  152. python .\skills\drawio-diagram-builder\scripts\validate_replication_artifacts.py .\workdir
  153. ```
  154. Before final handoff, after a rendered screenshot was reviewed:
  155. ```powershell
  156. python .\skills\drawio-diagram-builder\scripts\validate_replication_artifacts.py .\workdir --require-screenshot-review
  157. ```
  158. The stricter check fails if `defect-log.md` still contains placeholder screenshot rows.
  159. The replication validator also requires a requirement/semantic audit. This is intentional: a diagram can look clean while still reversing an arrow, breaking a fan-in/fan-out relationship, or missing a required relation.
  160. For iterative reference replication, keep `defect-log.md` append-only after the first rendered screenshot review. Generate, preview, screenshot, append the review, and then validate; do not run validation while another process is rewriting the same workdir.
  161. ### Generate + serve preview in one command
  162. ```powershell
  163. python .\skills\drawio-diagram-builder\scripts\serve_drawio_preview.py .\examples\minimal.drawio --port 8765
  164. ```
  165. Opens `http://127.0.0.1:8765/drawio-preview.html` in your browser.
  166. ### Generate preview HTML only
  167. ```powershell
  168. python .\skills\drawio-diagram-builder\scripts\make_drawio_preview.py .\examples\minimal.drawio --out .\drawio-preview.html
  169. python -m http.server 8765 --bind 127.0.0.1
  170. ```
  171. Then open `http://127.0.0.1:8765/drawio-preview.html?rev=1`.
  172. The preview uses an iframe to `https://embed.diagrams.net/` and injects XML via origin-checked `postMessage` — the browser URL stays short, avoiding the Windows long-URL crash.
  173. ## Windows Notes
  174. - Large `.url` shortcuts with encoded draw.io URLs crash on Windows. Use the preview scripts instead.
  175. - The preview's blue Save button downloads a `.drawio` file — it cannot overwrite the local source (browser sandbox). Move it back manually.
  176. - Run servers on `127.0.0.1` (not `localhost`) to avoid IPv6 resolution delays.
  177. ## Smoke Test
  178. ```powershell
  179. python .\tests\smoke_test.py
  180. ```
  181. Verifies XML parsing, stricter validation failures, preview HTML generation, origin-checked diagrams.net messaging, bundled icons, and bundled reference images.
  182. ## License
  183. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

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