Why use it: these two scripts are the semi-deterministic half of the import flow. They never make design decisions — they decode the source file and print out an IR (intermediate representation) that the agent reads to choose the diagram type and level of detail. Run them by hand when you want to see what the source contains before letting the agent draw, or when you need to plug them into a script/CI.
What this file produces: a Markdown digest (default, printed to stdout) or the full IR JSON (--json).
This entire file is shell commands. The corresponding slash-command version is at
05— do not mix the two.
1. Locate the script first
This is the number-one mistake. commands/import-drawio.md states clearly: "Never assume the skill is under the current working directory."
# tuỳ host, chọn cái nào tồn tại
SKILL_DIR=~/.claude/skills/diagram-design
SKILL_DIR=~/code/diagram-design/skills/diagram-design
SKILL_DIR=~/.config/opencode/skills/diagram-design
ls "$SKILL_DIR/scripts/"
expected: drawio_extract.py mermaid_extract.py self_check.py
---
## 2. `drawio_extract.py`
### Chữ ký thật (đọc từ `argparse` cuối file, không phải từ README)
```text
python3 drawio_extract.py <file> [--page N|NAME] [--json] [--max-rows N] [--out PATH]
| Parameter | Meaning |
|---|---|
file (required) |
.drawio / .xml / .drawio.png / .drawio.svg |
--page N|NAME |
select a page by index or name |
--json |
print the full IR (every node, every edge, every style) instead of the digest |
--max-rows N |
limit the number of table rows; must be ≥ 1, otherwise parser.error |
--out PATH |
write to a file instead of stdout |
What it can decode
The docstring says outright: the script "decodes whatever draw.io wrote (raw XML, deflate+base64 payloads, PNG/SVG files with an embedded mxfile), flattens the mxGraphModel into absolute-positioned nodes and edges."
This is why you must not read the file directly .drawio with cat — most of it is compressed, and the raw XML is noise.
Run it for real
python3 "$SKILL_DIR/scripts/drawio_extract.py" platform.drawio
Real output on the repo fixture (scripts/fixtures/sample-architecture.drawio):
# draw.io IR — sample\-architecture\.drawio
1 page(s): [0] Platform (12n/8e)
## Page 0 — Platform
- source canvas: 800×478 px (aspect 1.67)
- nodes: 12 total / 12 drawable / 2 containers, depth 1
- edges: 8 (7 labeled, 0 dangling), cycle: False
- shapes: {'rect': 5, 'swimlane': 2, 'cylinder': 2, 'rhombus': 1, 'aws': 1, 'note': 1}
- type candidates: flowchart, architecture
- budget: nodes OVER (max 9), edges ok (max 12)
- hubs (focal candidates): API Gateway(4), Auth Service(3), Orders Service(3), Web App · next\.js(1), Mobile App(1)
- entry points: Web App · next\.js, Mobile App
- terminals: Token valid?, Postgres, Redis, Object Store
- unconnected: Legacy path, to be retired
- collapsible groups (simplify here first):
- Core Services — 3 children: API Gateway, Auth Service, Orders Service
- Edge — 2 children: Web App · next\.js, Mobile App
How to read this digest:
budget: nodes OVER (max 9)— the source exceeds the budget. You will have to choose--detail=simplified, or accept zoning.hubs (focal candidates)— candidates for the focal node, ranked by degree.collapsible groups (simplify here first)— exactly where to merge first if you need to cut.unconnected— things in the source that connect to nothing; usually notes that should be dropped.
3. mermaid_extract.py
Real signature
python3 mermaid_extract.py <file> [--diagram N|all] [--json] [--max-rows N] [--out PATH]
Takes .mmd, .mermaid, and the Markdown file containing the block ```mermaid.
Supported grammar — exactly four: flowchart/graph, sequenceDiagram, stateDiagram-v2, erDiagram.
Trust boundary — the most important thing about this script
Docstring, verbatim:
"Trust boundary: this program parses bounded text. It never evaluates, renders, fetches, or executes Mermaid, JavaScript, URLs, directives, or label content. Every label and directive value is untrusted data. Click targets and styling are counted and discarded; retained labels are emitted only as inert text."
In other words: you can point it at Mermaid files from untrusted sources. It does not fetch, does not eval, does not follow click targets. The repo also has its own adversarial fixture — scripts/fixtures/sample-adversarial.mmd — and it runs rc=0 (clean parse, no blow-up).
Actually running it
python3 "$SKILL_DIR/scripts/mermaid_extract.py" architecture.mmd
Real output on scripts/fixtures/sample-flowchart.mmd:
# Mermaid IR — sample-flowchart.mmd
1 diagram(s): [0] flowchart (9n/7e)
## Diagram 0 — flowchart
- source layout: none (Mermaid is layout-free); direction: LR
- nodes: 9 total / 7 drawable / 2 containers, depth 1
- edges: 7 (4 labeled, 0 dangling), cycle: True
- shapes: {'rect': 3, 'container': 2, 'cylinder': 1, 'rhombus': 1, 'round': 1, 'stadium': 1}
- type candidates: flowchart, architecture
- budget: nodes ok (max 9), edges ok (max 12)
- hubs (focal candidates): API Gateway(6), Token valid?(3), Orders Service(2), Web App(1), Postgres(1)
Note the first line: source layout: none (Mermaid is layout-free). Unlike draw.io — draw.io has coordinates, Mermaid does not. Neither not has layout carried over to the output.
Markdown with multiple blocks
python3 "$SKILL_DIR/scripts/mermaid_extract.py" README.md
Real output:
# Mermaid IR — sample-readme-with-mermaid.md
2 diagram(s): [0] flowchart (3n/2e), [1] sequenceDiagram (3n/4e)
Select one block: --diagram 1. Export all: --diagram all.
4. Exit codes — NOT the 0/1 convention
Measured by actually running it, not by reading the docs:
| Command | rc | Meaning |
|---|---|---|
drawio_extract.py fixture.drawio |
0 |
ok |
mermaid_extract.py fixture.mmd |
0 |
ok |
mermaid_extract.py /nope.mmd |
2 |
file does not exist |
drawio_extract.py --badflag x |
2 |
usage error (argparse) |
mermaid_extract.py adversarial.mmd |
0 |
clean parse, no blow-up |
The docstrings of both scripts state it correctly: "Exit codes: 0 ok, 2 unreadable / unsupported input" and "0 success, 2 unreadable, unsupported, malformed, or over limits."
2 lumps together three things: broken input, unsupported input, and usage errors. That means in a calling script, rc == 2 cannot distinguish "the user's file is broken" from "I typed the flag wrong". To distinguish them you have to read stderr:
python3 "$SKILL_DIR/scripts/mermaid_extract.py" "$f" > ir.md 2> err.txt
rc=$?
case $rc in
0) echo "ok" ;;
2) echo "không đọc được / không hỗ trợ / sai cờ: $(cat err.txt)" ;;
*) echo "lỗi bất ngờ rc=$rc" ;;
esac
Real error format: mermaid_extract: /nope.mmd: no such file.
5. Handing the IR to the agent
The usual path: dump the IR to a file and tell the agent to read it.
python3 "$SKILL_DIR/scripts/drawio_extract.py" platform.drawio --out platform-ir.md
# stdout: wrote platform-ir.md (4123 bytes)
Then in chat: "Read platform-ir.md and redraw page 0 as an architecture diagram at slide-16x9, simplified."
If you need machine-readable IR, --json:
python3 "$SKILL_DIR/scripts/mermaid_extract.py" arch.mmd --json --out arch-ir.json
6. Three hard rules when redrawing (apply to both sources)
From commands/import-drawio.md §"Required behaviour" and the corresponding Mermaid version:
- Digest reports 0 nodes → the source is an image or is encrypted. Say so plainly, ask for the original file. Do not make up content.
- Never carry over the source's coordinates, colors, or fonts. The output is a redraw in the
style-guide.mdskin. For Mermaid additionally: do not render Mermaid, do not carry over its computed theme/class/layout. --detail=faithfulon 9 nodes → the layout must be zoned; on 24 nodes → split into an overview file + a detail file.
7. This step is done when
- The extractor runs on your real file, rc=0.
- You can read the line
budget:and know you'll need the leveldetail. - Knowing
rc=2is combined and your calling script reads stderr.
Next: 05-import-export-slash-commands.md — the chat part for the agent to redraw and export the file.