bahayonghang-drawio-skills

Draw.io Skill for Claude, Gemini & Codex

Important: Draw.io Skill 2.2.0 is a YAML-first, offline-first base workflow. The default path is local generation through YAML/CLI -> .drawio + sidecars, optionally enhanced by draw.io Desktop for PNG/PDF/JPG and embedded SVG export. The next-ai-draw-io MCP server (@next-ai-drawio/mcp-server) is optional live refinement for the base skill only, not a hard dependency.

English | 中文文档 | Documentation

Draw.io Skill is a YAML-first draw.io authoring system for engineering diagrams, network diagrams, structured redraws, Mermaid/CSV conversion, and imported .drawio files. Publication-facing work is handled by an Academic Overlay that depends on the sibling base skill instead of copying its runtime.

Skill Variants

• skills/drawio: Draw.io Base Skill. Owns shared execution primitives: the CLI, schemas, general references, themes (including academic/academic-color), general examples, style presets, Desktop export helpers, diagrams.net URL fallback, and optional live refinement backend.
• skills/drawio-academic-skills: Academic Overlay. Owns academic policy and academic-specific assets: publication overlay docs (academic-figure-playbook.md, academic-export-checklist.md), paper/pipeline examples, README, and evals. It requires sibling ../drawio for execution and never requires MCP/live backend.

Boundary rule: themes and shared execution primitives live in the base; academic policy, academic docs, and paper examples live in the overlay. A standalone academic package can be generated later by a packaging workflow, but the repository model is base plus overlay.

Features

• YAML-first artifact bundle: keep .drawio, .spec.yaml, and .arch.json aligned for repeatable local editing.
• Desktop-aware export: use draw.io Desktop for PNG, PDF, JPG, and embedded .drawio.svg when available.
• Optional live refinement: configure next-ai MCP only for base-skill browser refinement; academic overlay stays offline.
• 3 core routes: create, edit, and replicate.
• 6 built-in themes: tech-blue, academic, academic-color, nature, dark, high-contrast.
• Academic overlay policy: venue/audience preflight, caption/legend checks, formula fidelity, A4/Word/LaTeX expectations, and figure typing.
• Academic figure taxonomy: publication requests classify into architecture, roadmap, or workflow before layout and export.
• Cloud and stencil support: AWS, GCP, Azure, Kubernetes, and network/provider icon workflows through the base references.
• Network topology support: semantic device types (router, switch, firewall, server, load_balancer, subnet, internet, ap) and automatic link labels from interface/IP/VLAN/bandwidth metadata.
• Import and normalize existing diagrams: convert .drawio into a YAML-first bundle with --input-format drawio --export-spec.
• Validation before export: structure, layout, quality, formula, and replication text-position checks.

Runtime Model

Use this order unless the request explicitly needs a browser session:

1. Offline Authoring Path: generate .drawio locally and keep sidecars in sync.
2. Desktop-Enhanced Export: use draw.io Desktop for raster/PDF and embedded SVG exports.
3. Live Refinement Backend: base-skill browser refinement only; the offline bundle remains canonical.
4. Direct XML Exception: tiny XML-only handoff or exact mxGraph control when YAML is not the right tool.

Academic overlay uses the first two paths only. It does not create, require, or route through .mcp.json, MCP, or live backend.

Install

Recommended

npx skills add bahayonghang/drawio-skills

Restart your client after installation so it reloads the skills.

Manual

1. Clone the repository.
2. Copy skills/drawio into your client's skill directory.
3. For publication-facing workflows, also copy skills/drawio-academic-skills next to drawio so the overlay can resolve sibling ../drawio.

Common locations: