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:

bash

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:

bash

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.

bash

# 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:

bash

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

drawio-academic-skills

NPX Install

Tags

SKILL.md Content

Draw.io Academic Skill

Non-Negotiable Contract

Runtime Decision

Preflight Checklist

Task Routing

Academic Defaults

Create Flow

Edit and Replicate Flow

Export Policy

Style Presets

Failure Recovery

Quality Gate

Completion Report

Reference Files