Content
<a href="#english">English</a> | <a href="#中文">中文</a>
---
<a id="english"></a>
# aws-excalidraw-diagram
An agent skill for generating beautiful Excalidraw architecture diagrams from natural language descriptions, with AWS icon library support.
Based on [@coleam00](https://github.com/coleam00)'s [excalidraw-diagram-skill](https://github.com/coleam00/excalidraw-diagram-skill), modified to use **Chrome DevTools MCP** for rendering instead of Playwright, and extended with AWS icon search/extract tooling.
## What This Does
**aws-excalidraw-diagram** lets you describe a system architecture in plain language, and the agent generates a production-quality `.excalidraw` diagram — rendered to PNG via a real Chrome browser for visual validation.
Diagrams are designed to **argue visually**, not just display information. The skill guides the agent through concept mapping, layout design, JSON generation, and an iterative render-view-fix loop.
## Key Features
- **Natural Language → Diagram** — Describe your architecture, get an `.excalidraw` file + PNG.
- **Chrome DevTools MCP Rendering** — Uses a real Chrome browser for reliable rendering (no Playwright/headless issues).
- **AWS Icon Library Support** — Search and extract official AWS service icons from `.excalidrawlib` files via the bundled `search_icons.py` tool.
- **Visual Argument Design** — Diagrams use shape, color, and layout to convey meaning, not just label boxes.
- **Iterative Refinement** — Render → View → Fix loop until the diagram looks right.
- **Brand Customizable** — All colors are centralized in `color-palette.md` for easy theming.
## Prerequisites
- An AI IDE or agent that supports skills (e.g. [Claude Code](https://claude.ai/claude-code))
- [Chrome DevTools MCP server](https://www.npmjs.com/package/@anthropic-ai/chrome-devtools-mcp) — add to your MCP settings:
```json
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["@anthropic-ai/chrome-devtools-mcp@latest"]
}
}
}
```
- (Optional) An `.excalidrawlib` file with AWS icons for icon extraction
## Installation
### Option 1: Clone and copy the skill folder
```bash
git clone https://github.com/lanceli93/aws-excalidraw-diagram.git
cp -r aws-excalidraw-diagram/aws-excalidraw-diagram ~/.claude/skills/aws-excalidraw-diagram
```
### Option 2: Clone and symlink (easy to update)
```bash
git clone https://github.com/lanceli93/aws-excalidraw-diagram.git ~/aws-excalidraw-diagram
ln -s ~/aws-excalidraw-diagram/aws-excalidraw-diagram ~/.claude/skills/aws-excalidraw-diagram
```
To update later, just `git pull` in the cloned repo.
## Usage
Ask the agent to create a diagram:
```
Create an AWS three-tier architecture diagram: ALB → EC2 → RDS
```
The skill will:
1. Assess the diagram depth (simple vs comprehensive)
2. Map concepts to visual patterns (fan-out, convergence, timeline, etc.)
3. Generate `.excalidraw` JSON, section by section for large diagrams
4. Render to PNG via Chrome DevTools MCP
5. Visually inspect and fix issues in a loop
### AWS Icon Search
If you have an `.excalidrawlib` file with AWS icons:
```bash
# Search for an icon
python3 .claude/skills/aws-excalidraw-diagram/references/search_icons.py <lib-path> search "ALB"
# Extract icon elements positioned at (x, y)
python3 .claude/skills/aws-excalidraw-diagram/references/search_icons.py <lib-path> extract "ALB" --x 300 --y 200 --id-prefix alb1
# List all available icons
python3 .claude/skills/aws-excalidraw-diagram/references/search_icons.py <lib-path> list
```
## Output
```
diagrams/my-architecture/
├── my-architecture.excalidraw # Excalidraw JSON (editable in excalidraw.com)
└── my-architecture.png # Rendered PNG
```
## Skill Structure
```
aws-excalidraw-diagram/
├── SKILL.md # Main skill instructions
├── README.md # Original upstream README
└── references/
├── color-palette.md # Brand colors (customizable)
├── element-templates.md # JSON templates for each element type
├── json-schema.md # Excalidraw JSON format reference
├── render_template.html # Browser template for rendering
└── search_icons.py # AWS icon search/extract tool
```
## License
MIT — See [LICENSE](LICENSE) for details.
---
<a id="中文"></a>
# aws-excalidraw-diagram
一个 Agent 技能，通过自然语言描述生成精美的 Excalidraw 架构图，支持 AWS 图标库。
基于 [@coleam00](https://github.com/coleam00) 的 [excalidraw-diagram-skill](https://github.com/coleam00/excalidraw-diagram-skill)，改用 **Chrome DevTools MCP** 渲染（替代 Playwright），并扩展了 AWS 图标搜索/提取工具。
## 这是什么
**aws-excalidraw-diagram** 让你用自然语言描述系统架构，Agent 会生成生产级别的 `.excalidraw` 图表，并通过真实 Chrome 浏览器渲染为 PNG 进行可视化验证。
图表的设计理念是 **用视觉来论证**，而不仅仅是展示信息。技能会引导 Agent 进行概念映射、布局设计、JSON 生成，以及迭代式的渲染-检查-修复循环。
## 核心特性
- **自然语言 → 图表** —— 描述你的架构，得到 `.excalidraw` 文件 + PNG。
- **Chrome DevTools MCP 渲染** —— 使用真实 Chrome 浏览器进行可靠渲染（无 Playwright/无头浏览器问题）。
- **AWS 图标库支持** —— 通过内置的 `search_icons.py` 工具从 `.excalidrawlib` 文件中搜索和提取官方 AWS 服务图标。
- **视觉论证式设计** —— 图表通过形状、颜色和布局传达含义，而非简单地标记方框。
- **迭代式优化** —— 渲染 → 查看 → 修复循环，直到图表效果满意。
- **品牌可定制** —— 所有颜色集中在 `color-palette.md` 中，方便主题定制。
## 前置要求
- 支持技能的 AI IDE 或 Agent（如 [Claude Code](https://claude.ai/claude-code)）
- [Chrome DevTools MCP 服务器](https://www.npmjs.com/package/@anthropic-ai/chrome-devtools-mcp) —— 添加到 MCP 设置中：
```json
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["@anthropic-ai/chrome-devtools-mcp@latest"]
}
}
}
```
- （可选）包含 AWS 图标的 `.excalidrawlib` 文件，用于图标提取
## 安装
### 方式一：克隆后复制技能文件夹
```bash
git clone https://github.com/lanceli93/aws-excalidraw-diagram.git
cp -r aws-excalidraw-diagram/aws-excalidraw-diagram ~/.claude/skills/aws-excalidraw-diagram
```
### 方式二：克隆后创建符号链接（便于更新）
```bash
git clone https://github.com/lanceli93/aws-excalidraw-diagram.git ~/aws-excalidraw-diagram
ln -s ~/aws-excalidraw-diagram/aws-excalidraw-diagram ~/.claude/skills/aws-excalidraw-diagram
```
后续更新只需在克隆目录中执行 `git pull`。
## 使用方法
让 Agent 创建图表：
```
画一个 AWS 三层架构图：ALB → EC2 → RDS
```
技能将会：
1. 评估图表深度（简单 vs 全面）
2. 将概念映射到视觉模式（扇出、汇聚、时间线等）
3. 逐节生成 `.excalidraw` JSON（大型图表分段生成）
4. 通过 Chrome DevTools MCP 渲染为 PNG
5. 可视化检查并在循环中修复问题
### AWS 图标搜索
如果你有包含 AWS 图标的 `.excalidrawlib` 文件：
```bash
# 搜索图标
python3 .claude/skills/aws-excalidraw-diagram/references/search_icons.py <lib路径> search "ALB"
# 提取图标元素，定位到 (x, y)
python3 .claude/skills/aws-excalidraw-diagram/references/search_icons.py <lib路径> extract "ALB" --x 300 --y 200 --id-prefix alb1
# 列出所有可用图标
python3 .claude/skills/aws-excalidraw-diagram/references/search_icons.py <lib路径> list
```
## 输出结构
```
diagrams/my-architecture/
├── my-architecture.excalidraw # Excalidraw JSON（可在 excalidraw.com 中编辑）
└── my-architecture.png # 渲染的 PNG
```
## 技能文件结构
```
aws-excalidraw-diagram/
├── SKILL.md # 主技能指令
├── README.md # 上游原始 README
└── references/
├── color-palette.md # 品牌颜色（可定制）
├── element-templates.md # 各元素类型的 JSON 模板
├── json-schema.md # Excalidraw JSON 格式参考
├── render_template.html # 浏览器渲染模板
└── search_icons.py # AWS 图标搜索/提取工具
```
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
