home / skills / theonelee / theone_claude_skill / drawio

drawio skill

safe

This skill helps you create draw.io diagrams by generating compressed URLs and opening diagrams in your browser for flowcharts, architectures, and more.

npx playbooks add skill theonelee/theone_claude_skill --skill drawio

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

3.0 KB

---
name: drawio-diagram
description: Use when the user requests any visual diagram using draw.io - flowcharts, architecture diagrams, UML, ERD, sequence diagrams, org charts, mind maps, wireframes, network topology, or other diagramming needs
argument-hint: "[language: zh-CN (default) | en | ja | ...]"
allowed-tools:
  - Write
  - Read
  - Bash(python3:*)
  - Bash(python:*)
metadata:
  author: jgraph
  source: https://github.com/jgraph/drawio-mcp
  skill_ref: https://linux.do/t/topic/1602943 (由mcp改为skill)
---

# Draw.io Diagram Generation

Generate draw.io diagrams by creating compressed URLs via Python and opening them in the browser.

## Configuration

### Working Directory
Current working directory: !`pwd`

### Language
- **Default**: `zh-CN` (Chinese)
- **Resolution order** (highest priority first):
  1. `$0` argument from `/drawio-diagram [language]` invocation
  2. Language preference explicitly mentioned in the user's request (e.g., "用英文画", "draw in Japanese")
  3. Default: `zh-CN`
- Diagram labels, notes, and descriptions should use the resolved language
- Technical terms (protocol names, opcodes, HTTP headers, status codes, framework names, etc.) MUST remain in English
- Examples:
  - `zh-CN`: "握手阶段" (not "Handshake Phase"), but keep "HTTP GET", "101 Switching Protocols"
  - `en`: "Handshake Phase", "HTTP GET", "101 Switching Protocols" (all English)

## Reference

Read [claude-project-instructions.md](references/claude-project-instructions.md) (relative to this skill file) for the complete diagram generation instructions, including:
- Supported diagram types
- Format selection guide (Mermaid / CSV / XML)
- Python URL generation code
- Format examples (Mermaid, XML, CSV syntax)

## Agent CLI Adaptation

The reference instructions mention "HTML artifact" — in Agent CLI environments there are no artifacts. Instead:

1. **Modify the Python script**: At the end of the script (after generating the URL), add `import webbrowser; webbrowser.open(url)` to directly open the draw.io URL in the default browser — no intermediate HTML page needed
2. **Save HTML backup**: Save the HTML to `{intent}-{type}-{timestamp}.html` in the current working directory (see Configuration > Working Directory above). Naming convention:
   - `{intent}`: 1-5 word kebab-case subject (e.g., `mqtt-conn`, `user-auth-flow`)
   - `{type}`: Abbreviated diagram type (e.g., `seq`, `flow`, `erd`, `arch`, `class`, `mind`)
   - `{timestamp}`: Format `YYYYMMDDHHMMSS`
   - Example: `mqtt-conn-seq-20260211143052.html`
   - **Retry / fix of a previous diagram** (e.g., user reports an error, asks for style tweaks, or requests content changes to the same diagram): Reuse the exact same filename to overwrite it
   - **Different diagram**: Generate a new filename

### URL Safety

**NEVER** manually type, copy, or reproduce generated URLs in text responses. The URL contains compressed base64 data — even a single character change breaks it. Always let the Python script generate the URL and embed it directly in the HTML file.

Overview

This skill generates draw.io diagrams programmatically and opens them in your browser. It creates compressed draw.io URLs from diagram definitions, saves an HTML backup file, and follows safe handling rules so URLs are never pasted in messages. Use it for flowcharts, architecture diagrams, UML, ERDs, sequence diagrams, org charts, mind maps, wireframes, and network topologies.

How this skill works

You write a diagram description in a supported format (Mermaid, CSV, or draw.io XML) and run the included Python helper. The script compresses the diagram, builds a draw.io URL, saves an HTML backup file with a timestamped name, and opens the URL in the default browser using webbrowser.open(url). The script enforces URL safety by keeping the generated URL out of chat output and by overwriting backups when reusing the same intent filename.

When to use it

When you need a ready-to-edit draw.io diagram from text input.
When converting architecture, sequence, class, ERD, or flowchart specifications into a visual diagram.
When you want the diagram opened directly in your browser for quick review or editing.
When you want a timestamped HTML backup saved for reproducibility or revision control.
When you need consistent filenames for retries or iterative edits.

Best practices

Provide a clear intent name (1–5 words, kebab-case) to produce meaningful backup filenames.
Choose the appropriate format: Mermaid for quick flow/sequence, CSV for simple tables/ERDs, XML for full draw.io control.
Keep technical terms in English to preserve protocol and API names; localize labels and notes to the resolved language if needed.
Reuse the exact filename when fixing or retrying a diagram to overwrite the previous HTML backup.
Do not paste or transmit the generated draw.io URL; let the script open it in your browser.

Example use cases

Generate a microservice architecture diagram from a short textual spec and open it for layout tweaks.
Create a sequence diagram for an API authentication flow and save the HTML backup for documentation.
Convert a CSV-based ERD into a draw.io diagram and iterate on table relationships visually.
Produce a wireframe or mockup from a structured description and share the screenshot or exported image (not the draw.io URL).
Make a network topology diagram for a lab environment and keep the timestamped HTML as a reproducible snapshot.

FAQ

Can I share the generated draw.io URL with others?

No. The compressed URL contains encoded diagram data and must not be pasted into messages. Share exported images or the HTML backup file instead.

How is the backup filename determined and when should I reuse it?

Filenames use the pattern {intent}-{type}-{timestamp}.html. Reuse the exact filename only when you are fixing or retrying the same diagram so the file is overwritten; otherwise a new timestamped file is created.

What language will diagram labels use?

Labels and notes will use the resolved language based on command arguments or explicit user preference. Technical terms remain in English to preserve accuracy.