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: restructure READMEs to GitHub-conventional layout

Agents365-ai9eb303301a72
diff --git a/README.md b/README.md
index 5120aa7..0158393 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,84 @@
# drawio-skill — From Text to Professional Diagrams
-[中文文档](README_CN.md) | [Online Docs](https://agents365-ai.github.io/drawio-skill/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
+[![GitHub stars](https://img.shields.io/github/stars/Agents365-ai/drawio-skill?style=flat&logo=github)](https://github.com/Agents365-ai/drawio-skill/stargazers)
+[![SkillsMP](https://img.shields.io/badge/SkillsMP-listed-1f6feb)](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md)
+[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin-8a2be2)](https://github.com/Agents365-ai/365-skills)
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-compatible-2ea44f)](https://agentskills.io)
+
+**English** · [中文](README_CN.md) · [📖 Online Docs](https://agents365-ai.github.io/drawio-skill/)
+
+A skill that turns natural-language descriptions into `.drawio` XML and exports them to PNG / SVG / PDF / JPG via the native draw.io desktop CLI. Works with **Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes**, and any agent compatible with the [Agent Skills](https://agentskills.io) format.
<p align="center">
<img src="assets/workflow.png" width="900" alt="Workflow">
</p>
-A skill that turns natural-language descriptions into `.drawio` XML and exports them to PNG / SVG / PDF / JPG via the native draw.io desktop CLI — with 6 diagram presets (ERD, UML Class, Sequence, Architecture, ML/DL, Flowchart), self-check + auto-fix (2 rounds), an iterative feedback loop (5 rounds), and style presets you can capture from a sample file or image.
+## ✨ Highlights
-Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes, and any agent that supports the [Agent Skills](https://agentskills.io) format.
+- **6 diagram type presets** — ERD, UML Class, Sequence, Architecture, ML/Deep Learning, Flowchart
+- **Self-check + auto-fix** — reads its own PNG output and auto-fixes 6 issue types (up to 2 rounds)
+- **Iterative feedback loop** — 5-round targeted refinement until you're satisfied
+- **Style presets** — capture your visual style from a `.drawio` file or image, reuse on demand
+- **Grid-aligned layout** — complexity-scaled spacing, routing corridors, hub-center strategy
+- **Multi-agent, zero-config** — pure SKILL.md; no MCP server, no Python, no Node.js
-## Documentation
+## 🖼️ Example
-| Doc | What's inside |
-|---|---|
-| [docs/COMPARISON.md](docs/COMPARISON.md) | Side-by-side tables vs. native agents and other draw.io skills/tools, with key-advantages summary |
-| [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md) | draw.io desktop CLI install recipes for macOS / Windows / Linux |
-| [docs/INSTALL_SKILL.md](docs/INSTALL_SKILL.md) | Plugin marketplace, manual clone, and update commands |
-| [docs/USAGE.md](docs/USAGE.md) | Natural-language prompts, microservices walkthrough, topology demos (star / layered / ring) |
-| [docs/STYLE_PRESETS.md](docs/STYLE_PRESETS.md) | Built-in presets, "learn my style from a file" workflow, manage-presets commands |
-| [skills/drawio-skill/SKILL.md](skills/drawio-skill/SKILL.md) | Workflow guide loaded by the agent |
+> **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.*
-## What it does
+<p align="center">
+ <img src="assets/microservices-example.png" width="800" alt="Microservices Architecture">
+</p>
-| Capability | Description |
-|---|---|
-| `.drawio` XML generation | From natural-language descriptions |
-| Multi-format export | PNG / SVG / PDF / JPG via the native draw.io desktop CLI |
-| 6 diagram type presets | ERD, UML Class, Sequence, Architecture, ML/Deep Learning, Flowchart |
-| Iterative review | Self-check + auto-fix (up to 2 rounds), then a 5-round feedback loop until you approve |
-| Style presets | Capture your visual style from a `.drawio` file or image, save by name, reapply on demand |
-| Auto-trigger | Activates whenever diagrams would help explain complex systems |
+More walkthroughs (star / layered / ring topologies) in [docs/USAGE.md](docs/USAGE.md).
+
+## 🚀 Installation
-## Supported diagram types
+### 1. Install the draw.io desktop CLI
+
+| Platform | Command |
+|----------|---------|
+| **macOS** | `brew install --cask drawio` |
+| **Windows** | [Download installer](https://github.com/jgraph/drawio-desktop/releases) |
+| **Linux** | `.deb`/`.rpm` from [releases](https://github.com/jgraph/drawio-desktop/releases); `sudo apt install xvfb` for headless |
+
+Verify with `drawio --version`. Full recipes in [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md).
+
+### 2. Install the skill
+
+```bash
+# Any agent (Claude Code, Cursor, Copilot, ...)
+npx skills add Agents365-ai/365-skills -g
+```
+
+```text
+# Claude Code plugin marketplace
+> /plugin marketplace add Agents365-ai/365-skills
+> /plugin install drawio
+```
+
+```bash
+# Manual install
+git clone https://github.com/Agents365-ai/drawio-skill.git \
+ ~/.claude/skills/drawio-skill
+```
+
+Also indexed on [SkillsMP](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md) and [ClawHub](https://clawhub.ai/agents365-ai/drawio-pro-skill). Full options + update commands in [docs/INSTALL_SKILL.md](docs/INSTALL_SKILL.md).
+
+## ⚡ Quick Start
+
+After installation, 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 a separate database per service
+```
+
+The skill plans the layout, generates the `.drawio` XML, exports to your chosen format, self-checks the result, and lets you iterate.
+
+## 🧩 Supported Diagram Types
| Category | Examples | Notable features |
|---|---|---|
@@ -43,20 +89,33 @@ Works with Claude Code, Cursor, Copilot, OpenClaw, Codex, Hermes, and any agent
| Data | ER diagrams, data flow diagrams (DFD) | Table containers, PK/FK notation |
| Other | org charts, mind maps, wireframes | — |
-## Quick Start
+## 🆚 Why drawio-skill?
-Two steps — install the draw.io CLI first (see [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md)), then drop the skill into your host (see [docs/INSTALL_SKILL.md](docs/INSTALL_SKILL.md)). After that, just describe what you want:
+Compared with a native agent (no skill):
-```
-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
-```
+| Feature | Native agent | drawio-skill |
+|---|---|---|
+| Self-check after export | ❌ | ✅ reads PNG, auto-fixes 6 issue types |
+| Iterative review loop | ❌ manual re-prompt | ✅ targeted edits, 5-round safety valve |
+| Diagram type presets | ❌ | ✅ 6 presets (ERD, UML, Seq, Arch, ML, Flow) |
+| Grid-aligned layout | ❌ | ✅ 10px snap, routing corridors |
+| Color palette | random / inconsistent | ✅ 7-color semantic system |
+| Style presets | ❌ | ✅ learn from `.drawio` file or image |
-The skill plans the layout, generates the `.drawio` XML, exports to your chosen format, self-checks, and lets you iterate.
+Full comparison with other draw.io skills, MCP servers, and plugins in [docs/COMPARISON.md](docs/COMPARISON.md).
-## Community
+## 📚 Documentation
-Join us for help, Q&A, and updates:
+| Doc | What's inside |
+|---|---|
+| [docs/INSTALL_CLI.md](docs/INSTALL_CLI.md) | draw.io desktop CLI install recipes for macOS / Windows / Linux |
+| [docs/INSTALL_SKILL.md](docs/INSTALL_SKILL.md) | Plugin marketplace, manual clone, update commands |
+| [docs/USAGE.md](docs/USAGE.md) | Natural-language prompts, microservices walkthrough, topology demos |
+| [docs/STYLE_PRESETS.md](docs/STYLE_PRESETS.md) | Built-in presets, "learn my style from a file" workflow, manage commands |
+| [docs/COMPARISON.md](docs/COMPARISON.md) | Side-by-side tables vs. native agents and other draw.io skills/tools |
+| [skills/drawio-skill/SKILL.md](skills/drawio-skill/SKILL.md) | Workflow guide loaded by the agent |
+
+## 💬 Community
- **Discord:** https://discord.gg/79JF5Atuk
- **WeChat:** scan the QR code below
@@ -65,7 +124,7 @@ Join us for help, Q&A, and updates:
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/agents365ai_wechat_1.png" width="200" alt="WeChat Community Group">
</p>
-## Support
+## ❤️ Support
If this skill helps you, consider supporting the author:
@@ -94,13 +153,13 @@ If this skill helps you, consider supporting the author:
</tr>
</table>
-## Author
+## 👤 Author
**Agents365-ai**
-- Bilibili: https://space.bilibili.com/441831884
- GitHub: https://github.com/Agents365-ai
+- Bilibili: https://space.bilibili.com/441831884
-## License
+## 📄 License
-MIT
+[MIT](https://opensource.org/licenses/MIT)
diff --git a/README_CN.md b/README_CN.md
index e8e0575..0abe6b5 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -1,73 +1,131 @@
# drawio-skill —— 从文字到专业图表
-[English](README.md) | [Online Docs](https://agents365-ai.github.io/drawio-skill/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](#license)
+[![GitHub stars](https://img.shields.io/github/stars/Agents365-ai/drawio-skill?style=flat&logo=github)](https://github.com/Agents365-ai/drawio-skill/stargazers)
+[![SkillsMP](https://img.shields.io/badge/SkillsMP-listed-1f6feb)](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md)
+[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin-8a2be2)](https://github.com/Agents365-ai/365-skills)
+[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-兼容-2ea44f)](https://agentskills.io)
+
+[English](README.md) · **中文** · [📖 在线文档](https://agents365-ai.github.io/drawio-skill/)
+
+一个把自然语言描述变成 `.drawio` XML,并通过 draw.io 桌面版原生 CLI 导出 PNG / SVG / PDF / JPG 的技能。支持 **Claude Code、Cursor、Copilot、OpenClaw、Codex、Hermes** 等任何兼容 [Agent Skills](https://agentskills.io) 规范的 agent。
<p align="center">
<img src="assets/workflow-cn.png" width="900" alt="工作流程">
</p>
-一个把自然语言描述变成 `.drawio` XML,并通过 draw.io 桌面版原生 CLI 导出 PNG / SVG / PDF / JPG 的技能 —— 内置 6 种图表预设(ER 图、UML 类图、序列图、架构图、ML/DL、流程图)、自检 + 自动修复(2 轮)、迭代反馈循环(5 轮),以及可以从样例文件或图片学习的样式预设。
+## ✨ 核心亮点
-支持 Claude Code、Cursor、Copilot、OpenClaw、Codex、Hermes 等任何兼容 [Agent Skills](https://agentskills.io) 规范的 agent。
+- **6 种图表类型预设** —— ER 图、UML 类图、序列图、架构图、ML/深度学习、流程图
+- **自检 + 自动修复** —— 读取自己导出的 PNG,自动修复 6 类问题(最多 2 轮)
+- **迭代反馈循环** —— 最多 5 轮定向优化,直到你满意为止
+- **样式预设** —— 用 `.drawio` 文件或图片"教会"Skill 你的风格,命名保存后随时复用
+- **网格对齐布局** —— 按复杂度分级间距、路由走廊、hub 居中策略
+- **多智能体、零配置** —— 纯 SKILL.md,无需 MCP、Python、Node.js
-## 文档导航
+## 🖼️ 示例
-| 文档 | 内容 |
-|---|---|
-| [docs/COMPARISON_CN.md](docs/COMPARISON_CN.md) | 与原生智能体、其他 draw.io skills/工具的对照表与核心优势 |
-| [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md) | macOS / Windows / Linux 各平台的 draw.io 桌面版 CLI 安装配方 |
-| [docs/INSTALL_SKILL_CN.md](docs/INSTALL_SKILL_CN.md) | 插件市场、手动克隆与更新命令 |
-| [docs/USAGE_CN.md](docs/USAGE_CN.md) | 自然语言提示词、微服务示例、多种拓扑演示(星形 / 分层 / 环形) |
-| [docs/STYLE_PRESETS_CN.md](docs/STYLE_PRESETS_CN.md) | 内置预设、"从文件学习样式"流程、完整的预设管理命令 |
-| [skills/drawio-skill/SKILL.md](skills/drawio-skill/SKILL.md) | agent 加载的工作流指南 |
+> **提示词:** *画一个微服务电商架构图,包含 Mobile/Web/Admin 客户端,API Gateway(含认证+限流+路由),Auth/User/Order/Product/Payment 微服务,Kafka 消息队列,Notification 服务,以及 User DB / Order DB / Product DB / Redis Cache / Stripe API。*
+
+<p align="center">
+ <img src="assets/microservices-example.png" width="800" alt="微服务架构图">
+</p>
-## 功能说明
+更多拓扑示例(星形 / 分层 / 环形)见 [docs/USAGE_CN.md](docs/USAGE_CN.md)。
-| 能力 | 说明 |
-|---|---|
-| `.drawio` XML 生成 | 根据自然语言描述生成 |
-| 多格式导出 | PNG / SVG / PDF / JPG,使用 draw.io 桌面版原生 CLI |
-| 6 种图表类型预设 | ERD、UML 类图、序列图、架构图、ML/深度学习、流程图 |
-| 迭代审查 | 自检 + 自动修复(最多 2 轮),再走 5 轮反馈循环直到你满意 |
-| 样式预设 | 用 `.drawio` 文件或图片"教会"Skill 你的风格,命名保存后随时复用 |
-| 自动触发 | 图表有助于解释复杂系统时自动调用 |
+## 🚀 安装
-## 支持的图表类型
+### 1. 安装 draw.io 桌面版 CLI
+
+| 平台 | 命令 |
+|------|------|
+| **macOS** | `brew install --cask drawio` |
+| **Windows** | [下载安装包](https://github.com/jgraph/drawio-desktop/releases) |
+| **Linux** | 从 [releases](https://github.com/jgraph/drawio-desktop/releases) 下载 `.deb`/`.rpm`;无头导出需 `sudo apt install xvfb` |
+
+用 `drawio --version` 验证。完整方案见 [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md)。
+
+### 2. 安装技能
+
+```bash
+# 任意 Agent(Claude Code、Cursor、Copilot 等)
+npx skills add Agents365-ai/365-skills -g
+```
+
+```text
+# Claude Code 插件市场
+> /plugin marketplace add Agents365-ai/365-skills
+> /plugin install drawio
+```
+
+```bash
+# 手动安装
+git clone https://github.com/Agents365-ai/drawio-skill.git \
+ ~/.claude/skills/drawio-skill
+```
+
+同时索引于 [SkillsMP](https://skillsmp.com/skills/agents365-ai-drawio-skill-skill-md) 与 [ClawHub](https://clawhub.ai/agents365-ai/drawio-pro-skill)。完整方案与更新命令见 [docs/INSTALL_SKILL_CN.md](docs/INSTALL_SKILL_CN.md)。
+
+## ⚡ 快速开始
+
+装好之后直接描述你想要的图表:
+
+```
+画一个微服务电商架构图,包含 API Gateway、用户/订单/商品/支付服务、
+Kafka 消息队列、通知服务,以及各自独立的数据库
+```
+
+Skill 会自动规划布局、生成 `.drawio` XML、导出为你选择的格式、自检结果,并支持后续迭代。
+
+## 🧩 支持的图表类型
| 类别 | 示例 | 特色 |
-|---|---|---|
-| 架构图 | 微服务、云(AWS/GCP/Azure)、网络拓扑、部署 | 分层泳道、hub 居中策略 |
+|------|------|------|
+| 架构图 | 微服务、云(AWS/GCP/Azure)、网络拓扑、部署 | 分层泳道、hub 居中策略 |
| ML / 深度学习 | Transformer、CNN、LSTM、GRU | 张量形状标注、层类型配色 |
-| 流程图 | 业务流程、工作流、决策树、状态机 | 语义形状(平行四边形 I/O、菱形判断) |
-| UML | 类图、序列图 | 继承 / 组合 / 聚合箭头;生命线 + 激活框 |
-| 数据图 | ER 图、数据流图(DFD) | 表容器、PK/FK 标记 |
+| 流程图 | 业务流程、工作流、决策树、状态机 | 语义形状(平行四边形 I/O、菱形判断) |
+| UML | 类图、序列图 | 继承 / 组合 / 聚合箭头;生命线 + 激活框 |
+| 数据图 | ER 图、数据流图(DFD) | 表容器、PK/FK 标记 |
| 其他 | 组织架构图、思维导图、线框图 | — |
-## 快速开始
+## 🆚 为什么用 drawio-skill?
-两步 —— 先装 draw.io CLI(见 [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md)),再把技能加载到 host(见 [docs/INSTALL_SKILL_CN.md](docs/INSTALL_SKILL_CN.md))。装好之后直接描述你想要的:
+对比原生智能体(无 skill):
-```
-画一个微服务电商架构图,包含 API Gateway、用户/订单/商品/支付服务、
-Kafka 消息队列、通知服务,以及各自独立的数据库
-```
+| 功能 | 原生智能体 | drawio-skill |
+|------|-----------|--------------|
+| 导出后自检 | ❌ | ✅ 读取 PNG 自动修复 6 类问题 |
+| 迭代审查循环 | ❌ 需手动重新提问 | ✅ 定向编辑,5 轮安全阀 |
+| 图表类型预设 | ❌ | ✅ 6 种(ERD、UML、序列、架构、ML、流程) |
+| 网格对齐布局 | ❌ | ✅ 10px 对齐、路由走廊 |
+| 配色方案 | 随机 / 不一致 | ✅ 7 色语义系统 |
+| 样式预设 | ❌ | ✅ 从 `.drawio` 文件或图片学习 |
+
+与其他 draw.io skills、MCP 服务、插件的完整对比见 [docs/COMPARISON_CN.md](docs/COMPARISON_CN.md)。
-技能会规划布局、生成 `.drawio` XML、导出为你选择的格式、自检,然后让你迭代。
+## 📚 文档导航
-## 社区
+| 文档 | 内容 |
+|------|------|
+| [docs/INSTALL_CLI_CN.md](docs/INSTALL_CLI_CN.md) | macOS / Windows / Linux 各平台的 draw.io 桌面版 CLI 安装配方 |
+| [docs/INSTALL_SKILL_CN.md](docs/INSTALL_SKILL_CN.md) | 插件市场、手动克隆与更新命令 |
+| [docs/USAGE_CN.md](docs/USAGE_CN.md) | 自然语言提示词、微服务示例、多种拓扑演示 |
+| [docs/STYLE_PRESETS_CN.md](docs/STYLE_PRESETS_CN.md) | 内置预设、"从文件学习样式"流程、完整管理命令 |
+| [docs/COMPARISON_CN.md](docs/COMPARISON_CN.md) | 与原生智能体、其他 draw.io skills/工具的对照表 |
+| [skills/drawio-skill/SKILL.md](skills/drawio-skill/SKILL.md) | agent 加载的工作流指南 |
-加入交流群获取帮助、提问和最新动态:
+## 💬 社区
-- **Discord:** https://discord.gg/79JF5Atuk
-- **微信:** 扫描下方二维码
+- **Discord:** https://discord.gg/79JF5Atuk
+- **微信:** 扫描下方二维码
<p align="center">
<img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/agents365ai_wechat_1.png" width="200" alt="微信交流群">
</p>
-## 支持作者
+## ❤️ 支持作者
-如果这个 skill 对你有帮助,欢迎支持作者:
+如果这个 skill 对你有帮助,欢迎支持作者:
<table>
<tr>
@@ -94,13 +152,13 @@ Kafka 消息队列、通知服务,以及各自独立的数据库
</tr>
</table>
-## 作者
+## 👤 作者
**Agents365-ai**
-- Bilibili: https://space.bilibili.com/441831884
- GitHub: https://github.com/Agents365-ai
+- Bilibili: https://space.bilibili.com/441831884
-## License
+## 📄 License
-MIT
+[MIT](https://opensource.org/licenses/MIT)