最近一段时间Coding Agent 的发展速度远超很多人的预期。OpenAI 的 Codex、Anthropic 的 Claude Code、Google 的 Jules再加上国内厂商陆续跟进的各种 Coding Agent几乎每周都有新能力放出。但如果你真的在项目里重度使用过这些 Agent会发现一个很普遍的体验落差Agent 写代码的速度确实快但它解释代码的能力远远跟不上它写代码的速度。什么意思当你让 Agent 改一个模块它噼里啪啦生成一大段 diff当你问它“这段逻辑是怎么跑起来的”它给你输出一大段 Markdown 文字当你想让它解释某个复杂的调用链它往往只会用文字复述代码而不是画一张图让你一眼看懂。结果就是你 review 得仍然很累。所以我开始关注一个叫show-me的 Agent Skill它在 TypeScript 社区引起了挺多讨论连 Matt Pocock 这样级别的开发者都公开评价过。这篇文章我会从“为什么要给 Coding Agent 配一个讲解型 Skill”这个角度切入把 show-me 的作用、安装方式、实际用法、和普通 Prompt 的区别以及它的适用边界一次性讲清楚。1. show-me 到底是什么它解决了什么问题先给一个明确判断show-me 不是一个新的 Coding Agent也不是一个代码解释器而是一个“技能包”Skill用来让 Coding Agent 把抽象代码逻辑变成可视化图表。它解决的核心问题可以概括成一句代码是给人读的但人读代码的效率远远低于人看图。传统开发里我们要理解一段陌生代码通常有几个办法直接读源码一行一行跟下来。在 IDE 里打断点Debug 看调用栈。用 PlantUML、Mermaid 或者 draw.io 手动画图。把代码丢给 ChatGPT让它用文字解释。这四个办法各有利弊。读源码效率最低但最准确打断点适合定位问题但不适合理解全局手动画图清晰但维护成本高让 AI 文字解释方便但 AI 的文字往往和代码一样长你还是得花时间看。show-me 的思路不一样它让 Coding Agent 在解释代码时不只是输出文字而是基于 Mermaid 或 ASCII 图把类关系、调用链、数据流、时序过程直接画出来。相当于把“代码讲解员”这个能力做成了 Agent 的一项可复用技能。为什么这个方向很关键因为 Claude Code、Codex 这类 Agent 本身有很强的代码理解能力它们完全能分析出代码结构但默认情况下它们倾向于用文字回答。文字回答不是不好而是处理复杂结构时信息密度太低。有了 show-me 之后Agent 的输出形式从“散文”变成了“图说明”代码 review 和理解成本明显下降。1.1 Skill 和 Agent 的区别很多人其实没搞懂在继续往下讲之前我想先花点篇幅把Agent Skill这个概念说清楚因为我在很多技术讨论里看到有人把 Skill 和 Agent 混为一谈。先说 Agent它通常指一个具备自主规划、工具调用、记忆能力的执行体。它可以自己拆解任务、调用工具、执行命令、根据结果调整下一步。Coding Agent 就是以写代码为目标的 Agent。Skill 则完全不是这个层面的东西。你可以把 Skill 理解为 Agent 的“外挂能力包”或“专项操作手册”。它由一组指令、技能描述、优秀示例文件组成Agent 在遇到符合触发条件的任务时会加载 Skill 对应的内容从而知道自己应该用什么方式处理任务。举一个容易理解的类比Agent 就像一个经验丰富的工程师。Skill 像工程师手里的一本“专项工作手册”。Agent 可以没有手册工作但有了手册它在特定场景下会更规范、更高效。所以 show-me 作为 Skill它不会替换你的 Coding Agent也不会改变 Agent 写代码的能力。它做的是当 Agent 需要解释代码时告诉它“你该用图表形式输出而且你有现成的 Mermaid 模板可以用”。这是两者最本质的区别。1.2 Matt Pocock 为什么认可这个方向Matt Pocock 是 TypeScript 社区非常知名的开发者他做类型体操教程和各类前端工具测评在开发者群体里影响力很大。他公开提过 show-me 这个 Skill 后GitHub 上的讨论热度确实涨了一波。从我的观察来看他认可 show-me 的核心原因不只是“画图功能好用”而是这个方向代表了一种趋势在 Agent 时代开发者的核心技能正在从“会写代码”转向“会审查代码”。Agent 帮你把代码写出来了但代码是否可靠、是否优雅、是否有潜在 bug仍然需要人去判断。而判断的前提是理解理解的前提是高效的信息呈现。show-me 恰恰在这个环节上做了增量它不是在帮 Agent 写更多代码而是在帮 Agent 把代码“讲清楚”。2. show-me 的核心能力拆解show-me 的能力范围可以拆成三大类结构可视化、流程可视化和时序可视化。2.1 结构可视化这类图用来展示“代码里有哪些东西它们之间是什么关系”。典型场景某个模块包含哪些类、接口、函数。类的继承关系。目录结构和模块边界。类型定义和引用关系。在没有 show-me 之前你要理解一个项目的模块结构通常得逐个文件读或者靠 IDE 的大纲视图。有了 Agent 加 show-me 之后你可以直接对 Agent 说请用 show-me 帮我画出 src/modules/user 下面所有类的继承关系和依赖关系。Agent 会分析代码结构然后生成一张 Mermaid classDiagram你可以直接贴到 Markdown 里渲染看效果。2.2 流程可视化这一类针对的是业务逻辑比如一个请求从进来到返回经历了哪些中间件。一个订单状态机有多少个状态状态之间有哪些流转条件。一段遍历数据、过滤、映射、归约的管道操作。某个算法的主流程和分支条件。流程可视化特别适合 review 业务代码。因为业务代码往往函数很长分支很多光靠眼睛看很容易漏掉边界条件。把它画成 flowchart 之后Review 效率会高很多。2.3 时序可视化时序图适合展示跨模块、跨系统的交互过程。典型场景前端调后端接口后端调第三方服务三方之间怎么交互。数据库事务里多个表之间的读写顺序。微服务架构里一个请求在多个服务之间的调用链。Mermaid 的 sequenceDiagram 可以比较直观地表达这类动态交互。show-me 会让 Agent 在讲解调用链时优先输出这种图而不是大段文字描述。2.4 讲解策略先图后文show-me 的核心设计哲学是“先图后文”。在很多普通 Prompt 里让 Agent 解释代码它可能直接开始列要点结构比较散。而 show-me 会让 Agent 遵循一套更优的输出顺序用图表输出整体结构。用简短文字标注关键节点。最后列出容易踩坑的边界条件。这套流程很像一个有经验的技术专家在给你做 Code Review先让你看全局再聚焦到关键点最后补充风险提示。3. 环境准备与前置条件在开始安装和使用这个 Skill 之前先确认你的环境满足下面这些条件。操作系统方面Windows、macOS、Linux 理论上都可以但如果你用的是 Windows建议把 Shell 环境切到 Git Bash 或者 WSL避免 .sh 脚本执行遇到权限问题。因为这个 Skill 涉及 Shell 脚本Windows 的 CMD 和 PowerShell 处理起来体验不太好。Coding Agent 方面这个 Skill 的定位是让 Coding Agent 使用所以你需要先安装一款支持 Agent 机制的 AI 编程工具。比较常见的选择包括 Claude Code、Codex CLI 等。需要注意具体 Agent 的安装和 API Key 配置方式不同版本之间差异较大请务必以对应工具的官方文档为准这里不会给出某个特定版本的安装命令避免误导你。Node.js 环境也需要检查一下。因为你会用到 Node 的调试工具来获取执行上下文Node 版本建议在 18 以上。你可以用下面的命令检查版本node -v npm -v如果本机还没有 Node.js可以到 Node 官网下载 LTS 版本安装。版本这方面本文重点演示通用思路具体版本号不用死抠。在代码库准备方面建议你先建一个测试项目验证效果而不要一上来就直接在核心生产项目里使用。你可以用这个命令创建一个简单的测试目录mkdir -p ~/show-me-demo/src cd ~/show-me-demo npm init -y4. 安装 Agent Skill 并配置 show-me4.1 理解 Skill 的目录结构要正确安装一个 Skill首先要知道 Agent 加载 Skill 的机制。以典型的 Agent 框架为例Skills 通常约定放在一个特定目录下每个 Skill 拥有一个独立子目录里面有一个SKILL.md文件作为入口来描述这个 Skill 的功能和用法。一个典型的结构大致如下~/.claude/skills/ └── show-me/ ├── SKILL.md └── scripts/ └── generate-diagram.js其中SKILL.md是核心文件。Agent 在对话中判断当前任务匹配 Skill 能力时会读取这个文件然后按照里面的指引去执行。4.2 获取 show-me 的 Skill 文件show-me 作为一个开源 Skill一般通过 Git 克隆的方式分发。你可以在终端执行git clone show-me的仓库地址 ~/.claude/skills/show-me这里有个地方要提醒一下由于 Skill 的仓库地址会因为作者维护而发生变化最稳妥的方式是去 GitHub 上搜索show-me相关仓库找到你使用的 Agent 对应的版本再克隆。不要盲目复制网上散落的旧命令。克隆完成后检查目录结构是否正确ls -la ~/.claude/skills/show-me cat ~/.claude/skills/show-me/SKILL.md如果能正常看到SKILL.md的内容说明 Skill 已经就位。4.3 权限设置如果你使用的是类 Unix 系统Skill 里的脚本可能需要执行权限。执行chmod x ~/.claude/skills/show-me/scripts/*.sh chmod x ~/.claude/skills/show-me/scripts/*.js这一步很容易被忽略但它直接影响后续能否正常调用。4.4 验证 Skill 是否被 Agent 加载启动 Coding Agent输入类似这样的 Prompt请列出当前可用的技能列表不同 Agent 的返回格式不一样但关键在于如果 show-me 已经被正确安装Agent 会列出或者提到 show-me 这个 Skill。如果没有出现检查你放 Skill 的目录是否是你所用 Agent 默认读取的路径。5. 使用 show-me 的完整示例让你的 Agent 把代码讲清楚这一节的核心是实际操作。我们通过三个示例覆盖 show-me 最常见的三种场景类结构、业务流程图、时序图。5.1 示例一讲解类继承关系我们先写一段带有继承关系的 TypeScript 代码。文件路径src/animal.tsabstract class Animal { name: string; constructor(name: string) { this.name name; } abstract speak(): string; } class Dog extends Animal { speak(): string { return Woof; } } class Cat extends Animal { speak(): string { return Meow; } } class Zoo { animals: Animal[] []; addAnimal(animal: Animal): void { this.animals.push(animal); } allSpeak(): string[] { return this.animals.map((animal) animal.speak()); } }然后你在 Agent 对话窗口里输入请用 show-me 讲解 src/animal.ts 的类结构和调用关系。show-me 的 Skill 会让 Agent 优先输出 Mermaid 图它大概是下面这种形式mermaid classDiagram class Animal { string name speak() string } class Dog { speak() string } class Cat { speak() string } class Zoo { Animal[] animals addAnimal(animal) void allSpeak() string[] } Animal |-- Dog Animal |-- Cat Zoo o-- Animal你把这段 Markdown 贴到支持 Mermaid 渲染的编辑器里就能看到 Animal 作为抽象基类、Dog 和 Cat 继承自它、Zoo 组合了 Animal 的清晰结构。 这里有一个值得注意的细节show-me 不只是画图Agent 还会在图的后面追加对关键逻辑的说明比如多态的调用关系、为什么 Zoo 依赖抽象类而不是具体类等等。 ### 5.2 示例二讲解订单状态机 业务代码里状态机是最适合用图来表达的。 文件路径src/order.ts typescript type OrderStatus pending | paid | shipped | completed | cancelled; function transitionOrder(from: OrderStatus, action: string): OrderStatus { switch (from) { case pending: if (action pay) return paid; if (action cancel) return cancelled; break; case paid: if (action ship) return shipped; if (action refund) return cancelled; break; case shipped: if (action complete) return completed; if (action return) return cancelled; break; } throw new Error(Invalid transition from ${from} with action ${action}); }输入 Prompt请用 show-me 把 src/order.ts 的状态流转画出来并标出每个状态之间的触发条件。Agent 生成的结果会包含一个 flowchart表达状态之间的流转关系。这类图一旦画出来你就能马上发现一个问题如果订单已经 completed还能不能取消从代码看completed 之后没有任何操作入口一旦到了终态就结束了。这种边界情况用文字描述容易被忽略但看图一眼就能发现。5.3 示例三讲解跨模块调用链第三个场景我们看一个简单的数据获取链路。文件路径src/api.tsimport { fetchUserProfile } from ./http; import { formatUser } from ./formatter; import { cacheUser } from ./cache; export async function loadUser(userId: string) { const cached await cacheUser.get(userId); if (cached) { return cached; } const raw await fetchUserProfile(userId); const formatted formatUser(raw); await cacheUser.set(userId, formatted); return formatted; }输入 Prompt用 show-me 画出 loadUser 函数的时序图包括缓存、HTTP 请求、格式化三个模块的交互顺序。Agent 会生成一个 sequenceDiagram表达loadUser - cache - http - formatter - cache - loadUser的调用链。这样你很快就能知道查询缓存是第一步miss 之后才会发 HTTP返回前会写缓存。整个逻辑链路非常清楚。6. 运行结果与效果验证使用上面示例中的代码show-me 的正常输出应该遵循“图 注解 风险点”的结构。你可以这样判断是否成功Agent 是否输出了 Mermaid 代码块而不是只有纯文字。代码块的标签是否为mermaid。图的内容是否与代码逻辑一致。是否在图的上下文中给出补充说明而不是只画完图就结束。如果你是在支持的 Markdown 编辑器中阅读比如 Typora、Obsidian、JetBrains IDER 的 Markdown 预览或者直接在支持 Mermaid 渲染的代码托管平台提交就能看到渲染后的图形。如果 Agent 没有输出图而是直接用文字回答一般有三个原因Skill 没有被正确加载Agent 根本不认识 show-me。你使用的 Agent 工具对 Mermaid 格式的输出不支持。对话窗口里没有明确说“请用 show-me”Agent 没有触发这个技能。判断核心show-me 不是让 Agent 自己知道什么时候该画图而是要求你在关键 Prompt 里主动声明使用 show-me。7. 常见问题与排查思路show-me 本身不复杂但在实际使用中确实有几个高频问题值得单独列出来。| 问题现象 | 可能原因 | 排查方式 | 解决方案 | | --- | --- | --- | --- | | Agent 不认识 show-me | Skill 未安装到正确目录 | 检查 SKILL.md 是否存在确认 Agent 的 Skills 目录路径 | 把 Skill 目录放到 Agent 默认读取位置 | | 生成了文字但没生成图 | Prompt 里没有触发 show-me | 回顾输入看是否明确包含“用 show-me”短语 | 在 Prompt 中显式声明使用 show-me | | Mermaid 渲染乱码 | 缩进或特殊字符问题 | 把 Agent 生成的 Mermaid 单独复制到在线渲染器验证 | 检查中文字符是否需要转义 | | 图过小或节点太多 | 一次传入的代码范围太大 | 缩小到单个文件或单一函数 | 分模块画图不要一次画整个项目 | | 脚本执行没有权限 | 没有 chmod 脚本 | 查看脚本执行报错日志 | chmod x 对应脚本 | | Agent 画出的图和代码逻辑不一致 | Agent 的上下文理解偏差 | 截图或复制关键代码重新描述你的需求 | 在 Prompt 里限定只分析指定文件不要让它猜测 | | 代码路径很长Agent 不识别行号 | 语言模型对行号依赖差异大 | 指定文件路径和函数名 | 减少对行号的依赖多用函数名作为锚点 |其中最容易踩的坑是Mermaid 里的中文转义问题。如果流程图的节点里有中文或特殊符号偶尔会出现渲染失败。我的习惯是尽量用英文或简短驼峰命名作为节点标签中文说明写在图后面的文字里。另外一点如果你发现 Agent 画的图过于复杂不要把整个项目一次丢给它应该拆分模块逐个分析。否则 Skill 的作用会被稀释从“辅助理解”变成“生成一张谁也看不懂的大图”。8. 最佳实践什么时候该用 show-me什么时候不该用show-me 是一个很实用的 Skill但它并不是万能的。结合我在项目里的使用习惯给你一些边界建议。8.1 推荐使用场景第一代码 Review 阶段。尤其是接手别人写的模块时用 show-me 画出模块结构和核心调用链可以大幅缩短理解时间。第二写技术方案文档时。你可以用 show-me 生成架构图配合 Mermaid 直接嵌入 Markdown 文档比手动画图快很多。第三定位复杂 bug 的时候。如果 bug 和调用链有关先让 Agent 画出时序图再沿着图的路线排查。第四教新人理解项目时。与其带人逐行读代码不如先给一张结构图再由人解释细节。学习效率会好很多。8.2 谨慎使用或不要使用的场景第一当代码逻辑非常简单时不需要 show-me。只有几行代码直接读就行画图反而增加成本。第二当结果依赖大量运行时状态时看图和看代码一样困难。show-me 是静态分析器它读的是代码文本不包含运行时内存状态所以它对 bug 的排查更多是辅助作用。第三非常前沿或小众的代码库。如果 Agent 对框架本身不熟画出的图很可能是错的。这时要用文字 Prompt 严格控制分析范围。第四不能渲染 Mermaid 的环境。Mermaid 还需要不支持的话转成 ASCII 图。如果你的 Agent 输出不了 Mermaid 渲染你依然可以把 Mermaid 代码复制到支持渲染的工具里看。8.3 对常见 Agent 工作流的建议如果你使用的 Coding Agent 支持 YAML 或者 Markdown 形式的 Skill 定义那么 show-me 的核心理念也可以迁移到其他工具上。也就是说你不需要把 show-me 当作一个黑盒完全可以根据自己项目的特点定制一个自己的“show-me”变体修改输出模板、设置默认图表语言、甚至加上你的项目专用图例约定。这种自己造 Skill 的玩法其实比直接用 show-me 本身更有价值。它说明你已经从“会提问”进阶到了“会定义 Agent 的行为规范”。9. 结语Agent 时代的新分工与新型开发者能力回到开头那个问题Coding Agent 已经很能写了那我们的关键短板在哪里我的答案是理解和审查。Agent 能生成代码但代码是否符合业务预期、是否覆盖边界条件、是否容易被后面的人维护这些都还需要人来把关。而这个“把关”的基础是快速准确地理解代码。show-me 这类 Agent Skill 的真正价值不在于画图这个动作本身而在于它把 Agent 从“代码生产机器”变成“代码讲解助手”。它让我们看到了一条路开发者不用亲自读每一行代码但依然能对代码建立了然于胸的结构感。如果你正好在用 Coding Agent 写项目哪怕不打算安装这个 Skill也建议你了解一下 Agent Skill 这套机制试着把自己的常用指令沉淀成 Skill。这是 Agent 时代比较值得养成的工程习惯也是能降低团队协作成本的一个方向。你可以先建一个测试项目把 show-me 跑通然后用它画几张图比较一下“纯文字解释”和“图文字解释”的差异。如果你手里也有那种几十个类互相调用的老模块这个 Skill 很可能会帮你省下不少理解成本。