Draw.io Academic Skill

Create, edit, replicate, validate, and export publication-ready draw.io figures.

This skill merges two workflows:

The upstream pure drawio-skill workflow: direct .drawio XML generation, Desktop export, self-check, style presets, diagrams.net URL fallback, and diagram-type presets.
This repository's skills/drawio workflow: YAML-first authoring, offline sidecars, academic quality gates, formula handling, and SVG conversion.

Non-Negotiable Contract

Keep this fork academic-first and offline-first.
Never create, require, or route through .mcp.json or an MCP backend.
Treat the YAML spec plus .drawio, .arch.json, and .svg outputs as the normal editable bundle.
Use draw.io Desktop only as an optional export enhancer for PNG/PDF/JPG or embedded .drawio.svg.
When a requested export cannot be produced locally, still deliver the editable bundle and report the unavailable export clearly.

Runtime Decision

Default to the offline academic path.

Priority	Runtime	Use for
1	YAML/CLI offline bundle	New academic figures, paper diagrams, repeatable edits
2	draw.io Desktop CLI	PNG/PDF/JPG, embedded `.drawio.svg`, final raster export
3	direct XML fallback	Tiny one-off diagrams, CLI unavailable, handoff-only XML
4	diagrams.net URL fallback	User cannot install Desktop but can open browser URL

This skill intentionally ships without .mcp.json. Use Desktop CLI or the diagrams.net URL fallback for handoff and refinement.

Preflight Checklist

Before generating or editing, decide and state:

Input type: new prompt, .spec.yaml, .drawio, image/SVG reference, or style preset.
Route from the table below, then load only the referenced files.
Deliverables needed: default bundle, plus any requested PNG/PDF/JPG.
Whether draw.io Desktop is required for the requested export.
Fallback plan if Desktop or validation is unavailable.

Task Routing

Choose one route first, then load only the referenced files.

Route	Trigger	Load
`academic-create`	paper, thesis, IEEE, manuscript, journal figure	`references/docs/academic-figure-playbook.md`, `references/docs/academic-export-checklist.md`, `references/workflows/create.md`
`math-formula`	formula, equation, LaTeX, AsciiMath, MathJax, 公式	`references/docs/math-typesetting.md`, `references/docs/design-system/formulas.md`
`edit`	modify an existing `.drawio`, YAML bundle, or previous output	`references/workflows/edit.md`, `references/docs/migration-readiness.md`
`replicate`	redraw screenshot, image, SVG, or reference diagram	`references/workflows/replicate.md`, `references/docs/design-system/color-guide.md`
`stencil-heavy`	cloud, network, AWS, Azure, GCP, Cisco, Kubernetes	`references/docs/stencil-library-guide.md`, `references/official/xml-reference.md`
`style-preset`	learn/use/list/delete/rename visual style presets	`references/docs/style-presets.md`, `references/docs/upstream-pure-drawio-skill.md`

Academic Defaults

For academic-paper requests, set these before rendering:

meta.profile: academic-paper
meta.figureType: exactly one of architecture, roadmap, or workflow
meta.theme: academic by default, or academic-color when color is useful
meta.title: caption-ready figure title
meta.description: one sentence explaining the figure intent

Default deliverables:

<name>.drawio
<name>.spec.yaml
<name>.arch.json
<name>.svg

Add <name>.png only when the user asks for PNG, Word, thesis/A4, raster-first, or screenshot matching, and draw.io Desktop export is available.

Create Flow

Classify the figure as architecture, roadmap, or workflow.
Draft the YAML spec as the canonical source.
Use concise labels; shorten labels before shrinking fonts.

Validate before rendering:

node <skill-dir>/scripts/cli.js input.yaml output.drawio --validate --write-sidecars
node <skill-dir>/scripts/cli.js input.yaml output.svg --validate --write-sidecars

Use --strict or --strict-warnings for publication-grade checks.
Self-check the exported SVG/PNG when vision is available.
Apply targeted edits to YAML or XML, re-render, and repeat until approved.

Edit and Replicate Flow

If a .spec.yaml sidecar exists, edit the YAML spec first.

If only .drawio exists, import it before editing:

node <skill-dir>/scripts/cli.js existing.drawio --input-format drawio --export-spec --write-sidecars

After import, inspect the generated .spec.yaml and .arch.json, apply edits to the YAML spec, then regenerate the requested .drawio or .svg with --write-sidecars.
Keep all regenerated files on the same basename so the bundle remains round-trippable.
For image/SVG replication, extract palette intent first and preserve the source palette unless the user asks for paper-safe recoloring.
For major structural changes, show an ASCII logic draft before rendering.
Preserve <name>.drawio, <name>.spec.yaml, and <name>.arch.json together.

Export Policy

Use the local CLI for deterministic exports.

# Offline SVG and sidecars
node <skill-dir>/scripts/cli.js input.yaml figure.svg --validate --write-sidecars

# Editable .drawio bundle
node <skill-dir>/scripts/cli.js input.yaml figure.drawio --validate --write-sidecars

# Desktop-enhanced exports
node <skill-dir>/scripts/cli.js input.yaml figure.drawio.svg --validate --write-sidecars --use-desktop
node <skill-dir>/scripts/cli.js input.yaml figure.png --validate --use-desktop
node <skill-dir>/scripts/cli.js input.yaml figure.pdf --validate --use-desktop

Desktop CLI supports PNG/SVG/PDF/JPG. PNG/SVG/PDF exports can embed the editable diagram XML.

If Desktop is unavailable, generate a diagrams.net URL:

node <skill-dir>/scripts/runtime/diagrams-net-url.js figure.drawio

The diagram XML is encoded after #R in the URL fragment. The fragment is client-side and is not sent to diagrams.net servers.

If Desktop is unavailable for PNG/PDF/JPG, do not pretend those files exist. Deliver .drawio, .spec.yaml, .arch.json, and .svg, then include the diagrams.net URL or the exact Desktop command the user can run later.

Style Presets

Use user presets from ~/.drawio-academic-skills/styles/ first, then bundled presets from styles/built-in/.

Supported operations:

learn a style from .drawio, .xml, .svg, .png, .jpg, or .jpeg
preview a generated sample before saving
list presets
set one user preset as default
rename or delete user presets

Never mutate bundled presets. Copy a bundled preset into ~/.drawio-academic-skills/styles/ before making it a default.

Failure Recovery

Use these fallbacks before stopping:

Failure	Recovery
YAML validation fails	Fix the YAML spec first, then rerun the same CLI command with `--validate`.
`.drawio` import is incomplete	Preserve the original file, export the partial spec, and report unsupported shapes or styles explicitly.
Desktop export fails or Desktop is missing	Regenerate the offline bundle and SVG, then provide a diagrams.net URL fallback.
Formula rendering is wrong	Recheck delimiters against the math reference, then simplify the label before changing layout.
SVG/PNG self-check finds overlap	Edit labels or routing in YAML/XML and re-render; do not only describe the issue.

Quality Gate

Do not claim completion until:

.drawio, .spec.yaml, .arch.json, and .svg are aligned
academic profile has a valid figureType
labels are readable at paper/A4 scale
formulas use official delimiters: $$...$$, $...$, or AsciiMath backticks
connector routing is readable
colors are not the only carrier of meaning
requested PNG/PDF/JPG exports were attempted through draw.io Desktop or clearly reported as unavailable
no MCP config, MCP server, or live backend is required for the result

Completion Report

End with a concise report:

Deliverables written, with paths.
Commands run for validation/export.
Any unavailable exports and the fallback provided.
Remaining manual checks, if visual inspection or Desktop export could not run.

Reference Files

references/docs/upstream-pure-drawio-skill.md: preserved upstream pure SKILL.md workflow
references/docs/academic-figure-playbook.md: academic figure typing and delivery rules
references/docs/academic-export-checklist.md: paper-ready checklist
references/docs/math-typesetting.md: formula syntax and export guidance
references/official/xml-reference.md: draw.io XML mirror
references/official/style-reference.md: draw.io style mirror
references/examples/: reusable YAML examples
styles/built-in/: upstream pure-skill style presets
assets/themes/: YAML/CLI design-system themes