{
  "markdown": "# Draw.io Skill for Claude & Codex\n\n[![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)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://spdx.org/licenses/MIT.html)\n\n> **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.\n>\n> **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.\n\n[English](./README.md) | [中文文档](./README_CN.md) | [Documentation](https://bahayonghang.github.io/drawio-skills/)\n\nDraw.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.\n\n## Recommended Models\n\n- **GPT Sol Max**\n- **Claude Fable 5**\n- **Claude Opus 5**\n\n## Skill Variants\n\n- `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.\n- `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.\n\nBoundary 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.\n\n## Features\n\n- **YAML-first artifact bundle**: keep `.drawio`, `.spec.yaml`, and `.arch.json` aligned for repeatable local editing.\n- **Desktop-aware export**: use draw.io Desktop for PNG, PDF, JPG, and embedded `.drawio.svg` when available.\n- **Optional live refinement**: configure next-ai MCP only for base-skill browser refinement; academic overlay stays offline.\n- **3 core routes**: `create`, `edit`, and `replicate`.\n- **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).\n- **15 built-in palettes**: academic, engineering, and general color groups compose independently with themes and carry colorblind, grayscale, category-capacity, and source metadata.\n- **Academic overlay policy**: venue/audience preflight, caption/legend checks, formula fidelity, A4/Word/LaTeX expectations, and figure typing.\n- **Academic figure taxonomy**: publication requests classify into `architecture`, `roadmap`, or `workflow` before layout and export.\n- **Cloud and stencil support**: AWS, GCP, Azure, Kubernetes, and network/provider icon workflows through the base references.\n- **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.\n- **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.\n- **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.\n- **Code relationship import**: render Python, JavaScript/TypeScript, Go, or Rust module/class relationships from a local project directory.\n- **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.\n- **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`.\n- **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.\n- **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).\n- **Validation before export**: structure, layout, quality, formula, and replication text-position checks.\n\n## Runtime Model\n\nUse this order unless the request explicitly needs a browser session:\n\n1. **Offline Authoring Path**: generate `.drawio` locally and keep sidecars in sync.\n2. **Desktop-Enhanced Export**: use draw.io Desktop for raster/PDF and embedded SVG exports.\n3. **Live Refinement Backend**: base-skill browser refinement only; the offline bundle remains canonical.\n4. **Direct XML Exception**: tiny XML-only handoff or exact mxGraph control when YAML is not the right tool.\n\nAcademic overlay uses the first two paths only. It does not create, require, or route through `.mcp.json`, MCP, or live backend.\n\n## Install\n\n### Project-level Installation for Diagram Replication (Recommended)\n\nTo 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):\n\n- **Claude (Project Level)**:\n\n  ```bash\n  git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .claude/skills/drawio-scientific-illustrator\n  ```\n\n- **Codex (Project Level)**:\n\n  ```bash\n  git clone -b dev https://github.com/bahayonghang/drawio-scientific-illustrator.git .codex/skills/drawio-scientific-illustrator\n  ```\n\n### Standard Base Skill Installation\n\n```bash\nnpx skills add bahayonghang/drawio-skills\n```\n\nRestart your client after installation so it reloads the skills.\n\n### Manual\n\n1. Clone the repository.\n2. Copy `skills/drawio` into your client's skill directory.\n3. For publication-facing workflows, also copy `skills/drawio-academic-skills` next to `drawio` so the overlay can resolve sibling `../drawio`.\n\nCommon locations:\n\n- **Claude**\n  - macOS: `~/Library/Application Support/Claude/skills/`\n  - Linux: `~/.config/Claude/skills/`\n  - Windows: `%APPDATA%\\Claude\\skills\\`\n- **Codex**\n  - macOS / Linux: `~/.codex/skills/`\n  - Windows: `%USERPROFILE%\\.codex\\skills\\`\n\n## Optional Live Editing Setup\n\nNormal create/edit/export work does **not** require MCP. Configure `@next-ai-drawio/mcp-server` only when you want base-skill browser refinement.\n\nAcademic overlay does not need this setup.\n\n### Claude JSON config\n\nmacOS / Linux:\n\n```json\n{\n  \"mcpServers\": {\n    \"drawio\": {\n      \"command\": \"npx\",\n      \"args\": [\"--yes\", \"@next-ai-drawio/mcp-server@latest\"]\n    }\n  }\n}\n```\n\nWindows:\n\n```json\n{\n  \"mcpServers\": {\n    \"drawio\": {\n      \"type\": \"stdio\",\n      \"command\": \"cmd\",\n      \"args\": [\"/c\", \"npx\", \"--yes\", \"@next-ai-drawio/mcp-server@latest\"]\n    }\n  }\n}\n```\n\n### Codex `config.toml`\n\nmacOS / Linux:\n\n```toml\n[mcp_servers.drawio]\ncommand = \"npx\"\nargs = [\"--yes\", \"@next-ai-drawio/mcp-server@latest\"]\n```\n\nWindows:\n\n```toml\n[mcp_servers.drawio]\ntype = \"stdio\"\ncommand = \"cmd\"\nargs = [\"/c\", \"npx\", \"--yes\", \"@next-ai-drawio/mcp-server@latest\"]\n```\n\n## Quick Start\n\nCreate a new diagram:\n\n```text\n/drawio create a horizontal tech-blue login flow with 6 nodes\n```\n\nCreate a network topology with structured metadata:\n\n```text\n/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.\n```\n\nCreate a publication figure with the overlay:\n\n```text\n/drawio-academic-skills create an IEEE-style workflow figure for a manuscript. Deliver .drawio + .spec.yaml + .arch.json + .svg.\n```\n\nImport an existing `.drawio` file into the offline bundle:\n\n```bash\nnode skills/drawio/scripts/cli.js existing.drawio --input-format drawio --export-spec --write-sidecars\n```\n\nRender and validate a bundle:\n\n```bash\nnode skills/drawio/scripts/cli.js input.yaml output.drawio --validate --write-sidecars\nnode skills/drawio/scripts/cli.js input.yaml output.svg --validate --write-sidecars\n```\n\nUse mixed provider, Lobe, brand, and Lucide icons:\n\n```yaml\nnodes:\n  - id: lambda\n    label: AWS Lambda\n    icon: aws.lambda\n  - id: openai\n    label: OpenAI document understanding\n    icon: lobe.openai\n  - id: claude\n    label: Claude reasoning\n    icon: ai.anthropic\n  - id: redis\n    label: Redis cache\n    icon: brand.redis\n  - id: cache\n    label: Cache fallback\n    icon: lucide.database-zap\n  - id: ops\n    label: Server operations\n    icon: lucide.server-cog\n```\n\nCommon `lobe.*` / `ai.*` icons such as OpenAI, Claude, and Gemini are embedded\nas normalized SVGs for reliable offline rendering. Unsupported Lobe names fail\nshape validation instead of creating remote image links. `brand.*` is for the\nbundled non-AI brand fallbacks; the curated `lucide.*` set is embedded as data\nURI SVGs and should not be treated as official brand logos. Supported examples\ninclude `lucide.alarm-clock`, `lucide.server-cog`, and `lucide.workflow`.\nLobe and Lucide attribution files ship under `skills/drawio/assets/licenses/`.\n\nAcademic overlay still uses the sibling base CLI:\n\n```bash\nnode skills/drawio/scripts/cli.js skills/drawio-academic-skills/references/examples/system-architecture-paper.yaml academic-system.svg --validate --write-sidecars --strict-warnings\n```\n\nUse draw.io Desktop when you need raster or PDF export:\n\n```bash\nnode skills/drawio/scripts/cli.js input.yaml output.pdf --validate --use-desktop\nnode skills/drawio/scripts/cli.js input.yaml output.png --validate --use-desktop\n```\n\nGenerate a diagrams.net URL fallback from a `.drawio` file:\n\n```bash\nnode skills/drawio/scripts/runtime/diagrams-net-url.js output.drawio\n```\n\n## Canonical Artifact Bundle\n\nWhen the diagram will continue evolving, keep these files together:\n\n- `<name>.drawio`\n- `<name>.spec.yaml`\n- `<name>.arch.json`\n\nAcademic overlay adds standalone SVG as part of the default publication bundle:\n\n- `<name>.svg`\n\nPNG/PDF/JPG are Desktop-enhanced optional outputs and should be reported as unavailable if draw.io Desktop is missing.\n\n## Network Topology Authoring\n\nThe current network-topology workflow supports:\n\n- semantic node types such as `router`, `switch`, `firewall`, `server`, `load_balancer`, `subnet`, `internet`, and `ap`\n- link metadata fields such as `srcInterface`, `dstInterface`, `ip`, `vlan`, `bandwidth`, and `linkType`\n- layout intents `hierarchical`, `star`, and `mesh`\n- provider-aware icon mapping through explicit `icon` fields or `network.vendor` + `network.device`\n\nRepresentative specs ship in `skills/drawio/references/examples/`.\n\nRender one directly:\n\n```bash\nnode skills/drawio/scripts/cli.js skills/drawio/references/examples/vendor-device-mapping.yaml output.drawio --validate --write-sidecars\n```\n\n## Offline Importers and Adapters\n\nBeyond `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.\n\n| Route              | Input                                                                       | `--input-format` / command                                                                  |\n| ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `config-import`    | Terraform, Kubernetes, Compose, SQL DDL, OpenAPI, GitHub Actions, GitLab CI | `terraform` / `kubernetes` / `compose` / `sql` / `openapi` / `github-actions` / `gitlab-ci` |\n| `code-import`      | local Python, JS/TS, Go, Rust project directory                             | `python-imports` / `python-classes` / `js-imports` / `go-imports` / `rust-imports`          |\n| `live-drift`       | saved Terraform state, Docker inspect, Kubernetes live JSON                 | snapshot adapters + `compareGraphProjections`                                               |\n| `multi-page`       | canonical bundle v1                                                         | `--input-format drawio --all-pages --export-spec`                                           |\n| `raster-replicate` | trusted structured visual extraction                                        | `raster-extraction`                                                                         |\n| `postprocess`      | canonical YAML / `.drawio`                                                  | `postprocess mermaid\\|explain\\|relabel\\|restyle\\|heatmap\\|html`                             |\n\nThe 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`.\n\n## Documentation\n\n- [Getting Started](https://bahayonghang.github.io/drawio-skills/guide/getting-started)\n- [Workflows](https://bahayonghang.github.io/drawio-skills/guide/workflows)\n- [Config and IaC Importers](https://bahayonghang.github.io/drawio-skills/guide/config-importers)\n- [Code Relationship Importers](https://bahayonghang.github.io/drawio-skills/guide/code-importers)\n- [Live Snapshots and Drift](https://bahayonghang.github.io/drawio-skills/guide/live-drift)\n- [Multi-page Bundles](https://bahayonghang.github.io/drawio-skills/guide/multi-page)\n- [Postprocess Suite](https://bahayonghang.github.io/drawio-skills/guide/postprocess)\n- [Upstream Capability Map](https://bahayonghang.github.io/drawio-skills/api/upstream-capability-map)\n- [CLI Tool](https://bahayonghang.github.io/drawio-skills/guide/cli)\n- [Optional MCP Tools](https://bahayonghang.github.io/drawio-skills/api/mcp-tools)\n- [Examples](https://bahayonghang.github.io/drawio-skills/examples/)\n\n## Development\n\n```bash\nnpm install\nnpm test\nnpm run docs:build\n```\n\nRepository layout:\n\n- `skills/drawio/`: base skill, CLI, references, themes, schemas, examples, style presets\n- `skills/drawio-academic-skills/`: academic overlay, README, evals, publication references\n- `docs/`: VitePress site\n- `tests/`: repo-level integration tests\n\n## Upstream Relationship\n\nThis 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.\n\nThe 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.\n\n## License\n\nThis repository is licensed under **MIT** (see `LICENSE`).\n\nThe optional upstream next-ai-draw-io MCP server is licensed under **Apache-2.0**:\n\n- <https://github.com/DayuanJiang/next-ai-draw-io/blob/main/LICENSE>\n",
  "bytes": 16539,
  "sha": "123aad5ef65ad6f17bbf88faee4081ca86057cb381d629e5204f68033cdc6de9",
  "repo_slug": "bahayonghang/drawio-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/skl_bahayonghang_drawio_skills_drawio_b4fb6fb4/readme"
}