{
  "markdown": "# Research Draw.io Diagram Skill\n\nA 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.\n\n```bash\nnpx skills add Will-hxw/drawio-diagram-builder-skill\n```\n\n> [中文版](README-cn.md)\n\n## Quick Install With An Agent\n\nCopy this prompt into Codex, Claude Code, or another local coding agent:\n\n```text\nInstall and test the drawio-diagram-builder skill from:\nhttps://github.com/Will-hxw/drawio-diagram-builder-skill\n\nAfter installing, run its smoke test and tell me the exact skill path.\n```\n\nAfter installation, ask the agent to run the bundled update check against its installed skill path:\n\n```powershell\npython <installed-skill-dir>\\scripts\\check_skill_update.py\n```\n\n## Prerequisites\n\n| Requirement | Why |\n|-------------|-----|\n| **Python 3** (3.7+) | Preview and validation scripts |\n| **Browser automation** (Playwright MCP, Puppeteer, browser tools, etc.) | Screenshot feedback loop — the skill is evidence-driven |\n| **Internet access** | Preview loads `https://embed.diagrams.net/` |\n\nWithout 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.\n\n## Why This Exists\n\nLLMs can write draw.io XML, but the first result is usually not right:\n\n- text overlaps or escapes boxes\n- arrows route incorrectly\n- loop arrows look wrong\n- icons are missing or inconsistent\n- reference figures get embedded as images instead of redrawn as editable objects\n- large diagrams crash on Windows with long-URL failures\n\nThis 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.\n\nFor 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.\n\nFor 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.\n\nThis 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.\n\n## Example Output\n\n![Editable draw.io workspace showing a research figure with selectable objects](assets/drawio-editable-workspace.png)\n\n![Refined research-style draw.io figure output](assets/research-figure-output.png)\n\n## What It Does\n\n- Recreates paper figures as editable draw.io objects\n- Draws method overviews from research papers\n- Converts repositories into architecture/data-flow diagrams\n- Creates ML pipeline diagrams (stages, models, datasets, training loops)\n- Combines text requirements with multiple image/style references into one coherent diagram brief\n- Audits connector semantics such as fan-in, fan-out, feedback loops, grouped routes, and arrowhead direction\n- Iteratively polishes typography, colors, arrows, icons, spacing\n- Provides a bundled MIT-licensed Tabler SVG icon inventory for common research-figure symbols\n\n## What It Doesn't\n\n- It is not a draw.io replacement or affiliated with diagrams.net / JGraph\n- It doesn't guarantee one-shot perfection — high-fidelity reproduction takes multiple screenshot-feedback passes\n- 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\n\n## Repository Layout\n\n```text\n.\n├── skills/drawio-diagram-builder/    # Agent skill (discovered by npx skills add)\n│   ├── SKILL.md                      # Main workflow\n│   ├── VERSION                       # Installed skill version marker\n│   ├── agents/openai.yaml\n│   ├── assets/icons/                 # Bundled MIT-licensed SVG icon set\n│   ├── references/\n│   │   ├── drawio-workflow.md\n│   │   ├── primitive-icons.md\n│   │   ├── reference-replication-protocol.md\n│   │   ├── self-supervision-and-intake.md\n│   │   ├── topconf-paper-style.md\n│   │   └── xml-authoring.md\n│   ├── assets/\n│   │   ├── icons/\n│   │   └── reference-images/\n│   └── scripts/\n│       ├── check_skill_update.py\n│       ├── make_drawio_preview.py\n│       ├── serve_drawio_preview.py\n│       ├── validate_drawio.py\n│       └── validate_replication_artifacts.py\n├── assets/                           # README images\n├── examples/minimal.drawio\n├── tests/smoke_test.py\n├── README.md\n└── LICENSE\n```\n\n## Manual Install (without npx skills)\n\n### Claude Code\n\n```bash\ngit clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git\ncp -R drawio-diagram-builder-skill/skills/drawio-diagram-builder ~/.claude/skills/\n```\n\n### Codex\n\n**Windows:**\n\n```powershell\ngit clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git\nNew-Item -ItemType Directory -Force \"$env:USERPROFILE\\.codex\\skills\" | Out-Null\nCopy-Item -Recurse -Force .\\drawio-diagram-builder-skill\\skills\\drawio-diagram-builder \"$env:USERPROFILE\\.codex\\skills\\\"\n```\n\n**macOS / Linux:**\n\n```bash\ngit clone https://github.com/Will-hxw/drawio-diagram-builder-skill.git\nmkdir -p \"$HOME/.codex/skills\"\ncp -R drawio-diagram-builder-skill/skills/drawio-diagram-builder \"$HOME/.codex/skills/\"\n```\n\nRestart the agent after copying.\n\nTo verify the installed copy, ask the agent to report its active skill path and run:\n\n```powershell\npython <installed-skill-dir>\\scripts\\check_skill_update.py\n```\n\nIf the script reports `OUTDATED` or `UNKNOWN`, reinstall from the canonical repository instead of checking for specific files or text snippets.\n\n## Example Prompts\n\n```text\nUse $drawio-diagram-builder to read this paper section and create an editable draw.io method overview.\n```\n\n```text\nUse $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.\n```\n\n```text\nUse $drawio-diagram-builder to reproduce this reference figure as editable draw.io XML. Preview locally, screenshot, compare, and iterate.\n```\n\n```text\nUse the drawio-diagram-builder skill in this repository to draw a system architecture diagram from the codebase.\n```\n\n## Helper Scripts\n\nAll scripts are plain Python 3 — no pip packages needed.\n\n## Bundled Icon Assets\n\nThe skill includes a curated Tabler Icons outline subset under:\n\n```text\nskills/drawio-diagram-builder/assets/icons/tabler/outline/\n```\n\nRead `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`.\n\n## Bundled Top-Conference Style References\n\nThe skill includes several computer-science paper figure references under:\n\n```text\nskills/drawio-diagram-builder/assets/reference-images/\n```\n\nUse 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.\n\n### Check whether an installed skill is current\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\check_skill_update.py\n```\n\nThe 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.\n\n### Validate a `.drawio` file\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\validate_drawio.py .\\examples\\minimal.drawio\n```\n\nFlags embedded raster images by default. Use `--allow-raster` only when image assets are intentional.\n\nThe 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:\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\validate_drawio.py --strict --json .\\examples\\minimal.drawio\n```\n\n### Validate reference-replication artifacts\n\nBefore drawing from a reference image:\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\validate_replication_artifacts.py .\\workdir\n```\n\nBefore final handoff, after a rendered screenshot was reviewed:\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\validate_replication_artifacts.py .\\workdir --require-screenshot-review\n```\n\nThe stricter check fails if `defect-log.md` still contains placeholder screenshot rows.\n\nThe 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.\n\nFor 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.\n\n### Generate + serve preview in one command\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\serve_drawio_preview.py .\\examples\\minimal.drawio --port 8765\n```\n\nOpens `http://127.0.0.1:8765/drawio-preview.html` in your browser.\n\n### Generate preview HTML only\n\n```powershell\npython .\\skills\\drawio-diagram-builder\\scripts\\make_drawio_preview.py .\\examples\\minimal.drawio --out .\\drawio-preview.html\npython -m http.server 8765 --bind 127.0.0.1\n```\n\nThen open `http://127.0.0.1:8765/drawio-preview.html?rev=1`.\n\nThe 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.\n\n## Windows Notes\n\n- Large `.url` shortcuts with encoded draw.io URLs crash on Windows. Use the preview scripts instead.\n- The preview's blue Save button downloads a `.drawio` file — it cannot overwrite the local source (browser sandbox). Move it back manually.\n- Run servers on `127.0.0.1` (not `localhost`) to avoid IPv6 resolution delays.\n\n## Smoke Test\n\n```powershell\npython .\\tests\\smoke_test.py\n```\n\nVerifies XML parsing, stricter validation failures, preview HTML generation, origin-checked diagrams.net messaging, bundled icons, and bundled reference images.\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n",
  "bytes": 11126,
  "sha": "23c26ee9d4af44ea4079256cdd9143f562dc1c8c5044872c313f1d3ea4624a02",
  "repo_slug": "will-hxw/drawio-diagram-builder",
  "fonte": "repo",
  "truncated": false,
  "api": "https://api.agentalog.com/api/listings/skl_will_hxw_drawio_diagram_builder_drawio_d_419f6b36/readme"
}