Skip to content

Agent skill that turns natural language, code, Terraform/K8s, SQL, OpenAPI, AsyncAPI, Protobuf and GraphQL sources into editable, tested draw.io architecture diagrams: incremental sync, multi-view projection, drift diff, CI architecture tests, whiteboard derasterize, interactive HTML/PPTX/Mermaid exports.

docs: split README into INSTALL_CLI / INSTALL_SKILL / USAGE files

Agents365-ai176ff11634b2
diff --git a/INSTALL_CLI.md b/INSTALL_CLI.md
new file mode 100644
index 0000000..1705ad8
--- /dev/null
+++ b/INSTALL_CLI.md
@@ -0,0 +1,40 @@
+# Prerequisites — draw.io desktop
+
+[中文](INSTALL_CLI_CN.md)
+
+The draw.io desktop app must be installed for diagram export:
+
+## macOS
+
+```bash
+# Recommended — Homebrew
+brew install --cask drawio
+
+# Verify
+drawio --version
+```
+
+## Windows
+
+Download and install from: https://github.com/jgraph/drawio-desktop/releases
+
+```powershell
+# Verify
+"C:\Program Files\draw.io\draw.io.exe" --version
+```
+
+## Linux
+
+Download `.deb` or `.rpm` from: https://github.com/jgraph/drawio-desktop/releases
+
+```bash
+# Headless export (required on Linux servers without display)
+sudo apt install xvfb # Debian/Ubuntu
+xvfb-run -a drawio --version
+```
+
+| Platform | Extra step |
+|----------|------------|
+| **macOS** | No extra steps after Homebrew install |
+| **Windows** | Use full path if not in PATH |
+| **Linux** | Wrap commands with `xvfb-run -a` for headless export |
diff --git a/INSTALL_CLI_CN.md b/INSTALL_CLI_CN.md
new file mode 100644
index 0000000..38315d0
--- /dev/null
+++ b/INSTALL_CLI_CN.md
@@ -0,0 +1,40 @@
+# 前置依赖 —— draw.io 桌面版
+
+[English](INSTALL_CLI.md)
+
+需要安装 draw.io 桌面版用于图表导出:
+
+## macOS
+
+```bash
+# 推荐方式 — Homebrew
+brew install --cask drawio
+
+# 验证安装
+drawio --version
+```
+
+## Windows
+
+从以下地址下载安装包:https://github.com/jgraph/drawio-desktop/releases
+
+```powershell
+# 验证安装
+"C:\Program Files\draw.io\draw.io.exe" --version
+```
+
+## Linux
+
+从以下地址下载 `.deb` 或 `.rpm` 包:https://github.com/jgraph/drawio-desktop/releases
+
+```bash
+# 无头导出(Linux 服务器无显示器时必须)
+sudo apt install xvfb # Debian/Ubuntu
+xvfb-run -a drawio --version
+```
+
+| 平台 | 额外步骤 |
+|------|----------|
+| **macOS** | Homebrew 安装后无需额外操作 |
+| **Windows** | 如不在 PATH 中,使用完整路径 |
+| **Linux** | 无头导出时命令前加 `xvfb-run -a` |
diff --git a/INSTALL_SKILL.md b/INSTALL_SKILL.md
new file mode 100644
index 0000000..0b2fcac
--- /dev/null
+++ b/INSTALL_SKILL.md
@@ -0,0 +1,43 @@
+# Skill Installation
+
+[中文](INSTALL_SKILL_CN.md)
+
+```bash
+# Any agent (Claude Code, Cursor, Copilot, etc.)
+npx skills add Agents365-ai/365-skills -g
+
+# Claude Code only
+> /plugin marketplace add Agents365-ai/365-skills
+> /plugin install drawio
+```
+
+Manual install — clone into your agent's skills directory:
+
+```bash
+git clone https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill
+```
+
+Common paths: `~/.claude/skills/` (Claude Code), `~/.config/opencode/skills/` (Opencode), `~/.openclaw/skills/` (OpenClaw), `~/.agents/skills/` (Codex). Also indexed on [SkillsMP](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md) and [ClawHub](https://clawhub.ai/agents365-ai/drawio-pro-skill).
+
+## Updates
+
+The skill auto-checks for updates once per 24 hours on first use in a conversation. When a new version is available, the agent prints a one-line notice in the reply. To apply:
+
+```bash
+cd <your-install-path>/drawio-skill && git pull
+```
+
+The check is read-only, self-throttled, and silent when up to date, offline, or not a git install — it won't block or slow the workflow.
+
+Plugin-marketplace installs update automatically via the 365-skills umbrella. Package-manager installs handle updates themselves:
+
+```bash
+# Claude Code plugin
+/plugin update drawio
+
+# OpenClaw
+clawhub update drawio-pro-skill
+
+# SkillsMP
+skills update drawio-skill
+```
diff --git a/INSTALL_SKILL_CN.md b/INSTALL_SKILL_CN.md
new file mode 100644
index 0000000..f381cb2
--- /dev/null
+++ b/INSTALL_SKILL_CN.md
@@ -0,0 +1,43 @@
+# 技能安装
+
+[English](INSTALL_SKILL.md)
+
+```bash
+# 任意 Agent(Claude Code、Cursor、Copilot 等)
+npx skills add Agents365-ai/365-skills -g
+
+# 仅 Claude Code
+> /plugin marketplace add Agents365-ai/365-skills
+> /plugin install drawio
+```
+
+手动安装 —— 克隆到你的 Agent skills 目录:
+
+```bash
+git clone https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill
+```
+
+常用路径:`~/.claude/skills/`(Claude Code)、`~/.config/opencode/skills/`(Opencode)、`~/.openclaw/skills/`(OpenClaw)、`~/.agents/skills/`(Codex)。同时已索引于 [SkillsMP](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md) 和 [ClawHub](https://clawhub.ai/agents365-ai/drawio-pro-skill)。
+
+## 更新
+
+Skill 会在每次对话首次使用时自动检查更新(24 小时节流)。有新版本时,Agent 会在回复中打印一行提示。应用更新:
+
+```bash
+cd <你的安装路径>/drawio-skill && git pull
+```
+
+检查为只读、自节流,在已是最新版、离线、或非 git 安装时静默退出,不会阻塞或拖慢工作流。
+
+通过插件市场安装的用户通过 365-skills umbrella 自动更新。通过包管理器安装的用户直接用对应命令更新:
+
+```bash
+# Claude Code 插件
+/plugin update drawio
+
+# OpenClaw
+clawhub update drawio-pro-skill
+
+# SkillsMP
+skills update drawio-skill
+```
diff --git a/README.md b/README.md
index 828a264..120976d 100644
--- a/README.md
+++ b/README.md
@@ -85,130 +85,16 @@
<img src="assets/workflow.png" width="420" alt="Workflow">
</p>
-## Prerequisites
-
-The draw.io desktop app must be installed for diagram export:
-
-### macOS
-
-```bash
-# Recommended — Homebrew
-brew install --cask drawio
-
-# Verify
-drawio --version
-```
-
-### Windows
-
-Download and install from: https://github.com/jgraph/drawio-desktop/releases
-
-```powershell
-# Verify
-"C:\Program Files\draw.io\draw.io.exe" --version
-```
-
-### Linux
-
-Download `.deb` or `.rpm` from: https://github.com/jgraph/drawio-desktop/releases
-
-```bash
-# Headless export (required on Linux servers without display)
-sudo apt install xvfb # Debian/Ubuntu
-xvfb-run -a drawio --version
-```
-
-| Platform | Extra step |
-|----------|------------|
-| **macOS** | No extra steps after Homebrew install |
-| **Windows** | Use full path if not in PATH |
-| **Linux** | Wrap commands with `xvfb-run -a` for headless export |
-
## Installation
-```bash
-# Any agent (Claude Code, Cursor, Copilot, etc.)
-npx skills add Agents365-ai/365-skills -g
-
-# Claude Code only
-> /plugin marketplace add Agents365-ai/365-skills
-> /plugin install drawio
-```
-
-Manual install — clone into your agent's skills directory:
-
-```bash
-git clone https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill
-```
-
-Common paths: `~/.claude/skills/` (Claude Code), `~/.config/opencode/skills/` (Opencode), `~/.openclaw/skills/` (OpenClaw), `~/.agents/skills/` (Codex). Also indexed on [SkillsMP](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md) and [ClawHub](https://clawhub.ai/agents365-ai/drawio-pro-skill).
-
-## Updates
-
-The skill auto-checks for updates once per 24 hours on first use in a conversation. When a new version is available, the agent prints a one-line notice in the reply. To apply:
-
-```bash
-cd <your-install-path>/drawio-skill && git pull
-```
+Two steps — install the draw.io CLI first, then drop the skill into your host:
-The check is read-only, self-throttled, and silent when up to date, offline, or not a git install — it won't block or slow the workflow.
-
-Plugin-marketplace installs update automatically via the 365-skills umbrella. Package-manager installs handle updates themselves:
-
-```bash
-# Claude Code plugin
-/plugin update drawio
-
-# OpenClaw
-clawhub update drawio-pro-skill
-
-# SkillsMP
-skills update drawio-skill
-```
+1. **[Install draw.io desktop](INSTALL_CLI.md)** — per-platform recipes for macOS / Windows / Linux.
+2. **[Install the skill](INSTALL_SKILL.md)** — plugin marketplace (recommended), manual clone, and update commands.
## Usage
-Just describe what you want:
-
-```
-Create a microservices e-commerce architecture with API Gateway, auth/user/order/product/payment services,
-Kafka message queue, notification service, and separate databases for each service
-```
-
-The agent will generate the `.drawio` XML file and export it to PNG automatically.
-
-## Example
-
-**Prompt:**
-> Create a microservices e-commerce architecture with Mobile/Web/Admin clients, API Gateway,
-> Auth/User/Order/Product/Payment services, Kafka message queue, Notification service,
-> and User DB / Order DB / Product DB / Redis Cache / Stripe API
-
-**Output:**
-
-![Microservices Architecture](assets/microservices-example.png)
-
-## Topology demos
-
-The skill handles various diagram topologies with clean edge routing — no lines crossing through shapes.
-
-### Star topology (7 nodes)
-
-Central message broker with 6 microservices radiating outward. Edges enter Kafka from different sides, zero crossings.
-
-![Star topology](assets/demo-star.png)
-
-### Layered flow (10 nodes, 4 tiers)
-
-E-commerce architecture with 2 cross-connections: Order→Product (same-tier horizontal) and Auth→Redis (diagonal via routing corridor). All edges route cleanly.
-
-![Layered flow](assets/demo-layered.png)
-
-### Ring / cycle (8 nodes)
-
-CI/CD pipeline with a closed loop and 2 spur branches. Edges flow along the perimeter without crossing the interior.
-
-![Ring cycle](assets/demo-ring.png)
+See [USAGE.md](USAGE.md) for natural-language prompts, a microservices walkthrough, and topology demos (star / layered / ring).
## Files
diff --git a/README_CN.md b/README_CN.md
index 8ca36f1..5fcaf44 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -85,131 +85,16 @@
<img src="assets/workflow-cn.png" width="420" alt="工作流程">
</p>
-## 前置依赖
-
-需要安装 draw.io 桌面版用于图表导出:
-
-### macOS
-
-```bash
-# 推荐方式 — Homebrew
-brew install --cask drawio
-
-# 验证安装
-drawio --version
-```
-
-### Windows
-
-从以下地址下载安装包:https://github.com/jgraph/drawio-desktop/releases
-
-```powershell
-# 验证安装
-"C:\Program Files\draw.io\draw.io.exe" --version
-```
-
-### Linux
-
-从以下地址下载 `.deb` 或 `.rpm` 包:https://github.com/jgraph/drawio-desktop/releases
-
-```bash
-# 无头导出(Linux 服务器无显示器时必须)
-sudo apt install xvfb # Debian/Ubuntu
-xvfb-run -a drawio --version
-```
-
-| 平台 | 额外步骤 |
-|------|----------|
-| **macOS** | Homebrew 安装后无需额外操作 |
-| **Windows** | 如不在 PATH 中,使用完整路径 |
-| **Linux** | 无头导出时命令前加 `xvfb-run -a` |
-
## 安装
-```bash
-# 任意 Agent(Claude Code、Cursor、Copilot 等)
-npx skills add Agents365-ai/365-skills -g
-
-# 仅 Claude Code
-> /plugin marketplace add Agents365-ai/365-skills
-> /plugin install drawio
-```
-
-手动安装 —— 克隆到你的 Agent skills 目录:
-
-```bash
-git clone https://github.com/Agents365-ai/drawio-skill.git ~/.claude/skills/drawio-skill
-```
-
-常用路径:`~/.claude/skills/`(Claude Code)、`~/.config/opencode/skills/`(Opencode)、`~/.openclaw/skills/`(OpenClaw)、`~/.agents/skills/`(Codex)。同时已索引于 [SkillsMP](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md) 和 [ClawHub](https://clawhub.ai/agents365-ai/drawio-pro-skill)。
-
-## 更新
-
-Skill 会在每次对话首次使用时自动检查更新(24 小时节流)。有新版本时,Agent 会在回复中打印一行提示。应用更新:
-
-```bash
-cd <你的安装路径>/drawio-skill && git pull
-```
+两步 —— 先装 draw.io CLI,再把技能加载到 host:
-检查为只读、自节流,在已是最新版、离线、或非 git 安装时静默退出,不会阻塞或拖慢工作流。
-
-通过插件市场安装的用户通过 365-skills umbrella 自动更新。通过包管理器安装的用户直接用对应命令更新:
-
-```bash
-# Claude Code 插件
-/plugin update drawio
-
-# OpenClaw
-clawhub update drawio-pro-skill
-
-# SkillsMP
-skills update drawio-skill
-```
+1. **[安装 draw.io 桌面版](INSTALL_CLI_CN.md)** —— macOS / Windows / Linux 各平台配方。
+2. **[安装技能](INSTALL_SKILL_CN.md)** —— 插件市场(推荐)、手动克隆、以及更新命令。
## 使用方式
-直接描述你想要的图表:
-
-```
-画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway,
-Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,
-以及各自独立的数据库
-```
-
-智能体会自动生成 `.drawio` 文件并导出为 PNG。
-
-## 示例
-
-**提示词:**
-> 画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway(含认证+限流+路由),
-> Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,
-> User DB / Order DB / Product DB / Redis Cache / Stripe API
-
-**输出效果:**
-
-![微服务架构图](assets/microservices-example.png)
-
-## 拓扑示例
-
-本 skill 支持多种图表拓扑,线条路由清晰 —— 不会穿越无关的形状。
-
-### 星形拓扑(7 个节点)
-
-中央消息代理 + 6 个微服务辐射排列。连线从不同方向进入 Kafka,零交叉。
-
-![星形拓扑](assets/demo-star-cn.png)
-
-### 分层流程(10 个节点,4 层)
-
-电商架构,含 2 条交叉连线:订单→商品(同层水平)和 认证→Redis(对角线,经路由走廊绕行)。所有线条路由清晰。
-
-![分层流程](assets/demo-layered-cn.png)
-
-### 环形 / 循环(8 个节点)
-
-CI/CD 流水线,包含闭合回路和 2 个分支。线条沿矩形外围流动,不穿越内部区域。
-
-![环形循环](assets/demo-ring-cn.png)
+参见 [USAGE_CN.md](USAGE_CN.md) —— 包含自然语言提示词、微服务示例,以及多种拓扑演示(星形 / 分层 / 环形)。
## 文件说明
diff --git a/USAGE.md b/USAGE.md
new file mode 100644
index 0000000..8f3197f
--- /dev/null
+++ b/USAGE.md
@@ -0,0 +1,45 @@
+# Usage
+
+[中文](USAGE_CN.md)
+
+Just describe what you want:
+
+```
+Create a microservices e-commerce architecture with API Gateway, auth/user/order/product/payment services,
+Kafka message queue, notification service, and separate databases for each service
+```
+
+The agent will generate the `.drawio` XML file and export it to PNG automatically.
+
+## Example
+
+**Prompt:**
+> Create a microservices e-commerce architecture with Mobile/Web/Admin clients, API Gateway,
+> Auth/User/Order/Product/Payment services, Kafka message queue, Notification service,
+> and User DB / Order DB / Product DB / Redis Cache / Stripe API
+
+**Output:**
+
+![Microservices Architecture](assets/microservices-example.png)
+
+## Topology demos
+
+The skill handles various diagram topologies with clean edge routing — no lines crossing through shapes.
+
+### Star topology (7 nodes)
+
+Central message broker with 6 microservices radiating outward. Edges enter Kafka from different sides, zero crossings.
+
+![Star topology](assets/demo-star.png)
+
+### Layered flow (10 nodes, 4 tiers)
+
+E-commerce architecture with 2 cross-connections: Order→Product (same-tier horizontal) and Auth→Redis (diagonal via routing corridor). All edges route cleanly.
+
+![Layered flow](assets/demo-layered.png)
+
+### Ring / cycle (8 nodes)
+
+CI/CD pipeline with a closed loop and 2 spur branches. Edges flow along the perimeter without crossing the interior.
+
+![Ring cycle](assets/demo-ring.png)
diff --git a/USAGE_CN.md b/USAGE_CN.md
new file mode 100644
index 0000000..e06a67b
--- /dev/null
+++ b/USAGE_CN.md
@@ -0,0 +1,46 @@
+# 使用方式
+
+[English](USAGE.md)
+
+直接描述你想要的图表:
+
+```
+画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway,
+Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,
+以及各自独立的数据库
+```
+
+智能体会自动生成 `.drawio` 文件并导出为 PNG。
+
+## 示例
+
+**提示词:**
+> 画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway(含认证+限流+路由),
+> Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,
+> User DB / Order DB / Product DB / Redis Cache / Stripe API
+
+**输出效果:**
+
+![微服务架构图](assets/microservices-example.png)
+
+## 拓扑示例
+
+本 skill 支持多种图表拓扑,线条路由清晰 —— 不会穿越无关的形状。
+
+### 星形拓扑(7 个节点)
+
+中央消息代理 + 6 个微服务辐射排列。连线从不同方向进入 Kafka,零交叉。
+
+![星形拓扑](assets/demo-star-cn.png)
+
+### 分层流程(10 个节点,4 层)
+
+电商架构,含 2 条交叉连线:订单→商品(同层水平)和 认证→Redis(对角线,经路由走廊绕行)。所有线条路由清晰。
+
+![分层流程](assets/demo-layered-cn.png)
+
+### 环形 / 循环(8 个节点)
+
+CI/CD 流水线,包含闭合回路和 2 个分支。线条沿矩形外围流动,不穿越内部区域。
+
+![环形拓扑](assets/demo-ring-cn.png)