Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bahayonghang-drawio-skills/badge.svg)](/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

i

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)

  1. # Draw.io Skill for Claude & Codex
  2. [![Deploy Docs](https://github.com/bahayonghang/drawio-skills/actions/workflows/deploy-docs.yml/badge.svg)](https://github.com/bahayonghang/drawio-skills/actions/workflows/deploy-docs.yml)
  3. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://spdx.org/licenses/MIT.html)
  4. > **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.
  5. >
  6. > **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.
  7. [English](./README.md) | [中文文档](./README_CN.md) | [Documentation](https://bahayonghang.github.io/drawio-skills/)
  8. 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.
  9. ## Recommended Models
  10. - **GPT Sol Max**
  11. - **Claude Fable 5**
  12. - **Claude Opus 5**
  13. ## Skill Variants
  14. - `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.
  15. - `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.
  16. 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.
  17. ## Features
  18. - **YAML-first artifact bundle**: keep `.drawio`, `.spec.yaml`, and `.arch.json` aligned for repeatable local editing.
  19. - **Desktop-aware export**: use draw.io Desktop for PNG, PDF, JPG, and embedded `.drawio.svg` when available.
  20. - **Optional live refinement**: configure next-ai MCP only for base-skill browser refinement; academic overlay stays offline.
  21. - **3 core routes**: `create`, `edit`, and `replicate`.
  22. - **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).
  23. - **15 built-in palettes**: academic, engineering, and general color groups compose independently with themes and carry colorblind, grayscale, category-capacity, and source metadata.
  24. - **Academic overlay policy**: venue/audience preflight, caption/legend checks, formula fidelity, A4/Word/LaTeX expectations, and figure typing.
  25. - **Academic figure taxonomy**: publication requests classify into `architecture`, `roadmap`, or `workflow` before layout and export.
  26. - **Cloud and stencil support**: AWS, GCP, Azure, Kubernetes, and network/provider icon workflows through the base references.
  27. - **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.
  28. - **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.
  29. - **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.
  30. - **Code relationship import**: render Python, JavaScript/TypeScript, Go, or Rust module/class relationships from a local project directory.
  31. - **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.
  32. - **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`.
  33. - **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.
  34. - **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).
  35. - **Validation before export**: structure, layout, quality, formula, and replication text-position checks.
  36. ## Runtime Model
  37. Use this order unless the request explicitly needs a browser session:
  38. 1. **Offline Authoring Path**: generate `.drawio` locally and keep sidecars in sync.
  39. 2. **Desktop-Enhanced Export**: use draw.io Desktop for raster/PDF and embedded SVG exports.
  40. 3. **Live Refinement Backend**: base-skill browser refinement only; the offline bundle remains canonical.
  41. 4. **Direct XML Exception**: tiny XML-only handoff or exact mxGraph control when YAML is not the right tool.
  42. Academic overlay uses the first two paths only. It does not create, require, or route through `.mcp.json`, MCP, or live backend.
  43. ## Install
  44. ### Project-level Installation for Diagram Replication (Recommended)
  45. 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):
  46. - **Claude (Project Level)**:
  47. ```bash
  48. git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .claude/skills/drawio-scientific-illustrator
  49. ```
  50. - **Codex (Project Level)**:
  51. ```bash
  52. git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .codex/skills/drawio-scientific-illustrator
  53. ```
  54. ### Standard Base Skill Installation
  55. ```bash
  56. npx skills add bahayonghang/drawio-skills
  57. ```
  58. Restart your client after installation so it reloads the skills.
  59. ### Manual
  60. 1. Clone the repository.
  61. 2. Copy `skills/drawio` into your client's skill directory.
  62. 3. For publication-facing workflows, also copy `skills/drawio-academic-skills` next to `drawio` so the overlay can resolve sibling `../drawio`.
  63. Common locations:
  64. - **Claude**
  65. - macOS: `~/Library/Application Support/Claude/skills/`
  66. - Linux: `~/.config/Claude/skills/`
  67. - Windows: `%APPDATA%\Claude\skills\`
  68. - **Codex**
  69. - macOS / Linux: `~/.codex/skills/`
  70. - Windows: `%USERPROFILE%\.codex\skills\`
  71. ## Optional Live Editing Setup
  72. Normal create/edit/export work does **not** require MCP. Configure `@next-ai-drawio/mcp-server` only when you want base-skill browser refinement.
  73. Academic overlay does not need this setup.
  74. ### Claude JSON config
  75. macOS / Linux:
  76. ```json
  77. {
  78. "mcpServers": {
  79. "drawio": {
  80. "command": "npx",
  81. "args": ["--yes", "@next-ai-drawio/mcp-server@latest"]
  82. }
  83. }
  84. }
  85. ```
  86. Windows:
  87. ```json
  88. {
  89. "mcpServers": {
  90. "drawio": {
  91. "type": "stdio",
  92. "command": "cmd",
  93. "args": ["/c", "npx", "--yes", "@next-ai-drawio/mcp-server@latest"]
  94. }
  95. }
  96. }
  97. ```
  98. ### Codex `config.toml`
  99. macOS / Linux:
  100. ```toml
  101. [mcp_servers.drawio]
  102. command = "npx"
  103. args = ["--yes", "@next-ai-drawio/mcp-server@latest"]
  104. ```
  105. Windows:
  106. ```toml
  107. [mcp_servers.drawio]
  108. type = "stdio"
  109. command = "cmd"
  110. args = ["/c", "npx", "--yes", "@next-ai-drawio/mcp-server@latest"]
  111. ```
  112. ## Quick Start
  113. Create a new diagram:
  114. ```text
  115. /drawio create a horizontal tech-blue login flow with 6 nodes
  116. ```
  117. Create a network topology with structured metadata:
  118. ```text
  119. /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.
  120. ```
  121. Create a publication figure with the overlay:
  122. ```text
  123. /drawio-academic-skills create an IEEE-style workflow figure for a manuscript. Deliver .drawio + .spec.yaml + .arch.json + .svg.
  124. ```
  125. Import an existing `.drawio` file into the offline bundle:
  126. ```bash
  127. node skills/drawio/scripts/cli.js existing.drawio --input-format drawio --export-spec --write-sidecars
  128. ```
  129. Render and validate a bundle:
  130. ```bash
  131. node skills/drawio/scripts/cli.js input.yaml output.drawio --validate --write-sidecars
  132. node skills/drawio/scripts/cli.js input.yaml output.svg --validate --write-sidecars
  133. ```
  134. Use mixed provider, Lobe, brand, and Lucide icons:
  135. ```yaml
  136. nodes:
  137. - id: lambda
  138. label: AWS Lambda
  139. icon: aws.lambda
  140. - id: openai
  141. label: OpenAI document understanding
  142. icon: lobe.openai
  143. - id: claude
  144. label: Claude reasoning
  145. icon: ai.anthropic
  146. - id: redis
  147. label: Redis cache
  148. icon: brand.redis
  149. - id: cache
  150. label: Cache fallback
  151. icon: lucide.database-zap
  152. - id: ops
  153. label: Server operations
  154. icon: lucide.server-cog
  155. ```
  156. Common `lobe.*` / `ai.*` icons such as OpenAI, Claude, and Gemini are embedded
  157. as normalized SVGs for reliable offline rendering. Unsupported Lobe names fail
  158. shape validation instead of creating remote image links. `brand.*` is for the
  159. bundled non-AI brand fallbacks; the curated `lucide.*` set is embedded as data
  160. URI SVGs and should not be treated as official brand logos. Supported examples
  161. include `lucide.alarm-clock`, `lucide.server-cog`, and `lucide.workflow`.
  162. Lobe and Lucide attribution files ship under `skills/drawio/assets/licenses/`.
  163. Academic overlay still uses the sibling base CLI:
  164. ```bash
  165. node skills/drawio/scripts/cli.js skills/drawio-academic-skills/references/examples/system-architecture-paper.yaml academic-system.svg --validate --write-sidecars --strict-warnings
  166. ```
  167. Use draw.io Desktop when you need raster or PDF export:
  168. ```bash
  169. node skills/drawio/scripts/cli.js input.yaml output.pdf --validate --use-desktop
  170. node skills/drawio/scripts/cli.js input.yaml output.png --validate --use-desktop
  171. ```
  172. Generate a diagrams.net URL fallback from a `.drawio` file:
  173. ```bash
  174. node skills/drawio/scripts/runtime/diagrams-net-url.js output.drawio
  175. ```
  176. ## Canonical Artifact Bundle
  177. When the diagram will continue evolving, keep these files together:
  178. - `<name>.drawio`
  179. - `<name>.spec.yaml`
  180. - `<name>.arch.json`
  181. Academic overlay adds standalone SVG as part of the default publication bundle:
  182. - `<name>.svg`
  183. PNG/PDF/JPG are Desktop-enhanced optional outputs and should be reported as unavailable if draw.io Desktop is missing.
  184. ## Network Topology Authoring
  185. The current network-topology workflow supports:
  186. - semantic node types such as `router`, `switch`, `firewall`, `server`, `load_balancer`, `subnet`, `internet`, and `ap`
  187. - link metadata fields such as `srcInterface`, `dstInterface`, `ip`, `vlan`, `bandwidth`, and `linkType`
  188. - layout intents `hierarchical`, `star`, and `mesh`
  189. - provider-aware icon mapping through explicit `icon` fields or `network.vendor` + `network.device`
  190. Representative specs ship in `skills/drawio/references/examples/`.
  191. Render one directly:
  192. ```bash
  193. node skills/drawio/scripts/cli.js skills/drawio/references/examples/vendor-device-mapping.yaml output.drawio --validate --write-sidecars
  194. ```
  195. ## Offline Importers and Adapters
  196. 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.
  197. | Route | Input | `--input-format` / command |
  198. | ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
  199. | `config-import` | Terraform, Kubernetes, Compose, SQL DDL, OpenAPI, GitHub Actions, GitLab CI | `terraform` / `kubernetes` / `compose` / `sql` / `openapi` / `github-actions` / `gitlab-ci` |
  200. | `code-import` | local Python, JS/TS, Go, Rust project directory | `python-imports` / `python-classes` / `js-imports` / `go-imports` / `rust-imports` |
  201. | `live-drift` | saved Terraform state, Docker inspect, Kubernetes live JSON | snapshot adapters + `compareGraphProjections` |
  202. | `multi-page` | canonical bundle v1 | `--input-format drawio --all-pages --export-spec` |
  203. | `raster-replicate` | trusted structured visual extraction | `raster-extraction` |
  204. | `postprocess` | canonical YAML / `.drawio` | `postprocess mermaid\|explain\|relabel\|restyle\|heatmap\|html` |
  205. 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`.
  206. ## Documentation
  207. - [Getting Started](https://bahayonghang.github.io/drawio-skills/guide/getting-started)
  208. - [Workflows](https://bahayonghang.github.io/drawio-skills/guide/workflows)
  209. - [Config and IaC Importers](https://bahayonghang.github.io/drawio-skills/guide/config-importers)
  210. - [Code Relationship Importers](https://bahayonghang.github.io/drawio-skills/guide/code-importers)
  211. - [Live Snapshots and Drift](https://bahayonghang.github.io/drawio-skills/guide/live-drift)
  212. - [Multi-page Bundles](https://bahayonghang.github.io/drawio-skills/guide/multi-page)
  213. - [Postprocess Suite](https://bahayonghang.github.io/drawio-skills/guide/postprocess)
  214. - [Upstream Capability Map](https://bahayonghang.github.io/drawio-skills/api/upstream-capability-map)
  215. - [CLI Tool](https://bahayonghang.github.io/drawio-skills/guide/cli)
  216. - [Optional MCP Tools](https://bahayonghang.github.io/drawio-skills/api/mcp-tools)
  217. - [Examples](https://bahayonghang.github.io/drawio-skills/examples/)
  218. ## Development
  219. ```bash
  220. npm install
  221. npm test
  222. npm run docs:build
  223. ```
  224. Repository layout:
  225. - `skills/drawio/`: base skill, CLI, references, themes, schemas, examples, style presets
  226. - `skills/drawio-academic-skills/`: academic overlay, README, evals, publication references
  227. - `docs/`: VitePress site
  228. - `tests/`: repo-level integration tests
  229. ## Upstream Relationship
  230. 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.
  231. 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.
  232. ## License
  233. This repository is licensed under **MIT** (see `LICENSE`).
  234. The optional upstream next-ai-draw-io MCP server is licensed under **Apache-2.0**:
  235. - <https://github.com/DayuanJiang/next-ai-draw-io/blob/main/LICENSE>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.