详解 AI Agent 画图技能：从原理到自定义开发实践

最近 GitHub 上有个 diagram skill 项目把我注意力拉过去了：Star 数一路涨到 2.9 万，几乎是我见过涨得最快的 Agent 技能类仓库之一。作为长期折腾 Claude Code、Codex 这类工具的人，我一开始以为又是那种“放了个特别炫的页面、实际就是个 prompt 合集”的项目，结果真跑了一圈之后发现，这次确实是戳到痛点上了。

这个 diagram skill 不是什么新的画图引擎，也不是“让你在浏览器里用 AI 生成图片”的套壳工具，它本质上是把“让 AI Agent 画图”这件事标准化了：从输入需求、到拆解图形结构、再到渲染成可编辑的架构图或流程图，全程可以在对话里完成。这篇文章我会从实际使用的角度聊聊它为什么能涨这么多 Star，拆开看它内部到底做了什么，并且带大家从零写一个自己的 diagram skill。如果你平时经常让 AI 帮你写方案、画系统设计图、做流程图，这篇文章应该对你有用。

1. 为什么一个“画图技能”能拿到 2.9 万 Star

1.1 它解决的痛点：AI 聊天画图为什么总让人抓狂

过去两三年，大家让 AI 画图的姿势基本是这样的：在对话框里输入“帮我画一个登录流程图”，然后 AI 噼里啪啦回你一堆 Markdown，里面嵌着一段 Mermaid 语法。结果你想看效果，还得自己复制到某个在线渲染工具里，或者本地装个插件；运气不好语法渲染失败，你还得把报错信息原封不动贴回去让 AI 再改一版。遇上稍微复杂的架构图，节点一多，连线就乱，AI 还会自信地画出一些不存在的模块。

这个 diagram skill 解决的正是这一连串问题。它不是一个画图工具，而是一套让 Agent 自己完成“需求分析、结构规划、源文件生成、可视化渲染、按反馈迭代”的完整工作流。你只要说“帮我画一个订单系统的模块架构图”，它不会丢给你一段需要二次处理的代码，而是直接产出 SVG、HTML 或者可以导入常见绘图工具的源文件，并且这些内容是可以在浏览器里直接打开、放大、修改的。

更关键的是，它解决了“可编辑”的问题。普通方式生成的图片，改起来基本靠重新生成；diagram skill 输出的东西保留源文件结构，你可以要求它“把支付模块换成消息队列” “给用户模块加两个子模块”，Agent 能做精准修改而不是全图重画。这体验差距就很大了。

1.2 skill 到底是什么，它和普通 prompt 有什么区别

先把概念对齐。这里的 skill 不是 OpenClaw 那类游戏里的技能，而是现在 Agent 生态里很流行的一个概念：把一组指令、规则、脚本、示例文件打包成目录，让 Claude、Codex、OpenClaw 这类 AI Agent 在特定任务出现时自动加载并执行。一个标准 skill 目录通常包含 SKILL.md 描述文件、assets 资源目录、scripts 脚本目录，以及一些 examples 示例。

那它和普通 prompt 有什么区别？举例说明：普通 prompt 是“你现在是一个架构师，请帮忙画一个订单系统图”，指令纯粹依赖模型当时的发挥，模型心情好画得详细点，心情差可能只给你三行字。而 skill 是一套经过整理的“工作手册”：它告诉 Agent 遇到画图请求时先做什么、再做什么，必须输出什么格式，哪些规则不能违反，甚至连渲染脚本都准备好了。Agent 加载 skill 之后，不再是一个概念性的角色扮演，而是真的进入了一套可执行的工作流程。

所以项目和普通“提示词工程”完全不是一回事。前者做的是画图规则，后者只是临时约束；skill 可以把复杂流程拆分成可依赖的步骤，甚至调用本地脚本完成渲染和校验，这才是它能火起来的根本原因——它展示的是未来 Agent 使用工具的完整姿势。

1.3 高 Star 背后的逻辑

一个画图技能能涨到 2.9 万 Star，我观察下来有几个原因。门槛低是第一个，这个项目几乎不需要部署，把 skill 目录放进对应配置路径，AI 立刻就会用了，不像很多 AI 项目要配环境、调 API、折腾半天；第二个是需求真实，搞架构设计、写技术方案、做汇报 PPT 的人都深受“AI 画图画不好”困扰，这恰好命中；第三个是生态红利，Claude Code、Codex 陆续开始支持 skill 规范，大家发现原来 Agent 可以这样用，于是大量用户涌进来围观、收藏、转发。

还有一个容易被忽略的点：2.9 万 Star 不一定是说代码量多牛，更多表示“有大量的人觉得这个方案解决了一个真实问题，并且愿意把它收藏进自己的工具箱”。这给后来做 Agent 插件的人一个很好的信号：不一定非要做大模型，能在工作流里补上一个恰到好处的工具型技能，就已经能影响很多人了。

2. 实测：用 diagram skill 画一整套架构图

2.1 怎么把 skill 装进你的 Agent

我是在本地同时装了 Claude Code 和 Codex CLI 的环境里测的。这两个工具现在都支持自定义 skill，安装方式也比较接近：把 skill 目录放到 Agent 读取的 skills 根目录下即可。Claude Code 通常读取个人目录下的~/.claude/skills/或项目目录下的.claude/skills/；Codex 则支持类似路径，另外还兼容部分社区 skill 管理工具。

以 Claude Code 为例，安装一个 diagram skill 的典型步骤是这样的：

# 创建个人 skills 目录 mkdir -p ~/.claude/skills # 把下载的 diagram skill 项目放进去 cd ~/.claude/skills git clone https://github.com/your-downloaded-repo/diagram-skill.git diagram

注意，放进去之后最好检查一下目录结构是否满足要求：根目录必须有SKILL.md文件，而且文件名必须精确，不能叫skill.md或者skill.txt。项目级安装则更轻量，适合团队共享，在仓库根目录建.claude/skills/并提交到 Git，所有协作的人 clone 下来就能用。

装好之后不用重启 Agent，新开一个对话就能生效。测试是否加载成功有个笨办法：直接问 Agent“你有哪些技能可用”，如果新对话里它能列出 diagram 相关能力，说明加载正常。

2.2 从一句话到一张合格架构图

我实际测试时输入的是：“画一个订单系统的模块架构图，包含前端、后端服务、消息队列、数据库几个部分，标注关键交互。”没有用 skill 的情况下，AI 大概率会直接返回一段 Mermaid 源码，让你自己去渲染；但用了 diagram skill 之后，它的输出明显不同。

Agent 先是把需求拆成了几个阶段：列出核心模块、梳理模块间依赖、确定图的方向和层次、生成可视化文件。几秒钟后，它给了我一个 HTML 文件，浏览器打开就是一张层次分明的订单系统架构图：顶部是前端应用层，中间是订单服务、支付服务、库存服务，底部是 MySQL、Redis、MQ 消息队列，节点之间用箭头标了调用关系，每个模块旁边还有一行小字说明职责。

让我比较满意的不是它第一版画得多好看，而是后续迭代非常顺滑。我说“把支付服务拆成支付网关和清结算两个模块”，它是真的只动了局部，把旧的支付模块节点替换成两个新节点，并且重新拉了关联线，没有把整张图打乱重画。这种体验，传统“复制代码到渲染器”方式完全给不了。

2.3 同一需求：不用 skill 和用 skill 的对比

为了更直观地说明差异，我整理了一张对比表，都是同一个需求下的实际表现：

这个差异对齐了一个核心问题：AI 生成内容之后，人能不能有效继续加工。如果生成出来的东西只是一个中间格式，那本质上是把工作量后置给了用户；diagram skill 把这一步也接管了，这是它体验上最大的提升。

3. 拆开看：diagram skill 内部到底写了什么

3.1 SKILL.md 的骨架

一个好的 skill 一定有一个结构清晰的SKILL.md，它是整个技能的“主控逻辑”。我翻了几个类似项目的写法，基本可以归纳成三部分：YAML frontmatter、正文指令、示例参考。frontmatter 里最核心的是name和description，前者是技能的唯一标识，后者决定了 Agent 在什么时候决定调用它。

正文部分是关键。拿 diagram skill 举例，它通常会规定一套“接到画图任务后必须执行”的流程，比如：

--- name: diagram description: 用于绘制架构图、流程图、时序图、网络拓扑图等，适合用户要求生成图表或可视化内容时使用。 --- # Diagram Skill ## 工作流程 1. 分析用户需求，确认图表类型 2. 列出图表涉及的核心实体与关系 3. 设计布局方向，确定分层或分组方式 4. 生成可视化文件，保证浏览器可直接打开 5. 询问用户是否需要调整 ## 输出要求 - 优先输出 HTML 文件，内嵌 SVG - 每个节点必须包含名称和职责说明 - 连线必须标注方向，复杂关系需要图例 - 禁止生成无源文件的纯图片

这种结构其实就是在告诉 Agent：“你不是凭感觉画，而是按这套流程来。”规则不复杂，但能强制 Agent 在绘图前先思考结构，避免一上来就堆节点。

3.2 规则为什么是质量的关键

我见过不少玩家自己写画图 prompt，写得很长很详细，但效果依然不稳定。原因在于 prompt 只是软约束，模型上下文稍微一变，输出就飘了。而 skill 里的规则更像硬约束，它可以通过脚本在生成后续阶段做校验，不满足条件直接返回错误，让 Agent 重新生成。

举几个优秀的规则设计例子：

• “架构图必须先列出模块清单再动手” —— 强制 Agent 先做规划，而不是边画边想；
• “每个节点必须有名称和一句话职责” —— 保证图形不只是“好看的框”，还是有信息量的；
• “连线必须使用箭头并标注方向” —— 避免用户看了半天不知道调用关系；
• “输出文件必须完整可打开，不允许只输出代码片段” —— 这是质量红线。

规则设计的原则是“可判定”，也就是 Agent 能自己判断有没有做到。如果规则写得太笼统，比如“画得好看一点”，模型无法判断好看到什么程度，等于没写。而“必须包含图例”这类规则，Agent 就能检查并在缺失时自行补上。

3.3 渲染环节：为什么是 SVG、HTML，而不是 Mermaid

很多第一次接触 diagram skill 的人会觉得奇怪：AI 生成 Mermaid 不是已经很成熟了吗，为什么还要费劲搞 HTML/SVG？我的理解是这样的：Mermaid 是文本描述图形语法，适合快速预览，但在复杂图表上能力有限，布局一旦复杂就容易乱；SVG 则是一种矢量图形格式，渲染能力完整、可控性强、浏览器原生支持，并且“可编辑性”非常好。

SVG 是用 XML 描述图形元素的，每个节点都是一个矩形和一个文本框，每条连线都是一条 path 或 line。这意味着你可以用程序去修改任意节点位置、颜色、文本内容，也可以让 AI 精准地改一个模块而不影响其他部分。很多 diagram skill 会内置一个渲染脚本，把中间格式（比如 JSON 描述）转换成 SVG，甚至直接包一层 HTML，方便用浏览器打开，顺带支持导出 PNG。

也正是因为这一步，让用户可以“看到”AI 画的东西，而不仅仅拿到一段源码。

3.4 token 开销与 skill 设计约束

如果你想做一个自己的 skill，还有一个经常被忽略的问题：token 成本。SKILL.md每次被加载都会占用上下文，如果写得又长又啰嗦，Agent 做几轮迭代后上下文就被撑爆了，反而影响输出质量。

经验上，SKILL.md正文控制在 3-6KB 比较合适，规则只保留那些真正影响输出质量的硬性要求。复杂逻辑尽量放到外部脚本里，比如渲染函数、解析函数、校验程序，Agent 只需要知道“生成 JSON 描述后调用 render.py”这件事就够了。

我会在下一节用一个具体例子演示：怎么把流程写进 SKILL.md，把渲染逻辑抽到脚本里，这样 token 开销小，又保留了功能。

4. 从零写一个自己的 diagram skill：完整可复现

4.1 先定场景，收敛范围

很多人一上来就想写一个“万能画图技能”，结果越写越乱。我建议第一次尝试不要贪多，只做一个“架构图专用 skill”。范围收敛有两个好处：一是规则容易设计，你能把架构图的所有细节都列清楚；二是测试方便，一两个典型任务就能验证效果。

我这个示例的方向很简单：用户提出系统模块划分需求，Agent 输出一份 JSON 结构描述，再用本地脚本渲染成 SVG/HTML 架构图。整个链路不复杂，但足以让你掌握 skill 的开发流程。

4.2 创建目录和核心文件

我的项目内部规划：

my-diagram-skill/ ├── SKILL.md ├── scripts/ │ ├── render.py │ └── validate.py ├── assets/ │ └── template.html └── examples/ └── order-system.json

SKILL.md是主控，render.py负责把 JSON 描述转成 SVG，validate.py做基础校验，template.html是浏览器展示的壳。

SKILL.md我写的是这样：

--- name: arch-diagram description: 用于生成系统架构图，适合用户要求梳理系统模块、组件关系、服务依赖等场景。 --- # Architecture Diagram Skill ## 输入分析 - 先提取核心系统、子模块、外部依赖 - 确认是否需要分层展示 ## 输出格式 - 先输出 JSON 描述文件 - 脚本渲染为 HTML/SVG ## 规则 - 节点包含 id、label、description、layer - 连线包含 from、to、label、arrow - 顶部必须有系统标题和图例 - 每个节点必须有职责说明 ## 步骤 1. 分析输入需求 2. 生成 JSON 描述 3. 调用 validate.py 校验 4. 调用 render.py 渲染成 HTML 5. 提供访问方式

描述写得越具体，Agent 命中调用的概率越高。如果你写成“画图专用”，Agent 在大多数场景不会想起它；但写成“系统架构图、模块关系、服务依赖”，命中率就明显提升了。

4.3 用一个脚本把 JSON 描述变成 SVG

渲染脚本是我这个 skill 的核心支撑。我没有引重型前端框架，直接用 Python 脚本生成 SVG 字符串，这样在任何环境都能快速运行。核心代码大体长这样：

import json import sys def render_node(node, x, y): label = node.get("label", "?") desc = node.get("description", "") w, h = 220, 80 rect = f'<rect x="{x}" y="{y}" width="{w}" height="{h}" rx="8" fill="#f8f9fa" stroke="#4a6cf7" stroke-width="2"/>' text = f'<text x="{x+10}" y="{y+28}" font-size="14" font-weight="bold">{label}</text>' if desc: text += f'<text x="{x+10}" y="{y+50}" font-size="11" fill="#666">{desc}</text>' return f'<g>{rect}{text}</g>', x + w, y + h def render_edge(edge): return f'<line x1="{edge["x1"]}" y1="{edge["y1"]}" x2="{edge["x2"]}" y2="{edge["y2"]}" stroke="#999" stroke-width="1.5" marker-end="url(#arrow)"/>' if __name__ == "__main__": data = json.load(open(sys.argv[1])) nodes_svg = [] edges_svg = [] x, y = 40, 40 for layer in data["layers"]: for node in layer["nodes"]: svg, x_next, y_bottom = render_node(node, x, y) nodes_svg.append(svg) y += 100 x += 260 y = 40 # 拼装完整 SVG header = f'<svg xmlns="http://www.w3.org/2000/svg" width="{x+200}" height="600">' footer = "</svg>" html = f'<html><head><meta charset="utf-8"></head><body>{header}{"".join(nodes_svg)}{"".join(edges_svg)}{footer}</body></html>' print(html)

这只是一个缩短后的 MVP 版本，正式场景里还可以加自动布局算法、节点颜色分层、箭头 marker、中文注释等。但核心思想是：AI 生成结构化 JSON，脚本做渲染，各司其职。这样 SKILL.md 可以很短，真正复杂的图形逻辑在脚本里，token 开销也小。

4.4 验证与迭代

写完之后，我用三个真实任务做了回归测试：

• “画一个库存系统的模块图”
• “画一个用户登录的时序图”
• “画一个前后端分离架构图”

第一轮跑下来发现两个明显问题：一是 JSON 结构经常缺description字段，导致渲染出来的图只有标题没有说明；二是布局太简单，模块多了之后全部一行排下去，横向溢出。问题出在SKILL.md规则不够严格。我加了两条规则：所有节点必须包含 description；层内节点超过 4 个时自动换行。改完再跑，输出质量明显稳定了。

由此得到一个教训：skill 不是一次写好的，它和代码一样需要测试驱动迭代。保留一个“黄金测试集”，每次改完规则都重新跑一遍，你就能快速判断改动是变好还是变坏。

5. 常见问题与避坑记录

5.1 问题速查表

实际操作中一定会有各种意外，我整理了这段时间遇到的问题和解决方法，方便大家直接对号入座：

这些坑大部分来自对 skill 机制理解不深，不是模型能力问题。规则写得越精确，Agent 的表现越稳定。

5.2 几个真实踩坑心得

第一是 description 是命门。很多人写 SKILL.md 时把精力花在正文规则上，description 随便写两句，结果 Agent 压根不记得调用它。后来我把 description 改成了“生成系统架构图、模块关系图、服务依赖图，适用于技术方案设计、系统拆解、文档配图等场景”，命中率明显提升。

第二是规则宁少勿多。一开始我也会写一堆边界情况，结果 Agent 被规则绕晕，反而不知道该优先执行哪条。现在我的原则是：只保留 8-10 条核心规则，每一条都可以被明确检查。

第三是不要什么都塞给 skill。很多功能看起来能加，但加进去之后 skill 变得臃肿、难以调试。我给自己的标准是：一个 skill 只解决一类问题，如果另一个任务和画图关系不大，就单独建一个新的 skill，而不是强行合并。

第四是尽量通过脚本做强校验。规则写在 SKILL.md 里终归是软约束，加了 validate.py 之后，脚本会检查 JSON 结构是否合法，缺字段直接报错并让 Agent 修复，这个“闭环”机制让输出质量提升了一个档次。

5.3 怎么安全地获取和安装这类技能

鉴于这类项目很火，网上也出现了一些“原版”“无删减版”的网盘资源，我个人不建议碰。原因很简单：skill 本质是一段可执行指令加脚本，来源不明的东西你根本不知道里面写没写恶意操作。获取 skill 最好的路径是：GitHub 官方仓库、npm 包、以及官方 skill 市场。安装后打开 SKILL.md 快速扫一遍，确认没有可疑的“执行任意命令”“读取敏感文件”等描述再投入使用。

另外，凡是声称“破解版”“无删减版”的第三方包，务必直接忽略。开源项目本身就是要开放给所有人用的，不存在需要破解才能看的逻辑，这类标题基本是用来骗点击量的。

最后分享一点个人体会

这个 2.9 万 Star 的项目本身很简单，但它的价值在于给整个 Agent 生态指了一个方向：未来我们和 AI 协作，不再是一句 prompt 说遍天下，而是“为特定任务定义标准工作流”。diagram skill 只是第一个被我真正用起来的类型，但它让我理解了 skill、agent、工具脚本三者之间如何配合。

如果看完这篇文章你也想试试，我建议不要只停留在下载安装，动手做一个自己工作流里需要的小 skill，哪怕只做一件事。真正跑通一遍之后，你才会明白为什么这个看似普通的画图技能能收获那么多 Star——不是因为它花了多少巧妙心思，而是因为它真的改变了人和机器协作干活的方式。