开工前先把话挑明这个“diagram skill”不是又一个靠酷炫前端界面凑出来的开源玩具它是真正把“让 AI 画出一张准确、可迭代、可直接交付的图”这件事做明白了的项目。上个月我在 GitHub 上刷到它时star 还在噌噌往上涨转眼已经到了 2.9 万这个量级。评论区里有人用它画架构图有人拿去画数据库 ER 图还有嵌入式工程师用它直接输出芯片引脚图整整齐齐地对应 datasheet。这篇文章不讲虚的我会从它为什么能火、内部怎么设计、怎么装怎么用、有哪些坑一路拆到你能基于这个思路做自己的 skill。1. 现象级 star 背后为什么偏偏是“画图”这个场景被引爆1.1 从“AI 写文字”到“AI 画图”中间隔了一个确定性鸿沟先说你我都遇到过的问题。让大模型写一段方案、写一段代码它基本能给出不错的结果因为语言是它的主战场。但一旦让它“画一张系统架构图”不管是让 ChatGPT 直接输出图还是让它生成 Mermaid 代码结果经常很微妙方向箭头胡乱指、节点布局重叠、图例和内容对不上。你催它“再调整一下”它甚至会在下一版把上一版正确的连接线改错。这不是模型不够聪明而是图表本身就要求强约束每个节点有位子每条边有拓扑方向每个 label 不能重叠。大模型天然擅长模糊推理不擅长解决强约束下的几何与拓扑问题。diagram skill 这个项目的核心思路说白了就是把“画图”这件需要确定性的事情从大模型的自由发挥里剥出来模型只负责生成结构化的图形描述文本渲染交给确定的引擎去完成。引擎不会“灵机一动”你给它什么语法它就不打折扣地画出什么图。这一步拆分直接让“AI 画图”从碰运气变成了流水线作业。1.2 2025 年 Agent 生态大爆发让 skill 成了最好的分发单位你可能注意到最近一年 GitHub 上冒出一堆以 “skill” 结尾的仓库比如 superpower skill、codex skill、claude code skill 之类的。这里有个大背景Claude Code、Codex CLI、Trae 这些 AI agent 工具都开始支持一种叫“技能/Skill”的扩展机制。你可以把 skill 理解成给 agent 提前装好的一套“岗位说明书 操作手册 工具脚本”。一个 skill 往往就放在一个目录里里面有SKILL.md描述触发条件和执行步骤有可能带几个辅助脚本agent 在对话中会根据场景自动读取并调用。这种分发形式极轻clone 下来往配置目录一放你的 agent 就多了一项职业能力。画图这件事天然就是 agent 工作流里的一块洼地。你让 agent 帮你梳理代码模块、给新服务画个链路图它要做的工作可不仅仅是“会写点 Mermaid”而是要先理解上下文 → 判断该画什么图 → 组织正确的图语法 → 调用渲染器 → 生成文件 → 验证结果。把这一整套流程编成一个 skillagent 就能自动执行而不是每次都在 prompt 里反复强调。diagram skill 在 star 数上暴涨本质上是吃到了这波 Agent 生态红利大家在同一个时间节点发现原来技能市场里最缺的不是“会聊天的”而是“会干活的”。1.3 skill 和 agent 到底有什么边界不少人在社区问“skill 和 agent 的区别”。按我自己的理解agent 是负责“想”的它负责拆解大目标、编排步骤、决定下一步调用什么skill 则是负责“做”的它是一份已经被验证过的过程化知识agent 只要照着执行就可以拿到固定质量的结果。拿画图举例agent 看到你给它下发“画一下订单服务依赖图”的任务它会拆成“读取代码→抽取依赖→生成 mermaid→调用渲染器”其中“怎么生成 mermaid、怎么选类型、怎么渲染”这部分既有经验沉淀了下来打包成一个 skill。以后任何 agent 装上这个 skill画图就不用重新踩坑。所以别把两者对立它们是大脑和经验手册的关系不是竞争关系。2. skill 的底层设计把 LLM 的画图短板交给确定性引擎2.1 流程图、时序图、架构图、ER 图一次覆盖四种高频场景diagram skill 的价值不仅在于“会画图”还在于它把工程研发中最常用的图表类型全部收纳了。我看它的设计至少覆盖了四类主流场景流程图、时序图、架构图、ER 图。每一类图背后对应一种不同的建模思路。画流程图时你要梳理清楚分支和汇聚节点画时序图时要严格表达消息顺序和生命周期画架构图时要处理模块分层和依赖关系画 ER 图时要准确把握实体、属性和一对多/多对多关系。如果没有 skill 预先帮你约束这些规则让大模型裸奔去画它会在“画流程图”时莫名给你加一堆泳道在“画 ER 图”时把外键关系描述得模棱两可。而 skill 里通常会写明每种图的适用模板、语法规则和“避免做什么”的红线。像我前阵子给一个小型电商系统画服务依赖图直接让 agent 画它给了一堆嵌套节点语义上很丰富but 渲染出来像一锅粥。换成在 prompt 里声明让它调用 diagram skill 之后它自动先判断“这是一张偏分层的架构图”然后按照 skill 里定义的模板输出节点分组、依赖连线和外部边界渲染出来基本可以直接放进方案文档里。这个差别用过的人会非常明显。2.2 Mermaid、Graphviz、D2、Python Diagrams渲染引擎怎么选既然要把确定性交给引擎那引擎本身的选择就很关键。实际情况中不同 skill 项目会在渲染层做不同取舍。我分类说一下后面你自建 skill 时也用得上引擎擅长场景优点明显坑点Mermaid流程图、时序图、甘特图、ER 图语法简单GitHub Markdown 原生支持社区最大复杂布局时节点乱飞中文字体偶尔渲染异常Graphviz(DOT)有向图、依赖关系、树状结构布局算法成熟稳定适合大图自动排版语法反直觉改样式需要查很多属性D2现代架构图、网络拓扑语法清晰布局更现代可交互导出生态小周边工具少Python Diagrams云架构图如 AWS/GCP 组件用代码描述图标和关系深度可编程必须装 Python 环境上手成本略高diagram skill 能这么火很大一部分原因是它没有盲目押注单一渲染引擎而是把 Mermaid 作为默认、Graphviz 和 D2 作为可选项。Mermaid 最大的优势是门槛低你让模型生成的文本人也能直接看懂GitHub、Notion 这类工具直接渲染.mmd文件交付后别人不用装任何软件就能看。而 Graphviz 则用来兜底那些 Mermaid 排版确实搞不定的复杂依赖图。这种“主引擎 备用引擎”的设计给了 skill 极高的场景适配性。2.3 模型只写描述引擎负责渲染工作流怎么拆好的 skill 不仅定义“用什么工具”它还会定义“先做什么、再做什么、最后怎么验证”。diagram skill 的工作流我拆开看大概是五步根据用户请求和上下文确定图表类型流程图、时序图、架构图、ER 图等。在内存/暂存文件里先用结构化的“文字草稿”描述图的含义比如有哪些节点、节点之间是什么关系。把这份文字草稿翻译成目标引擎语法比如 Mermaid 的graph TD; A--B;。把语法文本写入.mmd文件调用渲染器生成 SVG/PNG 等最终产物。回读产物并验证如果渲染失败根据报错信息修正语法后重新渲染如果渲染成功向用户报告产物路径。这个流程看起来简单实际上把“思考”和“制图”解耦了。模型负责推理结构渲染器负责几何处理。我见过不少失败的 prompt 工程问题就出现在让模型“一步到位直接生成成品图”这等于既让它当建筑师又让它当施工队它显然干不好。diagram skill 的做法就是强制加了一道“文本草稿”的中间层。说出来你可能觉得平淡但这个设计正是 2.9 万 star 的技术底气。3. 从零接入目录结构、安装与一次绘图实测3.1 装 skill 的两种标准姿势要上手 diagram skill先把项目源码或者打包好的目录放到 agent 会扫描的 skills 目录里。以当前主流 agent 的目录约定为例一般是~/.claude/skills/或者项目内的.claude/skills/如果用的是其他兼容 agent就放到它对应的skills目录。装法通常有两种。第一种直接用 git clonemkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/xxx/diagrams-skill.git diagrams第二种如果你不想整个仓库挂进来也可以手动复制相关文件mkdir -p ~/.claude/skills/diagrams cp SKILL.md render.py config.yaml ~/.claude/skills/diagrams/装完以后重启你的 agent 客户端让 skill 清单重新加载。一个比较常见的误区是装完不重启导致 agent 看不到新技能于是对话里还是走“裸奔”流程。如果你不确定装没装上直接问一句“你现在有哪些 skill”它会把它能感知到的技能列表列出来。3.2 看明白 SKILL.mdskill 的心智核心一个 skill 能不能用得好SKILL.md的编写质量占 80%。diagram skill 的SKILL.md大概是这种结构--- name: diagrams description: 根据上下文创建或修改各种图表包括流程图、时序图、架构图、ER 图。当用户需要可视化概念、流程、架构或数据关系时启用。 --- # Diagrams Skill ## 适用场景 - 系统架构梳理 - 业务流程可视化 - 数据库模型设计 - 接口调用时序 ... ## 图表类型选择 1. 如果是描述业务流程使用 flowchart 2. 如果是描述消息交换过程使用 sequenceDiagram 3. 如果是描述系统模块使用 architecture 4. 如果是描述数据关系使用 erDiagram ... ## 执行步骤 1. 识别需求 2. 先写节点关系草稿 3. 再生成目标格式语法 4. 写入文件并用 renderer 渲染 5. 验证输出 ...重点在于 frontmatter 里的description它决定了 agent 什么时候会主动想起启用这个 skill。描述写得越具体触发时机越准。如果你发现 agent 在该画图时没调用 skill十有八九是description写得过于泛化模型无法把它和当前任务关联起来。3.3 一次完整的实测画电商下单链路光说不练假把式我来跑一个实际案例。假设我要让 agent 画一张“用户下单到支付完成”的时序图prompt 大概是请用 diagram skill 画一张订单支付时序图 用户创建订单 - 调用库存服务扣减库存 - 创建支付单 - 调用支付网关 - 回调通知 - 更新订单状态agent 识别到这是时序图场景会执行 skill 里的步骤大概率生成一个sequenceDiagram文件。它内部的渲染脚本会把.mmd文件转成 SVGnpx -y mermaid-js/mermaid-cli -i ./order_payment.mmd -o ./order_payment.svg我实测跑下来整个过程大约十几秒。出图效果符合预期消息箭头从上到下排列清楚生命周期虚线也在该出现的位置出现。这一步的体验非常扎实是因为渲染引擎替模型兜了底模型即使把某些节点的相对顺序写乱Mermaid 的布局引擎也不会把节点叠成一团它会在有限区域内尽量平衡排列。对最终用户来说这种“稳定可控”的体验远比偶尔惊艳但常常翻车的裸奔画图要好得多。3.4 没有装 Mermaid CLI 怎么办备好两条路线npx mermaid-js/mermaid-cli是个挺实用的渲染方案但有个现实问题它内部要启 Puppeteer 去渲染 HTML第一次跑的时候要下 Chromium网络不好的环境下经常卡半天还会因为系统缺依赖报错。我们的思路是准备好两条备选路线路线 A本地全局安装mermaid-js/mermaid-cli省去每次 npx 拉包的延迟。路线 B如果画的是简单架构图直接把生成的.mmd内容粘贴到支持 Mermaid 的在线工具或者 IDE 插件里查看不一定非要本地渲染成 SVG。很多团队文档平台天然支持 Mermaid 代码块那连本地渲染都省了。我个人的建议是本地能装则装因为自动化链路里最后一步“验证渲染成功”需要本地有渲染器。如果你在安全受限环境里装不了 puppeteer也可以考虑配置远程渲染服务器或者退回到 Graphviz 这类不需要浏览器的二进制渲染器。4. 这个 skill 到底做对了什么拆解它走红的技术原因4.1 它把“精确”从模型的幻觉手里抢了回来一个 repo 能在 GitHub 冲到 2.9 万 star绝不是靠刷屏营销。diagram skill 最核心的竞争力在于它用系统设计消灭了大模型的“图上幻觉”。所谓图上幻觉就是模型一本正经地画出与事实不符的连接关系比如把 A 服务调 B 服务画成 B 调 A甚至凭空多出两个不存在的中间件。为什么会有这种幻觉因为模型训练数据里类似架构图的描述太多它是在“预测下一个 token”不是在“测量系统接口”。要避免这种问题唯一可靠的办法是给模型一个明确的证据来源。diagram skill 的工程化设计里通常会要求模型先列出节点和边的“证据链”比如“来自哪个文件的哪段代码”“和哪张表的外键对应”。有了这个证据链再让模型把这些信息转换成图形语法图形的正确率就高得多。这个“证据链优先”的设计比任何花哨的 prompt 都管用。4.2 自动动手而不是让用户 Copy 代码块普通 AI 画图工具给你一段 Mermaid 代码然后就结束了剩下的复制粘贴、保存文件、手动渲染全靠你自己。diagram skill 打破了这个体验它会让 agent 直接在当前工作区创建文件调用脚本渲染出成品甚至自动打开预览。这个从“给你代码块”到“帮你生成文件”的跳跃看似只有一步却极大降低了使用成本。GitHub 上能得到开发者青睐的项目往往都是能丝滑吃进已有工作流的而不是让你再单独开一个工具。4.3 与 Claude Code / Codex / Trae 等生态无缝兼容再看它为什么能趁势而起而不是早两年出现。2023 年那阵子市面上还没有成熟的 agent 工作流你就算写出一个 skill 目录也没有载体去执行。到 2025 年Claude Code、Codex CLI、Trae 这些 agent 相继支持“读目录里的 SKILL.md → 按步骤执行 → 调用外部脚本”的机制这个 skill 的基本功才能发挥出来。换句话说它吃到的是 agent 基础设施成熟的第二波红利。你把它装进 Claude Code它会遵守 Claude 的 skill 协议安装到支持相同目录规范的其他工具里执行效果也大差不差。生态兼容面广star 数自然就容易滚起来。4.4 对比普通“Superpower Skill”垂直纵深 vs 提示词堆叠我留意到热词里也有 superpower skill它属于另一派把大量“方法论提示词”打包成一个超大 skill覆盖写作、编程、思考、Plan 等方方面面。这类 skill 乍看很爽实际用起来经常出现“什么都会但什么都不精”的情况。diagram skill 走的路线明显不同它只在“画图”这一个垂直场景里做深做透定义清楚图表类型选择、工作流、调用的渲染引擎、产出的文件位置还顺带给出验证机制。垂直纵深比横向堆叠更有生命力这是它能在细分场景拿到大量 star 的另一个原因。5. 定制、踩坑和实战经验从 74LS00 引脚图到生产级产出5.1 一个硬核案例用 diagram skill 画 74LS00 引脚图热词里有个“74ls00pinout diagram”我看到时差点笑出来因为这正是我踩过坑的场景。74LS00 是经典的 TTL 二输入与非门芯片14 个引脚要让 AI 准确画它的引脚图并不容易模型经常把 7 脚 GND 和 14 脚 VCC 搞反甚至把 1A、1B、1Y 的对应关系画乱。我用 diagram skill 试了一下让它生成一个用于快速理解接线逻辑的表格化图形而不是真正意义上的物理封装图。由于 skill 会强制模型“先列结构化信息再转图形语法”它就能先列出一张准确的事实表引脚功能11A 输入21B 输入31Y 输出7GND14VCC然后再把这张表转换成流程图里那种“左侧输入 → 中间与非门 → 右侧输出”的示意图。虽然 Mermaid 画不了工业级封装图但画逻辑连接关系已经足够了。这个用例说明diagram skill 最适合的其实是“信息结构化图”只要先把数据表列对图就差不到哪去。5.2 踩坑实录Mermaid 渲染失败、中文字体、乱序输出我用 diagram skill 跑了不少图也踩了不少坑挑三个最典型的分享。第一个坑是 Mermaid 语法里的特殊字符。模型画时序图时消息内容里如果带引号、冒号、括号特别是中文括号“”渲染器很容易直接报语法错误。后来我发现 skill 里其实写了“如果消息文本包含特殊字符请用双引号包裹或去掉括号”但模型偶尔还是不听。所以我在自己的定制版本里加了一条更强制的要求任何消息文本一律不允许出现英文括号中文文本里该用引号的必须成对。第二个坑是渲染器字体问题。Mermaid CLI 跑出来的 SVG在中文环境下偶尔会出现豆腐块。这是因为 puppeteer 渲染时找不到合适的中文字体。解决办法也不复杂装个中文字体包到系统里或者用-f参数指定字体文件。我本地用 Linux 环境执行过一次apt install fonts-noto-cjk之后中文渲染就正常了。你要是用 Windows 或者 macOS通常系统自带的中文字体已经够用问题不大。第三个坑是执行顺序被模型打乱。skill 明明写了“先写草稿再渲染”模型碰到复杂任务时却经常想走捷径草稿写到一半就急着调渲染器结果画出来缺节点。为了纠正这个行为我在 SKILL.md 的步骤描述里故意加了两行第一步用“必须输出节点清单”第二步用“等待用户确认后继续”。强制它把结构化草稿当作一个独立交付物而不是随手一写的过程变量。加了这一招之后出图稳定性明显提升。5.3 想自建 skill一套经过验证的“最小可跑模板”diagram skill 的模式完全可以复用到别的垂直场景。我自己搭技能包的时候总结了四条经验你可以直接抄SKILL.md 里必须有清晰的description并且带上触发关键词例如“画图”“图”“diagram”“flowchart”“架构图”“ER 图”。执行步骤必须“可勾选”每一步的输入输出都要有明确凭证。就像 skill 里第一步生成节点清单第二步生成语法文件第三步渲染并验证。渲染错误要有“自动修复循环”。skill 里可以写检测到渲染器返回非零退出码时读取错误信息并再生成修正版语法文件最多重试两次。把默认输出路径固定下来比如docs/diagrams/。这样生成的图会统一收进目录方便你事后整理也让 agent 在后续对话中能准确找到历史产物。5.4 跑偏的风险别让 skill 做它不擅长的事最后给个提醒。diagram skill 再强也不是万能画笔。我见过有人拿它画深度定制的专业电路原理图也有人想让它输出符合出版级排版的复杂 UML 图。Mermaid 和大部分确定性渲染引擎都不支持像素级精确控制。遇到这种高度定制需求老老实实用对应专业工具而不是拿 hammer 拧螺丝。skill 适合的是“结构清晰、可描述、可复用”的图形生成它带来的最大价值是节省了你从“想法”到“第一版图”的时间。至于你要不要在这张图基础上继续精修那是另一段工作。回到 star 数这件事2.9 万本身当然重要但更值得关注的是它验证了一个产品逻辑在 agent 时代专注、可复用、带确定性保障的“技能包”正在成为开发者生产力的放大器。装上这个 skill 后我自己的体验是以前一个上午画不出一张满意的架构图现在十分钟能产三版带迭代痕迹的图。可能你也该试试。 
长河君 · 2026/9/10 5:32:50 · 阅读 1.2k 从agent技能包到确定性渲染：diagram skill如何让AI画图不再翻车？
开工前先把话挑明这个“diagram skill”不是又一个靠酷炫前端界面凑出来的开源玩具它是真正把“让 AI 画出一张准确、可迭代、可直接交付的图”这件事做明白了的项目。上个月我在 GitHub 上刷到它时star 还在噌噌往上涨转眼已经到了 2.9 万这个量级。评论区里有人用它画架构图有人拿去画数据库 ER 图还有嵌入式工程师用它直接输出芯片引脚图整整齐齐地对应 datasheet。这篇文章不讲虚的我会从它为什么能火、内部怎么设计、怎么装怎么用、有哪些坑一路拆到你能基于这个思路做自己的 skill。1. 现象级 star 背后为什么偏偏是“画图”这个场景被引爆1.1 从“AI 写文字”到“AI 画图”中间隔了一个确定性鸿沟先说你我都遇到过的问题。让大模型写一段方案、写一段代码它基本能给出不错的结果因为语言是它的主战场。但一旦让它“画一张系统架构图”不管是让 ChatGPT 直接输出图还是让它生成 Mermaid 代码结果经常很微妙方向箭头胡乱指、节点布局重叠、图例和内容对不上。你催它“再调整一下”它甚至会在下一版把上一版正确的连接线改错。这不是模型不够聪明而是图表本身就要求强约束每个节点有位子每条边有拓扑方向每个 label 不能重叠。大模型天然擅长模糊推理不擅长解决强约束下的几何与拓扑问题。diagram skill 这个项目的核心思路说白了就是把“画图”这件需要确定性的事情从大模型的自由发挥里剥出来模型只负责生成结构化的图形描述文本渲染交给确定的引擎去完成。引擎不会“灵机一动”你给它什么语法它就不打折扣地画出什么图。这一步拆分直接让“AI 画图”从碰运气变成了流水线作业。1.2 2025 年 Agent 生态大爆发让 skill 成了最好的分发单位你可能注意到最近一年 GitHub 上冒出一堆以 “skill” 结尾的仓库比如 superpower skill、codex skill、claude code skill 之类的。这里有个大背景Claude Code、Codex CLI、Trae 这些 AI agent 工具都开始支持一种叫“技能/Skill”的扩展机制。你可以把 skill 理解成给 agent 提前装好的一套“岗位说明书 操作手册 工具脚本”。一个 skill 往往就放在一个目录里里面有SKILL.md描述触发条件和执行步骤有可能带几个辅助脚本agent 在对话中会根据场景自动读取并调用。这种分发形式极轻clone 下来往配置目录一放你的 agent 就多了一项职业能力。画图这件事天然就是 agent 工作流里的一块洼地。你让 agent 帮你梳理代码模块、给新服务画个链路图它要做的工作可不仅仅是“会写点 Mermaid”而是要先理解上下文 → 判断该画什么图 → 组织正确的图语法 → 调用渲染器 → 生成文件 → 验证结果。把这一整套流程编成一个 skillagent 就能自动执行而不是每次都在 prompt 里反复强调。diagram skill 在 star 数上暴涨本质上是吃到了这波 Agent 生态红利大家在同一个时间节点发现原来技能市场里最缺的不是“会聊天的”而是“会干活的”。1.3 skill 和 agent 到底有什么边界不少人在社区问“skill 和 agent 的区别”。按我自己的理解agent 是负责“想”的它负责拆解大目标、编排步骤、决定下一步调用什么skill 则是负责“做”的它是一份已经被验证过的过程化知识agent 只要照着执行就可以拿到固定质量的结果。拿画图举例agent 看到你给它下发“画一下订单服务依赖图”的任务它会拆成“读取代码→抽取依赖→生成 mermaid→调用渲染器”其中“怎么生成 mermaid、怎么选类型、怎么渲染”这部分既有经验沉淀了下来打包成一个 skill。以后任何 agent 装上这个 skill画图就不用重新踩坑。所以别把两者对立它们是大脑和经验手册的关系不是竞争关系。2. skill 的底层设计把 LLM 的画图短板交给确定性引擎2.1 流程图、时序图、架构图、ER 图一次覆盖四种高频场景diagram skill 的价值不仅在于“会画图”还在于它把工程研发中最常用的图表类型全部收纳了。我看它的设计至少覆盖了四类主流场景流程图、时序图、架构图、ER 图。每一类图背后对应一种不同的建模思路。画流程图时你要梳理清楚分支和汇聚节点画时序图时要严格表达消息顺序和生命周期画架构图时要处理模块分层和依赖关系画 ER 图时要准确把握实体、属性和一对多/多对多关系。如果没有 skill 预先帮你约束这些规则让大模型裸奔去画它会在“画流程图”时莫名给你加一堆泳道在“画 ER 图”时把外键关系描述得模棱两可。而 skill 里通常会写明每种图的适用模板、语法规则和“避免做什么”的红线。像我前阵子给一个小型电商系统画服务依赖图直接让 agent 画它给了一堆嵌套节点语义上很丰富but 渲染出来像一锅粥。换成在 prompt 里声明让它调用 diagram skill 之后它自动先判断“这是一张偏分层的架构图”然后按照 skill 里定义的模板输出节点分组、依赖连线和外部边界渲染出来基本可以直接放进方案文档里。这个差别用过的人会非常明显。2.2 Mermaid、Graphviz、D2、Python Diagrams渲染引擎怎么选既然要把确定性交给引擎那引擎本身的选择就很关键。实际情况中不同 skill 项目会在渲染层做不同取舍。我分类说一下后面你自建 skill 时也用得上引擎擅长场景优点明显坑点Mermaid流程图、时序图、甘特图、ER 图语法简单GitHub Markdown 原生支持社区最大复杂布局时节点乱飞中文字体偶尔渲染异常Graphviz(DOT)有向图、依赖关系、树状结构布局算法成熟稳定适合大图自动排版语法反直觉改样式需要查很多属性D2现代架构图、网络拓扑语法清晰布局更现代可交互导出生态小周边工具少Python Diagrams云架构图如 AWS/GCP 组件用代码描述图标和关系深度可编程必须装 Python 环境上手成本略高diagram skill 能这么火很大一部分原因是它没有盲目押注单一渲染引擎而是把 Mermaid 作为默认、Graphviz 和 D2 作为可选项。Mermaid 最大的优势是门槛低你让模型生成的文本人也能直接看懂GitHub、Notion 这类工具直接渲染.mmd文件交付后别人不用装任何软件就能看。而 Graphviz 则用来兜底那些 Mermaid 排版确实搞不定的复杂依赖图。这种“主引擎 备用引擎”的设计给了 skill 极高的场景适配性。2.3 模型只写描述引擎负责渲染工作流怎么拆好的 skill 不仅定义“用什么工具”它还会定义“先做什么、再做什么、最后怎么验证”。diagram skill 的工作流我拆开看大概是五步根据用户请求和上下文确定图表类型流程图、时序图、架构图、ER 图等。在内存/暂存文件里先用结构化的“文字草稿”描述图的含义比如有哪些节点、节点之间是什么关系。把这份文字草稿翻译成目标引擎语法比如 Mermaid 的graph TD; A--B;。把语法文本写入.mmd文件调用渲染器生成 SVG/PNG 等最终产物。回读产物并验证如果渲染失败根据报错信息修正语法后重新渲染如果渲染成功向用户报告产物路径。这个流程看起来简单实际上把“思考”和“制图”解耦了。模型负责推理结构渲染器负责几何处理。我见过不少失败的 prompt 工程问题就出现在让模型“一步到位直接生成成品图”这等于既让它当建筑师又让它当施工队它显然干不好。diagram skill 的做法就是强制加了一道“文本草稿”的中间层。说出来你可能觉得平淡但这个设计正是 2.9 万 star 的技术底气。3. 从零接入目录结构、安装与一次绘图实测3.1 装 skill 的两种标准姿势要上手 diagram skill先把项目源码或者打包好的目录放到 agent 会扫描的 skills 目录里。以当前主流 agent 的目录约定为例一般是~/.claude/skills/或者项目内的.claude/skills/如果用的是其他兼容 agent就放到它对应的skills目录。装法通常有两种。第一种直接用 git clonemkdir -p ~/.claude/skills cd ~/.claude/skills git clone https://github.com/xxx/diagrams-skill.git diagrams第二种如果你不想整个仓库挂进来也可以手动复制相关文件mkdir -p ~/.claude/skills/diagrams cp SKILL.md render.py config.yaml ~/.claude/skills/diagrams/装完以后重启你的 agent 客户端让 skill 清单重新加载。一个比较常见的误区是装完不重启导致 agent 看不到新技能于是对话里还是走“裸奔”流程。如果你不确定装没装上直接问一句“你现在有哪些 skill”它会把它能感知到的技能列表列出来。3.2 看明白 SKILL.mdskill 的心智核心一个 skill 能不能用得好SKILL.md的编写质量占 80%。diagram skill 的SKILL.md大概是这种结构--- name: diagrams description: 根据上下文创建或修改各种图表包括流程图、时序图、架构图、ER 图。当用户需要可视化概念、流程、架构或数据关系时启用。 --- # Diagrams Skill ## 适用场景 - 系统架构梳理 - 业务流程可视化 - 数据库模型设计 - 接口调用时序 ... ## 图表类型选择 1. 如果是描述业务流程使用 flowchart 2. 如果是描述消息交换过程使用 sequenceDiagram 3. 如果是描述系统模块使用 architecture 4. 如果是描述数据关系使用 erDiagram ... ## 执行步骤 1. 识别需求 2. 先写节点关系草稿 3. 再生成目标格式语法 4. 写入文件并用 renderer 渲染 5. 验证输出 ...重点在于 frontmatter 里的description它决定了 agent 什么时候会主动想起启用这个 skill。描述写得越具体触发时机越准。如果你发现 agent 在该画图时没调用 skill十有八九是description写得过于泛化模型无法把它和当前任务关联起来。3.3 一次完整的实测画电商下单链路光说不练假把式我来跑一个实际案例。假设我要让 agent 画一张“用户下单到支付完成”的时序图prompt 大概是请用 diagram skill 画一张订单支付时序图 用户创建订单 - 调用库存服务扣减库存 - 创建支付单 - 调用支付网关 - 回调通知 - 更新订单状态agent 识别到这是时序图场景会执行 skill 里的步骤大概率生成一个sequenceDiagram文件。它内部的渲染脚本会把.mmd文件转成 SVGnpx -y mermaid-js/mermaid-cli -i ./order_payment.mmd -o ./order_payment.svg我实测跑下来整个过程大约十几秒。出图效果符合预期消息箭头从上到下排列清楚生命周期虚线也在该出现的位置出现。这一步的体验非常扎实是因为渲染引擎替模型兜了底模型即使把某些节点的相对顺序写乱Mermaid 的布局引擎也不会把节点叠成一团它会在有限区域内尽量平衡排列。对最终用户来说这种“稳定可控”的体验远比偶尔惊艳但常常翻车的裸奔画图要好得多。3.4 没有装 Mermaid CLI 怎么办备好两条路线npx mermaid-js/mermaid-cli是个挺实用的渲染方案但有个现实问题它内部要启 Puppeteer 去渲染 HTML第一次跑的时候要下 Chromium网络不好的环境下经常卡半天还会因为系统缺依赖报错。我们的思路是准备好两条备选路线路线 A本地全局安装mermaid-js/mermaid-cli省去每次 npx 拉包的延迟。路线 B如果画的是简单架构图直接把生成的.mmd内容粘贴到支持 Mermaid 的在线工具或者 IDE 插件里查看不一定非要本地渲染成 SVG。很多团队文档平台天然支持 Mermaid 代码块那连本地渲染都省了。我个人的建议是本地能装则装因为自动化链路里最后一步“验证渲染成功”需要本地有渲染器。如果你在安全受限环境里装不了 puppeteer也可以考虑配置远程渲染服务器或者退回到 Graphviz 这类不需要浏览器的二进制渲染器。4. 这个 skill 到底做对了什么拆解它走红的技术原因4.1 它把“精确”从模型的幻觉手里抢了回来一个 repo 能在 GitHub 冲到 2.9 万 star绝不是靠刷屏营销。diagram skill 最核心的竞争力在于它用系统设计消灭了大模型的“图上幻觉”。所谓图上幻觉就是模型一本正经地画出与事实不符的连接关系比如把 A 服务调 B 服务画成 B 调 A甚至凭空多出两个不存在的中间件。为什么会有这种幻觉因为模型训练数据里类似架构图的描述太多它是在“预测下一个 token”不是在“测量系统接口”。要避免这种问题唯一可靠的办法是给模型一个明确的证据来源。diagram skill 的工程化设计里通常会要求模型先列出节点和边的“证据链”比如“来自哪个文件的哪段代码”“和哪张表的外键对应”。有了这个证据链再让模型把这些信息转换成图形语法图形的正确率就高得多。这个“证据链优先”的设计比任何花哨的 prompt 都管用。4.2 自动动手而不是让用户 Copy 代码块普通 AI 画图工具给你一段 Mermaid 代码然后就结束了剩下的复制粘贴、保存文件、手动渲染全靠你自己。diagram skill 打破了这个体验它会让 agent 直接在当前工作区创建文件调用脚本渲染出成品甚至自动打开预览。这个从“给你代码块”到“帮你生成文件”的跳跃看似只有一步却极大降低了使用成本。GitHub 上能得到开发者青睐的项目往往都是能丝滑吃进已有工作流的而不是让你再单独开一个工具。4.3 与 Claude Code / Codex / Trae 等生态无缝兼容再看它为什么能趁势而起而不是早两年出现。2023 年那阵子市面上还没有成熟的 agent 工作流你就算写出一个 skill 目录也没有载体去执行。到 2025 年Claude Code、Codex CLI、Trae 这些 agent 相继支持“读目录里的 SKILL.md → 按步骤执行 → 调用外部脚本”的机制这个 skill 的基本功才能发挥出来。换句话说它吃到的是 agent 基础设施成熟的第二波红利。你把它装进 Claude Code它会遵守 Claude 的 skill 协议安装到支持相同目录规范的其他工具里执行效果也大差不差。生态兼容面广star 数自然就容易滚起来。4.4 对比普通“Superpower Skill”垂直纵深 vs 提示词堆叠我留意到热词里也有 superpower skill它属于另一派把大量“方法论提示词”打包成一个超大 skill覆盖写作、编程、思考、Plan 等方方面面。这类 skill 乍看很爽实际用起来经常出现“什么都会但什么都不精”的情况。diagram skill 走的路线明显不同它只在“画图”这一个垂直场景里做深做透定义清楚图表类型选择、工作流、调用的渲染引擎、产出的文件位置还顺带给出验证机制。垂直纵深比横向堆叠更有生命力这是它能在细分场景拿到大量 star 的另一个原因。5. 定制、踩坑和实战经验从 74LS00 引脚图到生产级产出5.1 一个硬核案例用 diagram skill 画 74LS00 引脚图热词里有个“74ls00pinout diagram”我看到时差点笑出来因为这正是我踩过坑的场景。74LS00 是经典的 TTL 二输入与非门芯片14 个引脚要让 AI 准确画它的引脚图并不容易模型经常把 7 脚 GND 和 14 脚 VCC 搞反甚至把 1A、1B、1Y 的对应关系画乱。我用 diagram skill 试了一下让它生成一个用于快速理解接线逻辑的表格化图形而不是真正意义上的物理封装图。由于 skill 会强制模型“先列结构化信息再转图形语法”它就能先列出一张准确的事实表引脚功能11A 输入21B 输入31Y 输出7GND14VCC然后再把这张表转换成流程图里那种“左侧输入 → 中间与非门 → 右侧输出”的示意图。虽然 Mermaid 画不了工业级封装图但画逻辑连接关系已经足够了。这个用例说明diagram skill 最适合的其实是“信息结构化图”只要先把数据表列对图就差不到哪去。5.2 踩坑实录Mermaid 渲染失败、中文字体、乱序输出我用 diagram skill 跑了不少图也踩了不少坑挑三个最典型的分享。第一个坑是 Mermaid 语法里的特殊字符。模型画时序图时消息内容里如果带引号、冒号、括号特别是中文括号“”渲染器很容易直接报语法错误。后来我发现 skill 里其实写了“如果消息文本包含特殊字符请用双引号包裹或去掉括号”但模型偶尔还是不听。所以我在自己的定制版本里加了一条更强制的要求任何消息文本一律不允许出现英文括号中文文本里该用引号的必须成对。第二个坑是渲染器字体问题。Mermaid CLI 跑出来的 SVG在中文环境下偶尔会出现豆腐块。这是因为 puppeteer 渲染时找不到合适的中文字体。解决办法也不复杂装个中文字体包到系统里或者用-f参数指定字体文件。我本地用 Linux 环境执行过一次apt install fonts-noto-cjk之后中文渲染就正常了。你要是用 Windows 或者 macOS通常系统自带的中文字体已经够用问题不大。第三个坑是执行顺序被模型打乱。skill 明明写了“先写草稿再渲染”模型碰到复杂任务时却经常想走捷径草稿写到一半就急着调渲染器结果画出来缺节点。为了纠正这个行为我在 SKILL.md 的步骤描述里故意加了两行第一步用“必须输出节点清单”第二步用“等待用户确认后继续”。强制它把结构化草稿当作一个独立交付物而不是随手一写的过程变量。加了这一招之后出图稳定性明显提升。5.3 想自建 skill一套经过验证的“最小可跑模板”diagram skill 的模式完全可以复用到别的垂直场景。我自己搭技能包的时候总结了四条经验你可以直接抄SKILL.md 里必须有清晰的description并且带上触发关键词例如“画图”“图”“diagram”“flowchart”“架构图”“ER 图”。执行步骤必须“可勾选”每一步的输入输出都要有明确凭证。就像 skill 里第一步生成节点清单第二步生成语法文件第三步渲染并验证。渲染错误要有“自动修复循环”。skill 里可以写检测到渲染器返回非零退出码时读取错误信息并再生成修正版语法文件最多重试两次。把默认输出路径固定下来比如docs/diagrams/。这样生成的图会统一收进目录方便你事后整理也让 agent 在后续对话中能准确找到历史产物。5.4 跑偏的风险别让 skill 做它不擅长的事最后给个提醒。diagram skill 再强也不是万能画笔。我见过有人拿它画深度定制的专业电路原理图也有人想让它输出符合出版级排版的复杂 UML 图。Mermaid 和大部分确定性渲染引擎都不支持像素级精确控制。遇到这种高度定制需求老老实实用对应专业工具而不是拿 hammer 拧螺丝。skill 适合的是“结构清晰、可描述、可复用”的图形生成它带来的最大价值是节省了你从“想法”到“第一版图”的时间。至于你要不要在这张图基础上继续精修那是另一段工作。回到 star 数这件事2.9 万本身当然重要但更值得关注的是它验证了一个产品逻辑在 agent 时代专注、可复用、带确定性保障的“技能包”正在成为开发者生产力的放大器。装上这个 skill 后我自己的体验是以前一个上午画不出一张满意的架构图现在十分钟能产三版带迭代痕迹的图。可能你也该试试。