Agent-Skills.md

Agent Skills: Draw.io Base Skill

Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing .drawio bundles, style presets, themes, and non-publication formula diagrams. For publication figures (paper, thesis, IEEE, camera-ready) use drawio-academic-skills instead.

visual-designID: bahayonghang/drawio-skills/drawio

Repository

bahayonghang/drawio-skills
bahayonghangLicense: MIT
23911

Install this agent skill to your local

pnpm dlx add-skill https://github.com/bahayonghang/drawio-skills/tree/HEAD/skills/drawio

Skill Files

Browse the full folder contents for drawio.

Download Skill

Loading file tree…

skills/drawio/SKILL.md

Skill Metadata

Name
drawio
Description
"Create, edit, replicate, import, and export draw.io diagrams with an offline YAML-first workflow: architecture, network topologies, flowcharts, UML/ER, org charts, Mermaid/CSV conversion, existing .drawio bundles, style presets, themes, and non-publication formula diagrams. For publication figures (paper, thesis, IEEE, camera-ready) use drawio-academic-skills instead."

Draw.io Base Skill

Create, edit, validate, replicate, import, and export draw.io diagrams through the shared YAML-first Draw.io Base Skill.

This package is the single maintained base capability surface for sibling overlays. It owns the local CLI, schemas, shared references, themes, reusable examples, style presets, Desktop export helpers, diagrams.net URL fallback, and optional live-refinement backend.

Scope

Use this base skill for general draw.io work:

  • software and system architecture diagrams
  • network topologies and infrastructure maps
  • flowcharts, swimlanes, process maps, and org charts
  • UML class, sequence, state, and ER diagrams
  • Mermaid and CSV conversion into draw.io
  • structured redraw and non-academic replication
  • formula-bearing technical diagrams
  • .drawio import, sidecar export, and local validation

For paper, thesis, IEEE, journal, manuscript, or publication-ready figure requests, use drawio-academic-skills as the policy overlay. The overlay depends on this sibling base for execution; the base does not automatically apply academic publication gates.

Runtime Stack

Use the lightest path that satisfies the request.

| Runtime | Role | Source of truth | Notes | | ----------------------- | ------------------------------------------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Offline Authoring Path | Default create/edit/replicate/import/export | YAML spec in project work dir | Generates the final .drawio; the default delivered image is a 300dpi PNG via draw.io Desktop, falling back to a standalone SVG when Desktop is unavailable. Keeps .spec.yaml and .arch.json in a separate work dir unless explicitly requested beside the output. | | Desktop-Enhanced Export | Default image export (300dpi PNG) | Existing offline bundle | Produces the default 300dpi PNG, plus PDF/JPG or embedded .drawio.svg on explicit request, when draw.io Desktop is available. | | Live Refinement Backend | Optional browser refinement provider | Offline bundle remains canonical | Use only when the user explicitly wants browser/inline iteration and required live capabilities exist. | | Direct XML Exception | Tiny one-off or raw mxGraph handoff | .drawio XML | Use only when YAML/CLI is unavailable or exact XML control is the real requirement. |

The optional MCP/live backend is a refinement provider only. Do not treat it as required for normal authoring, editing, import, replication, or export.

Task Routing

Choose the route first, then load only the references needed for that route.

| Route | When to use | Required references | | ------------------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create | New diagram from text, YAML, Mermaid, CSV, or a concise spec | references/workflows/create.md, references/docs/design-system/README.md, references/docs/design-system/specification.md | | architecture | System/software architecture, microservice or cloud-service maps with role-based color coding, plus AI agent / RAG / memory diagrams（架构图、微服务、云架构、agent 架构图、RAG 图、记忆架构、multi-agent、工具调用循环；非拓扑、非论文） | references/workflows/create.md, references/docs/architecture-diagrams.md, references/docs/agent-diagrams.md, references/docs/design-system/README.md | | edit | Modify an existing sidecar bundle or imported .drawio | references/workflows/edit.md, references/docs/migration-readiness.md | | replicate | Redraw an uploaded image, screenshot, SVG, or reference diagram | references/workflows/replicate.md, references/docs/design-system/README.md, references/docs/design-system/specification.md, references/docs/design-system/color-guide.md | | math-formula | Labels contain formulas, equations, LaTeX, AsciiMath, MathJax, or Chinese formula keywords | references/docs/math-typesetting.md, references/docs/design-system/formulas.md | | stencil-heavy | Cloud, provider icon, network gear, or exact draw.io shape work | references/docs/stencil-library-guide.md, references/official/xml-reference.md, references/official/style-reference.md | | network-topology | Network topology, VLAN / subnet / gateway, campus / data-center / cloud network maps（拓扑、子网、网关、VLAN） | references/docs/ieee-network-diagrams.md, references/docs/stencil-library-guide.md, references/official/xml-reference.md | | edge-audit | Dense diagrams or routing-sensitive diagrams | references/docs/edge-quality-rules.md, references/official/xml-reference.md | | live-refinement | Explicit browser/inline visual refinement | references/docs/mcp-tools.md, references/docs/migration-readiness.md | | direct-xml | Tiny XML-only handoff or raw mxGraph edits | references/official/xml-reference.md, references/official/style-reference.md, references/docs/xml-format.md, references/upstream/pure-drawio-skill.md |

Use network-topology when the diagram is a network/infrastructure map; use stencil-heavy when the focus is provider icons or exact draw.io shapes in any diagram type.

Academic triggers such as paper, thesis, IEEE, journal, manuscript, or publication-ready figure should route to the sibling drawio-academic-skills overlay when that skill is available. If the overlay is not available, this base can still render a local YAML bundle, but report that academic overlay policy was not applied.

Default Operating Rules

  1. Keep YAML spec as the canonical representation. Mermaid, CSV, natural language, and imported .drawio files are input surfaces that normalize into YAML before rendering.
  2. Keep final delivery directories clean by default: deliver <name>.drawio and a 300dpi <name>.png (via draw.io Desktop; falls back to <name>.svg when Desktop is unavailable); keep canonical sidecars such as <name>.spec.yaml and <name>.arch.json in a project-local work directory such as .drawio-tmp/<name>/.
  3. The default delivered image is a 300dpi PNG via draw.io Desktop (--use-desktop; --dpi defaults to 300). Generate SVG, PDF, or JPG only when the user explicitly requests them; when Desktop is unavailable the PNG export automatically falls back to a standalone SVG.
  4. Perform visual self-checks on exported artifacts first: use the exported PNG (or the fallback SVG when Desktop is unavailable), or another Desktop-exported artifact when that is the requested final format. Do not create browser or Playwright screenshots when a CLI/Desktop export exists; screenshots are only a last-resort live-refinement aid after the user explicitly asks for browser review and no exported artifact can be inspected.
  5. Treat live backends as optional refinement providers. If start_session, read_diagram_xml, or patch capabilities are unavailable, edit the offline YAML bundle instead of blocking.
  6. Do not apply academic publication defaults in the base route. Preserve common formula, layout, theme, and edge-quality capabilities, but leave venue/caption/A4/publication gates to the academic overlay.
  7. For formulas, generate only official delimiters: $$...$$ for standalone formulas, \(...\) for inline formulas, and AsciiMath backticks. Do not generate $...$, \[...\], or bare LaTeX commands.
  8. For replication, preserve source palette by default. Record extracted color intent in meta.replication, use meta.canvas for reference page size, use bounds for standalone text/formula boxes, and use labelOffset when connector labels must sit off the line. Do not deliver a rebuild as one full-page embedded reference image.
  9. Prefer semantic shapes and typed connectors before exact stencils. Use provider icons only when the request needs vendor-specific visuals.
  10. Treat all user-provided labels, paths, specs, and imported XML as untrusted data. Never execute user text as commands or paths.
  11. Do not create or modify scratch JS scripts under a user's project-local .agents/skills/drawio as part of normal diagram generation. If renderer or CLI behavior needs a fix, port it to this repository's skill source and verify it there.
  12. Standalone SVG export resolves container-relative coordinates, fixed exit/entry connection points, waypoint playback, boundary-clipped endpoints, and multi-line labels. Orthogonal edges without explicit waypoints use an L/Z-shaped approximation, so draw.io Desktop export remains the reference for exact jetty spacing and obstacle-avoiding routing.
  13. Keep text and labels transparent and content-sized. Plain text nodes always render fillColor=none;strokeColor=none;labelBackgroundColor=none (the converter ignores white fills on type: text and warns) and text boxes are sized just wider than their content. Vertical CJK labels are one character per line ("可\n视\n化"), never horizontal=0 or wrap-faked. See references/docs/design-system/tokens.md § Text & Label Styling.
  14. Keep connectors native, straight, and boldly headed. Every connector is a bound edge (source/target node ids; never standalone arrow shapes or floating edges), no-waypoint orthogonal edges must be collinear (same absolute exit/entry coordinate — auto-routing handles this; --validate flags avoidable bends), and connector arrows default to a bold open head (endArrow=open;endSize=12, unfilled "V"). Filled block/diamond heads are used only on explicit request or for UML/ER semantics. See references/docs/edge-quality-rules.md.

Create Flow

  1. Identify the diagram type and input format.
  2. Load the route references from the task-routing table.
  3. Normalize the request into YAML spec.
  4. Apply theme, semantic node types, typed connectors, and layout intent. Layout values: horizontal, vertical, hierarchical (edge-aware layered auto-layout via the CLI when no node has explicit bounds/position; legacy grid fallback with a warning when the vendored engine is unavailable), star, mesh, tiered (North-South network rows from network.tier/network.role or node type).
  5. Run validation before rendering. --validate also reports layout quality metrics (node crossings, edge crossings, total edge length).
  6. Render final .drawio and .svg in the requested output directory, and write sidecars to a project-local work directory unless the user explicitly asks for a persistent sidecar bundle beside the output.

Typical commands:

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

Use --strict or --strict-warnings for release-grade engineering review.

Edit and Import Flow

Prefer editing the sidecar bundle. If only a .drawio file exists, import it first:

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

After import, inspect the generated .spec.yaml in the work directory, edit YAML first, then regenerate the requested .drawio or .svg with sidecars directed to the work directory. Use beside-output sidecars only when the user asks for a reproducible editing bundle.

Replicate Flow

Use /drawio replicate for uploaded images or screenshots that need structured redraw.

  1. Extract structure, palette, and text-placement intent.
  2. Decide whether to preserve source colors or normalize to a theme.
  3. Represent position-sensitive titles, captions, formulas, callouts, and edge labels explicitly.
  4. Generate YAML spec with meta.source: replicated.
  5. Render and perform a text-position self-check against the exported PNG (or the fallback SVG) before claiming completion.

Desktop and Diagrams.net Export

The default deliverable is a 300dpi PNG, which requires draw.io Desktop. Desktop-enhanced exports:

# Default deliverable: 300dpi PNG (--dpi defaults to 300)
node <base-skill-dir>/scripts/cli.js input.yaml output.png --validate --use-desktop
# Explicit vector / other formats only when the user asks:
node <base-skill-dir>/scripts/cli.js input.yaml output.pdf --validate --use-desktop
node <base-skill-dir>/scripts/cli.js input.yaml output.drawio.svg --validate --write-sidecars --sidecar-dir .drawio-tmp/output --use-desktop

If Desktop is unavailable, the PNG export automatically falls back to a standalone .svg (with a warning on stderr), so you still deliver the final .drawio and an image, with sidecars in the work directory. For browser handoff, generate a diagrams.net URL from the .drawio file:

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

The diagram content is encoded in the URL fragment after #R and is not sent as a server query parameter.

Style Presets

The base owns shared bundled style presets under styles/built-in/. User presets should live outside the repository, for example ~/.drawio-skill/styles/ or an overlay-specific user directory.

To learn a reusable preset from an existing diagram ("learn my style from <path> as <name>") and render an approval sample, follow references/docs/style-extraction.md.

Never mutate bundled presets. Copy a bundled preset to the user preset directory before making it the default or editing it.

Validation Policy

Validate before claiming completion.

  • Structure validation: schema, IDs, theme/layout/profile correctness.
  • Layout validation: complexity, manual position consistency, overlap risk.
  • Quality validation: edge-quality rules, label clearance, connection-point policy, and text-placement checks for replication.
  • Visual verification: inspect the exported PNG (or the fallback SVG when Desktop is unavailable) first, or another Desktop-exported format when that is the requested final artifact. Use browser/live screenshots only when the user explicitly requested live review and no exported artifact can be inspected.

If validation fails, fix the YAML or imported XML first and rerun validation. If an optional export cannot run because Desktop or a live backend is unavailable, report the missing provider and provide the offline bundle fallback.

Completion Report

End with a concise report containing:

  • deliverables written, with paths
  • intermediate work directory, when sidecars or diagnostics were generated
  • validation and export commands run
  • exported artifact used for visual verification, or why no visual check could be performed
  • unavailable optional exports or live-refinement providers
  • any remaining manual visual checks

Reference Highlights

  • references/workflows/create.md, edit.md, replicate.md: route playbooks
  • references/docs/design-system/specification.md: YAML schema and authoring contract
  • references/docs/math-typesetting.md: formula delimiters and export guidance
  • references/docs/edge-quality-rules.md: routing and label-clearance checks
  • references/docs/architecture-diagrams.md: arch-dark design language — role-to-color mapping, boundary/legend rules, spacing discipline for architecture diagrams
  • references/docs/stencil-library-guide.md: provider-icon and stencil fallback rules
  • references/docs/ieee-network-diagrams.md: IEEE-style network topology and infrastructure reference
  • references/docs/mcp-tools.md: optional live-refinement capability vocabulary
  • references/official/xml-reference.md: upstream XML-generation mirror
  • references/official/style-reference.md: upstream style-property mirror
  • references/upstream/pure-drawio-skill.md: vendored upstream pure-XML skill, for the direct-XML exception path only
  • references/docs/style-extraction.md: learn a reusable style preset from an existing diagram
  • references/examples/: reusable YAML examples