drawio-academic-skills（绘制学术技能）

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.

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.

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:

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