# Drawio Diagram Builder

> Create, edit, replicate, and iteratively refine editable research and technical diagrams in diagrams.net/draw.io (.drawio XML) from prompts, papers, repositories, screenshots, or existing diagrams. Use when asked to generate a scientific figure, paper method diagram, ML/system architecture diagram, draw.io file, reference figure reproduction, browser screenshot feedback loop, Windows-safe draw.io…

- **Type:** Skill
- **Install:** `agentstack add skill-will-hxw-drawio-diagram-builder-skill-drawio-diagram-builder`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Will-hxw](https://agentstack.voostack.com/s/will-hxw)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Will-hxw](https://github.com/Will-hxw)
- **Source:** https://github.com/Will-hxw/drawio-diagram-builder-skill/tree/main/skills/drawio-diagram-builder
- **Website:** https://xiaoweihua.cn

## Install

```sh
agentstack add skill-will-hxw-drawio-diagram-builder-skill-drawio-diagram-builder
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Research Draw.io Diagram Builder

## Prerequisites

Before starting, verify these are available. If anything is missing, tell the user immediately — do not proceed without them.

| Requirement | Why |
|-------------|-----|
| **Python 3** (3.7+) | All preview/validation scripts are Python. Run `python --version` to check. |
| **Browser automation** | The iterative refinement loop depends on taking screenshots of a local preview. You need one of: Playwright MCP, Puppeteer MCP, browser-evaluate/screenshot tools, or equivalent. |
| **Internet access** | Preview loads `https://embed.diagrams.net/` in an iframe. Offline won't work. |
| **File write access** | You will create `.drawio` files. |

Script paths in this document are relative to the skill directory. Resolve them like `/scripts/serve_drawio_preview.py`. If you can't find the skill directory, look under the agent's installed skills path (e.g., `~/.claude/skills/drawio-diagram-builder/` or `~/.codex/skills/drawio-diagram-builder/`).

If Playwright reports a missing bundled browser, first try an installed browser channel before giving up, for example `npx playwright screenshot --channel chrome ...` or `--channel msedge ...`.

## Core Principle

Produce an editable draw.io diagram first, especially for research and technical figures. Do not use an embedded screenshot as the final answer when the user asks for redraw, replica, vector, editable, or 100% reproduction. Raster images may be used only as references, temporary overlays, or explicitly approved assets.

Prefer direct `.drawio` XML authoring plus browser screenshot feedback for complex or high-fidelity diagrams. Use local draw.io UI control only when it materially improves inspection or user handoff.

## Tool Strategy

Use this priority order:

1. **Direct `.drawio` XML generation/editing** — reliable, reproducible. Write XML with explicit `mxGeometry` positions.
2. **Local preview HTML + diagrams.net iframe postMessage** — run `scripts/serve_drawio_preview.py` (one command, starts server + opens browser) or `scripts/make_drawio_preview.py` + `python -m http.server`. This keeps the browser URL short, avoiding the Windows long-URL crash.
3. **Browser automation screenshots** — navigate browser to `http://127.0.0.1:/drawio-preview.html`, wait for the draw.io embed to load (2-5 seconds), take a full-page or viewport screenshot. This is the evidence you compare against the reference.
4. **draw.io MCP / `@drawio/mcp`** — only for small diagrams or quick opening. On Windows, large encoded URLs fail with `The data area passed to a system call is too small`; do not rely on `.url` shortcuts for large XML.
5. **draw.io desktop/CLI export** — if installed. Treat as optional; always have the local iframe preview fallback.

Load `references/drawio-workflow.md` for the detailed end-to-end process. Load `references/self-supervision-and-intake.md` for any non-trivial diagram, mixed prompt-plus-image input, project-context diagram, or iterative visual repair. Load `references/xml-authoring.md` when writing or repairing XML shapes, styles, edges, and text layout. Load `references/primitive-icons.md` when a reference figure contains small modality, memory, warning, tool, clock, document, or other paper-style icons that should remain editable. Load `assets/icons/ICON-MANIFEST.md` when generic SVG icon assets would improve fidelity.

For any reference-image replication request, load `references/reference-replication-protocol.md` before creating XML. This is mandatory. Treat high-fidelity replication as an evidence pipeline: observe the reference, specify geometry, author XML, render, compare, patch, and repeat. Do not start drawing from a reference image until the protocol's required intermediate artifacts exist.

Resolve all references relative to the skill directory.

## Standard Workflow

1. **Verify prerequisites** — confirm Python 3 and browser automation are available. If not, stop and tell the user what's missing.

2. **Collect input context**
   - Read the user's prompt, reference images, paper sections, codebase files, or domain notes.
   - Identify the task type: research figure creation, paper-method diagramming, visual replication, architecture diagramming, repository diagramming, or iterative polish.
   - Classify every input by role: content source, structure source, style source, layout source, or asset source. A style reference does not automatically define content or connector semantics.
   - If exact assets are needed, locate them locally or ask for them. Do not silently replace a required logo/icon with an unrelated one.

3. **Build the diagram brief and visual specification**
   - For mixed inputs, prompt-only diagrams, paper/code diagrams, or any complex task, create a brief with: user goal, source inventory, requirement traceability, semantic model, style contract, and open assumptions. Use `references/self-supervision-and-intake.md`.
   - Record canvas size, major regions, hierarchy, labels, colors, line styles, fonts, arrows, icons, captions, and spacing.
   - Define the meaning of every connector before drawing it: source, target, direction, fan-in/fan-out, feedback, grouping, and arrowhead placement. Do not draw arrows whose semantics you cannot explain.
   - For reference-image replication, create a coordinate-level inventory: bounding boxes, text lines, highlight bars, connectors, loops, and repeated blocks.
   - For paper figures, preserve exact method terminology and distinguish data construction, training, evaluation, inference, and serving flows.
   - Decide what must be exact and what can be approximated.
   - For reference-image replication, write the required protocol artifacts before XML:
     - `visual-spec.md`
     - `layout-grid.md`
     - `asset-ledger.md`
     - `defect-log.md`

4. **Author the `.drawio` file**
   - The `.drawio` file is the primary artifact. Preview HTML is only a derived artifact.
   - Use one `mxfile` with one or more `diagram` pages.
   - Use explicit `mxGeometry` positions and sizes for high-fidelity work.
   - Split dense text into multiple cells when line-level alignment matters.
   - Build important icons and arrows with editable draw.io primitives when possible. Use `references/primitive-icons.md` for common research-figure icon recipes before inventing one-off symbols. Use bundled SVG icons from `assets/icons/` when fidelity matters more than primitive editability, and record them in `asset-ledger.md`.
   - Keep colors, strokes, fonts, and rounded corners consistent with the reference or requested style.

5. **Preview without long URLs**
   - **Preferred**: run `scripts/serve_drawio_preview.py .drawio --port 8765`. It generates the preview HTML, starts a server, and opens the browser.
   - **Manual**: run `scripts/make_drawio_preview.py .drawio --out drawio-preview.html`, then `python -m http.server 8765 --bind 127.0.0.1` in the output directory.
   - Open `http://127.0.0.1:8765/drawio-preview.html?rev=1` in the browser.
   - Wait 2-5 seconds for the diagrams.net embed iframe to initialize.
   - Take a screenshot of the rendered diagram.

6. **Iterate from evidence**
   - Compare the screenshot against the reference or requested spec.
   - The screenshot must show the full draw.io canvas or a deliberate crop of the full canvas. Do not judge high-fidelity work from a partial viewport where the diagram is clipped.
   - Run a self-supervision pass on the latest screenshot against the brief or references: requirement audit, semantic audit, visual hygiene audit, style audit, and regression audit.
   - Treat these as blockers, not polish: missing required components, wrong arrow direction, wrong fan-in/fan-out, connectors hiding text, text overflow, accidental overlap, incoherent icons, or explicit style violations.
   - Fix a small batch of concrete issues per pass: text overflow, a bad arrow, one misaligned block, wrong color, incorrect icon, spacing, or missing component.
   - Regenerate the preview HTML, refresh the browser (add a cache-busting `?rev=N`), screenshot again, and repeat.
   - Name the specific defects being fixed rather than claiming broad perfection.
   - For reference-image replication, append every screenshot pass to `defect-log.md` with: observed defect, reference evidence, XML cells to change, patch summary, and remaining risk. After the first screenshot row exists, treat `defect-log.md` as append-only; generators may initialize it once but must not overwrite review history.
   - Before claiming improvement, run a red-team visual audit on the latest screenshot: inspect arrow direction, bracket orientation, connector crossings, box overlap, text overflow, z-order, and regressions from the latest patch.
   - If the user points out an obvious screenshot defect, treat it as a self-supervision failure: re-open the source/reference, correct the interpretation, patch the diagram, screenshot a focused crop plus the full canvas, and record the lesson in the defect log.
   - If the first screenshot is structurally wrong, go back to `visual-spec.md` and `layout-grid.md` before making XML patches. A structural miss means an observation, coordinate, asset, or draw.io-rendering assumption was wrong.

7. **Validate before handoff**
   - Run `scripts/validate_drawio.py .drawio`.
   - For reference-image replication, also run `scripts/validate_replication_artifacts.py  --require-screenshot-review` after the latest screenshot pass. Run validation after generation/preview writes finish; do not run validators in parallel with scripts that write the same artifact directory.
   - Confirm: XML parses, page count is expected, no unwanted embedded raster images, captions included/removed as requested, latest screenshot reviewed.
   - Provide the `.drawio` path and the latest screenshot path. Leave the local preview server running if the user wants to continue iterating.

## Editing Rules

- Edit `.drawio` files by writing or patching XML directly. For small targeted fixes, use the file editing tool (e.g., Edit/Write in Claude Code).
- Preserve user files and unrelated generated files.
- Keep a working copy and a handoff copy only when useful; keep them synchronized.
- Never claim the diagram is complete without visual verification (a screenshot).
- Never claim the diagram is complete if the latest screenshot still has a visible P0/P1 blocker: wrong connector semantics, hidden text, clipped text, missing required content, accidental overlap, or a direct violation of the user's prompt/style reference.
- When the user asks for "100% reproduction", treat that as an iterative standard: keep finding and fixing visible differences until the user accepts or identifies next issues.
- For reference-image replication, never skip the intermediate artifacts. A low-quality first draw usually means the observation inventory, coordinate plan, asset ledger, or rendering assumptions were underspecified.

## Common Failure Handling

- **Windows long URL failure**: Do not open large diagrams through `.url` files or huge `#create=` URLs. Use local preview HTML with postMessage.
- **Saving from preview**: The local preview cannot silently overwrite local files (browser sandbox). The blue Save button triggers a `.drawio` download. Move the downloaded file back to your working path before further edits.
- **Text overlap or overflow**: Split paragraphs into smaller text cells, reduce font size, increase container width, set stable geometry, and screenshot-check.
- **Misaligned highlight bars**: Put highlight rectangles behind individual text lines, not behind the whole paragraph.
- **Ugly loop arrows**: Use editable curved connectors or arcs, not large Unicode arrow glyphs, unless the reference explicitly uses glyphs.
- **Wrong icon fidelity**: Build editable approximations from primitives, or ask for/download the exact icon when exactness matters.
- **Missing generic icons**: Check `assets/icons/ICON-MANIFEST.md` before searching the web. Use the bundled MIT-licensed Tabler SVGs for generic document, media, storage, routing, tool, metric, and status icons.
- **Rich text or formulas render literally**: Use the safe helper pattern in `references/xml-authoring.md`; escape normal text and use deliberate raw HTML only for agent-authored tags such as `` or ``.
- **Stale preview**: Add a query string such as `?rev=3`, regenerate preview HTML, or reopen the tab.
- **Editor chrome hiding details**: Resize viewport, zoom inside draw.io, or export a PNG if draw.io CLI is available.
- **Partial screenshot false positives**: If the screenshot clips any page edge, retake it with a larger viewport, a lower draw.io zoom, or a canvas-only crop before judging fidelity.
- **Research-label drift**: Re-read the source paper or code when labels start becoming generic. Prefer exact names from the source material.
- **Preview iframe not loading**: Wait a few more seconds — the `embed.diagrams.net` iframe can take 3-5 seconds on slow connections. If it still fails, verify internet access.

## Bundled Helpers

- `VERSION`: installed skill version marker. Use it through `scripts/check_skill_update.py`, not by checking for a specific feature string.
- `scripts/check_skill_update.py`: compare the installed skill version with the canonical GitHub version.
- `scripts/make_drawio_preview.py`: build a local short-URL preview HTML that loads `.drawio` XML into diagrams.net via `postMessage`.
- `scripts/serve_drawio_preview.py`: generate the preview HTML and serve it on `127.0.0.1` with an optional browser launch.
- `scripts/validate_drawio.py`: parse and sanity-check `.drawio` files before handoff.
- `assets/icons/ICON-MANIFEST.md`: local MIT-licensed SVG icon inventory and usage rules.
- `references/drawio-workflow.md`: full professional workflow for prompt/paper/code/reference-image to editable draw.io.
- `references/self-supervision-and-intake.md`: mixed-input intake, diagram brief, semantic connector audit, and screenshot self-supervision gate.
- `references/primitive-icons.md`: reusable editable primitive recipes for common research-figure icons.
- `references/reference-replication-protocol.md`: low-freedom protocol for high-fidelity reference-image replication.
- `references/xml-authoring.md`: XML, layout, style, edge, text, icon, and iteration patterns.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Will-hxw](https://github.com/Will-hxw)
- **Source:** [Will-hxw/drawio-diagram-builder-skill](https://github.com/Will-hxw/drawio-diagram-builder-skill)
- **License:** MIT
- **Homepage:** https://xiaoweihua.cn

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-will-hxw-drawio-diagram-builder-skill-drawio-diagram-builder
- Seller: https://agentstack.voostack.com/s/will-hxw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.