Draw.io Academic Skill

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

This skill merges two workflows:

1. The upstream pure drawio-skill workflow: direct .drawio XML generation, Desktop export, self-check, style presets, diagrams.net URL fallback, and diagram-type presets.
2. 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:

1. Input type: new prompt, .spec.yaml, .drawio, image/SVG reference, or style preset.
2. Route from the table below, then load only the referenced files.
3. Deliverables needed: default bundle, plus any requested PNG/PDF/JPG.
4. Whether draw.io Desktop is required for the requested export.
5. 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

1. Classify the figure as architecture, roadmap, or workflow.

2. Draft the YAML spec as the canonical source.

3. Use concise labels; shorten labels before shrinking fonts.

4. 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

5. Use --strict or --strict-warnings for publication-grade checks.

6. Self-check the exported SVG/PNG when vision is available.

7. 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