create-diagram

用途

根据描述生成正确、经过渲染的图表，并将每个请求路由到合适的工具。交付物是经过验证的图片及其源码；或者在渲染工具确实不可用时，交付已经校验、并明确标注未做渲染验证的源码。绝不交付未经运行或校验的图表代码：未渲染的图表源码是本技能最主要的失败模式，因为语法与导入错误只有在渲染时才会暴露。

工作流程

按以下清单跟踪进度：

Diagram Progress:
- [ ] 1. Routed by type and destination
- [ ] 2. Matching reference read
- [ ] 3. Content planned
- [ ] 4. Source written, names resolved not guessed
- [ ] 5. Rendered and verified
- [ ] 6. Delivered with source

1. 按图表类型和目标位置路由

请求类型	工具	参考文档
云架构、基础设施、网络拓扑、Kubernetes、本地部署、任何需要厂商图标的图	Python `diagrams` 库	`references/diagrams-library.md`
流程图、时序图、状态机、ER 图、类图、甘特图、git 图、思维导图	Mermaid	`references/mermaid.md`
C4 模型	默认使用 `diagrams` 库；当目标位置是 Markdown 文件时使用 Mermaid	参照上述选择

目标位置会覆盖类型：当图表位于会被 GitHub、GitLab 或 Obsidian 渲染的 Markdown 文件中（README、docs、vault 笔记）时，即使是简单的架构图也优先使用围栏式 Mermaid 代码块，因为目标位置会原生渲染它，并让源码保持就地可编辑。独立的图片交付物则对任何基础设施形态的图优先使用 diagrams 库，因为厂商图标承载真实信息。

2. 阅读对应的参考文档

参考文件包含对应工具的 API、语法、失败模式和示例。不要凭对任一工具的记忆来编写源码；两者都有不明显的陷阱（diagrams 中的导入大小写、Mermaid 中的保留字），这些都记录在参考文档中。

3. 规划内容

在编写源码之前先列出节点和关系。一张图只聚焦一个关注点：同时展示部署拓扑、请求流和 CI 流水线的图，三者都表达不清。改为提供多张图。单个图的可读性实际上限约为 15-20 个节点。

4. 编写源码

diagrams 库：绝不猜测导入路径或类名。对于任何不是从参考文档起始列表中逐字复制的节点，先用 uv run ${CLAUDE_SKILL_DIR}/scripts/find-node.py <term> 解析；该库有约 2,900 个节点类，大小写不一致，猜测导入是渲染失败的首要原因。
Mermaid：遵循参考文档中的语法规则；对任何含有特殊字符或保留字的标签加引号。

5. 渲染并验证

这是强制步骤，也是让本技能可靠的关键。

Python diagrams 路径：

uv run <filename>.py && ls <filename>.png

生成的脚本包含 PEP 723 元数据（见参考文档），因此 uv run 无需环境配置即可解析 diagrams 依赖。出现 ImportError 时，用 uv run ${CLAUDE_SKILL_DIR}/scripts/find-node.py <name> 解析正确路径并修复；出现 ExecutableNotFound: failed to execute 'dot' 时，表示缺少 Graphviz（按参考文档安装）。重复运行直到图片文件存在。

Mermaid 路径，按顺序：

如果 mmdc 或 npx 可用：npx -y @mermaid-js/mermaid-cli -i <file>.mmd -o <file>.svg（首次运行会下载无头 Chromium；慢一次，之后缓存）
如果两者都不存在，尝试一次安装：npm install -g @mermaid-js/mermaid-cli；失败后不要重试
如果仍无法渲染，交付围栏式源码，并明确说明它已经过校验但未做渲染验证
Markdown 目标位置的图不需要图片文件；围栏代码块就是交付物，但当工具存在时仍在本地渲染，因为在提交前捕获语法错误正是重点

查看结果。 任何成功渲染之后，用 Read 工具打开图片并检查：标签重叠、孤立节点、与内容相冲突的布局方向，都属于渲染成功但图表失败的情况。修复后重新渲染。

6. 交付

提供渲染后的图片和源码文件。说明验证了什么："rendered and inspected" 或 "validated, not render-verified, because no renderer was available"。当图片就是交付物时，把它发送给用户。

通用规则

绝不交付未经运行或校验的源码。 图表代码在渲染时失败，而不是在编写时；交付未运行的源码等于把调试工作转交出去。
解析名称，绝不猜测。 这同样适用于 diagrams 导入路径和 Mermaid 图标或形状名称。
不要常驻进程。 预览服务器和 watch 模式会挂起智能体会话；改为渲染到文件。
每张图一个源码文件，按内容命名（payment-flow.mmd、vpc_topology.py），使重新渲染和编辑保持简单。

注意事项

把类名改成"正确"大小写反而会破坏它。 diagrams 库使用 Cronjob、Dynamodb、IOS；看起来更自然的 CronJob 或 DynamoDB 会抛出 ImportError。脚本会解析确切大小写；相信它的输出而非直觉。
Mermaid 的渲染位置比你想的更多。 GitHub、GitLab 和 Obsidian 都原生渲染围栏式 mermaid 代码块；图片文件对文档来说往往是不合适的交付物，因为它无法编辑或 diff。
渲染成功不等于图表成功。 Graphviz 会乐于渲染重叠的边和难以阅读的布局。检查步骤存在，是因为退出码 0 只证明语法正确，不证明表达清楚。
首次 Mermaid 渲染很慢，但不是坏了。 mermaid-cli 首次使用会下载无头 Chromium；不要中止它，也不要在下载过程中判断工具不可用。