drawio-skills
drawio skills for cc,codex
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/bahayonghang-drawio-skills)HTML
<a href="/listings/bahayonghang-drawio-skills"><img src="/api/listings/bahayonghang-drawio-skills/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Project-level Installation for Diagram Replication (Recommended)
To replicate draw.io diagrams with superior fidelity, install [drawio-scientific-illustrator](https://github.com/bahayonghang/drawio-scientific-illustrator/tree/dev) (`dev` branch) at the project level (which works better for replication than this skills package):
- **Claude (Project Level)**:
git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .claude/skills/drawio-scientific-illustrator
- **Codex (Project Level)**:
git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .codex/skills/drawio-scientific-illustrator
Standard Base Skill Installation
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:
- **Claude** - macOS: `~/Library/Application Support/Claude/skills/` - Linux: `~/.config/Claude/skills/` - Windows: `%APPDATA%\Claude\skills\` - **Codex** - macOS / Linux: `~/.codex/skills/` - Windows: `%USERPROFILE%\.codex\skills\`
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 326 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # Draw.io Skill for Claude & Codex
- [](https://github.com/bahayonghang/drawio-skills/actions/workflows/deploy-docs.yml)
- [](https://spdx.org/licenses/MIT.html)
- > **Important**: Draw.io Skill 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](https://github.com/DayuanJiang/next-ai-draw-io) MCP server (`@next-ai-drawio/mcp-server`) is optional **live refinement** for the base skill only, not a hard dependency.
- >
- > **Recommendation for Diagram Replication**: For replicating draw.io diagrams, using the `dev` branch of [drawio-scientific-illustrator](https://github.com/bahayonghang/drawio-scientific-illustrator/tree/dev) produces significantly better results than using this skills package.
- [English](./README.md) | [中文文档](./README_CN.md) | [Documentation](https://bahayonghang.github.io/drawio-skills/)
- 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.
- ## Recommended Models
- - **GPT Sol Max**
- - **Claude Fable 5**
- - **Claude Opus 5**
- ## 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`.
- - **7 built-in themes**: `tech-blue`, `academic`, `academic-color`, `nature`, `dark`, `arch-dark`, `high-contrast`. `arch-dark` carries the architecture design language adapted from architecture-diagram-generator (MIT, Cocoon AI).
- - **15 built-in palettes**: academic, engineering, and general color groups compose independently with themes and carry colorblind, grayscale, category-capacity, and source metadata.
- - **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.
- - **Embedded AI, brand, and Lucide icons**: use 309 licensed offline `lobe.*` / `ai.*` AI/LLM logos, `brand.redis`, and a curated `lucide.*` set for common semantic roles without runtime network access. SysML (`mxgraph.sysml.*`) and BPMN (`mxgraph.bpmn.*`) base names are searchable too.
- - **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.
- - **Offline config and IaC import**: turn declared Terraform, Kubernetes, Compose, SQL DDL, OpenAPI, GitHub Actions, or GitLab CI into a canonical diagram — no provider CLI, Graphviz, or network.
- - **Code relationship import**: render Python, JavaScript/TypeScript, Go, or Rust module/class relationships from a local project directory.
- - **Live snapshots and drift**: project saved Terraform state, Docker inspect, or Kubernetes live JSON, and compare a declared-vs-live projection to render architecture drift.
- - **Multi-page bundles and postprocess**: author canonical bundle v1 with stable page/object identity, and project or transform diagrams offline with `mermaid`, `explain`, `relabel`, `restyle`, `heatmap`, or script-free `html`.
- - **Local PNG/JPEG assets**: register files under top-level `assets` and place them with `node.image`. Paths are relative to `--asset-root` (default cwd). SVG and multi-page `assets` are out of v1.
- - **Import and normalize existing diagrams**: convert `.drawio` into a YAML-first bundle with `--input-format drawio --export-spec` (add `--all-pages` for multi-page bundles; add `--extract-assets` for foreign embedded rasters).
- - **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
- ### Project-level Installation for Diagram Replication (Recommended)
- To replicate draw.io diagrams with superior fidelity, install [drawio-scientific-illustrator](https://github.com/bahayonghang/drawio-scientific-illustrator/tree/dev) (`dev` branch) at the project level (which works better for replication than this skills package):
- - **Claude (Project Level)**:
- ```bash
- git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .claude/skills/drawio-scientific-illustrator
- ```
- - **Codex (Project Level)**:
- ```bash
- git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .codex/skills/drawio-scientific-illustrator
- ```
- ### Standard Base Skill Installation
- ```bash
- 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:
- - **Claude**
- - macOS: `~/Library/Application Support/Claude/skills/`
- - Linux: `~/.config/Claude/skills/`
- - Windows: `%APPDATA%\Claude\skills\`
- - **Codex**
- - macOS / Linux: `~/.codex/skills/`
- - Windows: `%USERPROFILE%\.codex\skills\`
- ## Optional Live Editing Setup
- Normal create/edit/export work does **not** require MCP. Configure `@next-ai-drawio/mcp-server` only when you want base-skill browser refinement.
- Academic overlay does not need this setup.
- ### Claude JSON config
- macOS / Linux:
- ```json
- {
- "mcpServers": {
- "drawio": {
- "command": "npx",
- "args": ["--yes", "@next-ai-drawio/mcp-server@latest"]
- }
- }
- }
- ```
- Windows:
- ```json
- {
- "mcpServers": {
- "drawio": {
- "type": "stdio",
- "command": "cmd",
- "args": ["/c", "npx", "--yes", "@next-ai-drawio/mcp-server@latest"]
- }
- }
- }
- ```
- ### Codex `config.toml`
- macOS / Linux:
- ```toml
- [mcp_servers.drawio]
- command = "npx"
- args = ["--yes", "@next-ai-drawio/mcp-server@latest"]
- ```
- Windows:
- ```toml
- [mcp_servers.drawio]
- type = "stdio"
- command = "cmd"
- args = ["/c", "npx", "--yes", "@next-ai-drawio/mcp-server@latest"]
- ```
- ## Quick Start
- Create a new diagram:
- ```text
- /drawio create a horizontal tech-blue login flow with 6 nodes
- ```
- Create a network topology with structured metadata:
- ```text
- /drawio create a tech-blue network topology with a firewall, core switch, two app servers, and a private database subnet. Label interfaces and VLANs on the links.
- ```
- Create a publication figure with the overlay:
- ```text
- /drawio-academic-skills create an IEEE-style workflow figure for a manuscript. Deliver .drawio + .spec.yaml + .arch.json + .svg.
- ```
- Import an existing `.drawio` file into the offline bundle:
- ```bash
- node skills/drawio/scripts/cli.js existing.drawio --input-format drawio --export-spec --write-sidecars
- ```
- Render and validate a bundle:
- ```bash
- node skills/drawio/scripts/cli.js input.yaml output.drawio --validate --write-sidecars
- node skills/drawio/scripts/cli.js input.yaml output.svg --validate --write-sidecars
- ```
- Use mixed provider, Lobe, brand, and Lucide icons:
- ```yaml
- nodes:
- - id: lambda
- label: AWS Lambda
- icon: aws.lambda
- - id: openai
- label: OpenAI document understanding
- icon: lobe.openai
- - id: claude
- label: Claude reasoning
- icon: ai.anthropic
- - id: redis
- label: Redis cache
- icon: brand.redis
- - id: cache
- label: Cache fallback
- icon: lucide.database-zap
- - id: ops
- label: Server operations
- icon: lucide.server-cog
- ```
- Common `lobe.*` / `ai.*` icons such as OpenAI, Claude, and Gemini are embedded
- as normalized SVGs for reliable offline rendering. Unsupported Lobe names fail
- shape validation instead of creating remote image links. `brand.*` is for the
- bundled non-AI brand fallbacks; the curated `lucide.*` set is embedded as data
- URI SVGs and should not be treated as official brand logos. Supported examples
- include `lucide.alarm-clock`, `lucide.server-cog`, and `lucide.workflow`.
- Lobe and Lucide attribution files ship under `skills/drawio/assets/licenses/`.
- Academic overlay still uses the sibling base CLI:
- ```bash
- node skills/drawio/scripts/cli.js skills/drawio-academic-skills/references/examples/system-architecture-paper.yaml academic-system.svg --validate --write-sidecars --strict-warnings
- ```
- Use draw.io Desktop when you need raster or PDF export:
- ```bash
- node skills/drawio/scripts/cli.js input.yaml output.pdf --validate --use-desktop
- node skills/drawio/scripts/cli.js input.yaml output.png --validate --use-desktop
- ```
- Generate a diagrams.net URL fallback from a `.drawio` file:
- ```bash
- node skills/drawio/scripts/runtime/diagrams-net-url.js output.drawio
- ```
- ## Canonical Artifact Bundle
- When the diagram will continue evolving, keep these files together:
- - `<name>.drawio`
- - `<name>.spec.yaml`
- - `<name>.arch.json`
- Academic overlay adds standalone SVG as part of the default publication bundle:
- - `<name>.svg`
- PNG/PDF/JPG are Desktop-enhanced optional outputs and should be reported as unavailable if draw.io Desktop is missing.
- ## Network Topology Authoring
- The current network-topology workflow supports:
- - semantic node types such as `router`, `switch`, `firewall`, `server`, `load_balancer`, `subnet`, `internet`, and `ap`
- - link metadata fields such as `srcInterface`, `dstInterface`, `ip`, `vlan`, `bandwidth`, and `linkType`
- - layout intents `hierarchical`, `star`, and `mesh`
- - provider-aware icon mapping through explicit `icon` fields or `network.vendor` + `network.device`
- Representative specs ship in `skills/drawio/references/examples/`.
- Render one directly:
- ```bash
- node skills/drawio/scripts/cli.js skills/drawio/references/examples/vendor-device-mapping.yaml output.drawio --validate --write-sidecars
- ```
- ## Offline Importers and Adapters
- Beyond `create` / `edit` / `replicate`, the offline base promotes a batch of upstream capabilities behind the same canonical boundary. Every route normalizes its input to canonical YAML or multi-page bundle v1 before validation, JavaScript ELK layout, and the renderer — no provider CLI, Graphviz, network, Desktop, browser, MCP, or model is required. Optional parsers and exports report precise missing dependencies or fallbacks.
- | Route | Input | `--input-format` / command |
- | ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
- | `config-import` | Terraform, Kubernetes, Compose, SQL DDL, OpenAPI, GitHub Actions, GitLab CI | `terraform` / `kubernetes` / `compose` / `sql` / `openapi` / `github-actions` / `gitlab-ci` |
- | `code-import` | local Python, JS/TS, Go, Rust project directory | `python-imports` / `python-classes` / `js-imports` / `go-imports` / `rust-imports` |
- | `live-drift` | saved Terraform state, Docker inspect, Kubernetes live JSON | snapshot adapters + `compareGraphProjections` |
- | `multi-page` | canonical bundle v1 | `--input-format drawio --all-pages --export-spec` |
- | `raster-replicate` | trusted structured visual extraction | `raster-extraction` |
- | `postprocess` | canonical YAML / `.drawio` | `postprocess mermaid\|explain\|relabel\|restyle\|heatmap\|html` |
- The shipped postprocess operations are exactly `mermaid`, `explain`, `relabel`, `restyle`, `heatmap`, and script-free `html`; runbook, animated SVG, tube/sequence layout, compression, buildup, PPTX, timelapse, and PR diff are deferred, not hidden commands. Deterministic paths are command evidence; Desktop, provider, browser/MCP, and visual-model runs remain reported as missing evidence when not executed. The full upstream job-to-capability map lives at `skills/drawio/references/docs/upstream-capability-compatibility.md`.
- ## Documentation
- - [Getting Started](https://bahayonghang.github.io/drawio-skills/guide/getting-started)
- - [Workflows](https://bahayonghang.github.io/drawio-skills/guide/workflows)
- - [Config and IaC Importers](https://bahayonghang.github.io/drawio-skills/guide/config-importers)
- - [Code Relationship Importers](https://bahayonghang.github.io/drawio-skills/guide/code-importers)
- - [Live Snapshots and Drift](https://bahayonghang.github.io/drawio-skills/guide/live-drift)
- - [Multi-page Bundles](https://bahayonghang.github.io/drawio-skills/guide/multi-page)
- - [Postprocess Suite](https://bahayonghang.github.io/drawio-skills/guide/postprocess)
- - [Upstream Capability Map](https://bahayonghang.github.io/drawio-skills/api/upstream-capability-map)
- - [CLI Tool](https://bahayonghang.github.io/drawio-skills/guide/cli)
- - [Optional MCP Tools](https://bahayonghang.github.io/drawio-skills/api/mcp-tools)
- - [Examples](https://bahayonghang.github.io/drawio-skills/examples/)
- ## Development
- ```bash
- npm install
- npm test
- npm run docs:build
- ```
- Repository layout:
- - `skills/drawio/`: base skill, CLI, references, themes, schemas, examples, style presets
- - `skills/drawio-academic-skills/`: academic overlay, README, evals, publication references
- - `docs/`: VitePress site
- - `tests/`: repo-level integration tests
- ## Upstream Relationship
- This repository builds on draw.io and the optional **[next-ai-draw-io](https://github.com/DayuanJiang/next-ai-draw-io)** MCP server, but wraps shared behavior in a YAML-first workflow with offline sidecars, design-system references, and route-specific guidance.
- The official `@drawio/mcp` server is intentionally **not** the default integration surface for this repository because its tool model does not match the offline-first edit/replicate workflow.
- ## License
- This repository is licensed under **MIT** (see `LICENSE`).
- The optional upstream next-ai-draw-io MCP server is licensed under **Apache-2.0**:
- - <https://github.com/DayuanJiang/next-ai-draw-io/blob/main/LICENSE>
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.