又一个神级 Skill，让 AI 少写字、多画图

最近我的 Claude Code 装了一个叫 show-me 的 Skill，装完之后最大的感受是：终于不用在对话框里翻三屏找结论了。

这事儿说来有点讽刺。AI 编程助手的能力越来越强，但它们的"表达欲"也跟着膨胀。你问一个函数的调用关系，它能从项目背景讲到设计取舍，再讲到潜在风险，最后才在第三屏底部贴出那五行你真正想看的代码。内容没错，但阅读成本越来越高——大部分时候我直接拉到最底下，中间的解释全跳过。

show-me 这个 Skill 的出现，本质上是在解决一个问题： 当 AI 越来越聪明，我们怎么让它"说人话"——不，比说人话更进一步，让它"画人看得懂的图"。

但作为一个跟踪 AI 编程工具两年的编辑，我想说的不是"这个 Skill 真好用"这种肤浅的结论。真正值得聊的，是它背后折射出的几个技术趋势：Skill 机制是怎么工作的？为什么一份 100 多行的 Markdown 文件就能改变 AI 的输出行为？以及，"可视化表达"在 Agent 工作流里到底处于什么位置？

一、show-me 到底是什么？先破除一个误解

很多人第一次听说 show-me ，以为它是一个独立的可视化工具，或者是一个 Mermaid 渲染插件。都不是。

它本质上是一份 SKILL.md 文件，放在 humanlayer/skills 这个开源仓库里，MIT 协议，目前 4k+ Star。整个文件也就一百多行，里面没有一行代码教你"怎么画图"——它写的全是 输出规范 。

什么意思？就是告诉 AI：当用户问你逻辑流程的时候，别写大段文字，用伪代码；问调用关系的时候，画成树状缩进；问交互过程的时候，输出 Mermaid 时序图；问改动对比的时候，用 diff 格式。

这里面的技术关键点在于： Skill 不是给 AI 增加新能力，而是约束它的表达能力。

这和我们平时用的 CLAUDE.md 有什么区别？区别很大。Claude Code 的文档里说得清楚，CLAUDE.md 是在每次会话开始时加载的持久化指令，相当于项目的"家规"；而 Skill 是 按需加载 的——只有当你调用 /show-me 或者 AI 判断当前场景适合用这个 Skill 时，它的内容才会被塞进上下文。

这个设计很巧妙。如果你把"画图规范"直接写进 CLAUDE.md，等于每次对话都要为这几百字的指令买单，占用宝贵的上下文窗口。Skill 机制把它拆成了可插拔的模块，用的时候才加载，不用的时候零成本。

二、拆开 SKILL.md：一份"表达规范"文件的技术结构

我把 show-me 的 SKILL.md 完整读了一遍。它的结构其实很有代表性，值得拆开来看。

文件开头是标准的 YAML Frontmatter：

---name: show-medescription: A skill for compact visual representations...---

这两个字段不是摆设。Claude Code 会根据 description 来判断什么时候自动触发这个 Skill。如果你没手动打 /show-me ，但你的提问里包含了"内容太多了，给我看"这种语义，AI 会自己把这份规范加载进来。

后面的正文部分，就是具体的表达规范。我挑几个最有技术含量的说：

1. 伪代码替代自然语言描述

这是我最喜欢的一条。比如一个保存操作：内容没变就返回缓存，变了就写入新内容。用文字讲要两三句话，还可能带一堆"如果...那么..."的嵌套。伪代码四行：

if content_unchanged:return cacheelse: write_new_content

这里面的技术考量是： 结构化文本的信息密度远高于自然语言。 伪代码消除了自然语言的歧义性，同时保留了代码的精确性。对于已经会读代码的程序员来说，扫一眼伪代码的理解速度，比读一段英文描述快一个数量级。

这个做法的源头是工程师 Dillon Mulroy，他在 X 上分享过自己用"伪代码 + 调用栈"来写技术方案的习惯。 show-me 的作者 Dex Horthy 直接把这个模式收进了 Skill 规范里。

2. 调用关系树：缩进即层级

谁调用了谁，一层一层往下缩进排列。这个形式看似简单，但解决了一个很实际的问题： 在复杂代码库里，函数的调用链往往跨越多个文件，IDE 的调用图要么太细（把每一层框架封装都展开），要么太粗（只显示直接调用）。

show-me 规定的调用树格式，只保留"业务意义"上的层级，省略掉中间层的框架噪音。而且它要求把文件路径标在节点旁边，这样你一眼就能定位到代码位置。

3. Mermaid 时序图：交互过程的可视化

多方参与的交互过程，比如用户点击按钮 → 前端发请求 → 后台处理 → 流式返回结果，用文字描述很容易写成"然后...然后..."的流水账，时间线和阻塞关系都混在一起。

Mermaid 时序图的语法很简洁：

但这里有个技术细节要注意： 图能不能直接在对话界面里渲染出来，取决于你用的工具支不支持 Mermaid。 Claude Code 本身不渲染 Mermaid，它输出的是纯文本语法。你要么复制到飞书文档、Notion 或者 mermaid.live 里看，要么借助其他 Skill（比如配合 MCP Playwright）来生成 SVG/PNG。

这也是 show-me 和市面上那些专门的 Mermaid Skill（比如 mermaid-diagram-specialist 、 pretty-mermaid-skills ）的区别：后者更关注"怎么生成语法正确的 Mermaid 代码"和"怎么渲染成图片"，而 show-me 关注的是"什么时候该用图，用什么图"。

4. Diff 格式：改动对比的终极形态

两个方案摆在面前，AI 各写一大段优缺点，读完还是不知道差在哪。 show-me 的规定是：直接输出 diff。

// 方案A+ file_a.ts (修改)+ file_b.ts (新增)- file_c.ts (删除)// 方案B+ file_a.ts (重构)+ file_d.ts (新增)+ file_e.ts (新增)

这个格式的技术价值在于： diff 是一种"增量信息"的表达方式。 它只展示变化点，不重复展示不变的部分，天然符合程序员 Review Code 时的认知习惯。而且 diff 的语义是精确的——"新增三行"和"修改一个函数"在 diff 里有完全不同的表示，不会引起歧义。

5. HTML 讲解页：当图也讲不清的时候

Skill 文件里还有一条兜底策略：如果文字、伪代码、Mermaid 图都讲不清，就让 AI 生成一个独立的 HTML 文件，把内容拆成几块，配上交互式图表，双击用浏览器打开。

这个思路来自 TypeScript 社区的 Matt Pocock，他之前做过一个叫 /teach 的 Skill，专门生成 HTML 讲解页。Dex Horthy 在博客里专门致谢了他。

HumanLayer 团队自己说，他们内部做原型的时候，HTML 页面已经很大程度上替代了 Figma。这不是夸张——对于一个需要快速验证概念的技术团队来说，让 AI 生成一个可交互的 HTML 原型，比打开设计工具画 Mockup 快得多。

三、为什么一份 Markdown 文件就能改变 AI 的行为？

这可能是很多人困惑的地方：LLM 不是本来就会写 Mermaid 吗？训练数据里到处都是 Mermaid 语法，为什么还要专门装一个 Skill？

答案是： LLM 会写 Mermaid，但它不知道什么时候该写，以及该写成什么样。

这涉及到当前 AI 编程助手的两个核心机制：

机制一：系统提示词（System Prompt）的优先级

Claude Code、Cursor、Codex 这些工具，在每次调用模型时都会拼接一个系统提示词。这个提示词里包含了工具的定义、可用技能、当前项目上下文等等。Skill 文件的内容，就是被动态注入到系统提示词里的。

当 show-me 被加载后，它的规范会出现在系统提示词的"技能"部分。模型在生成回答时，会同时参考：

1. 用户的原始问题

2. 系统提示词里的全局约束（CLAUDE.md）

3. 当前激活的 Skill 规范（show-me）

Skill 规范的作用，相当于在模型输出之前加了一层 表达过滤器 ："在满足用户问题的前提下，优先选择以下表达形式..."

机制二：In-Context Learning 的触发条件

大模型的 In-Context Learning（上下文学习）能力，指的是它能在 Prompt 里看到示例后，模仿示例的风格和格式输出。Skill 文件里的那些"伪代码示例""调用树示例""diff 示例"，本质上就是在给模型提供 少样本提示（Few-Shot Prompting） 。

但这里有个关键细节：这些示例不是教模型"怎么写代码"，而是教它"怎么组织信息"。模型看到"调用关系用缩进树"的示例后，它会把这个模式泛化到新的场景——即使它从来没见过这个具体的函数调用链，它也知道该用缩进树来呈现。

这也是为什么 show-me 不需要写复杂的代码逻辑，只需要写清楚"什么场景用什么格式"，模型就能自动适配。

四、Skill 生态：从"重复粘贴提示词"到"可复用的行为封装"

show-me 的流行，不是孤例。这半年类似的 Skill 出来不少：管代码评审的、管需求追问的、管文档风格的、管测试策略的。HumanLayer 的 skills 仓库里一共放了五个，除了 show-me ，还有 improve-claude-md 、 narrow-react-prop-types 、 build-iterated-agentic-loop 、 design-control-loop 。

这些 Skill 的共同点是： 它们把人的工作习惯写成了文件，让 AI 照着来。

在 Skill 机制出现之前，开发者是怎么解决这个问题的？要么每次对话开头粘贴一段"请用伪代码回答"的提示词，要么在 CLAUDE.md 里写一大段全局约束。前者烦，后者贵（占上下文）。

Skill 机制的出现，相当于给 AI 编程助手引入了一种 模块化的行为配置系统 。你可以把它理解为 IDE 的插件：需要画图的时候装 show-me ，需要做代码评审的时候装 code-review ，需要生成架构图的时候装 mermaid-diagram-specialist 。每个 Skill 只在自己的领域生效，互不干扰。

Anthropic 官方对 Skill 的定位也很明确：当你发现自己在反复粘贴同样的指令、检查清单或多步骤流程时，就该把它做成 Skill。

这背后有一个更大的趋势： AI 编程工具的进化，正在从"模型能力竞赛"转向"工程化封装竞赛"。

模型本身的能力（代码生成、逻辑推理）在快速提升，但"怎么把模型的能力稳定地输出成人类需要的形式"这件事，还没有被很好地解决。Skill 机制就是在填补这个 gap。它不关心模型能不能写出正确的代码，它关心的是： 模型写出的代码，能不能以最高效的方式被人类消费。

五、安装与使用：没什么门槛，但有两个坑

安装很简单，一行命令：

npx skills add humanlayer/skills --skill show-me

装完之后，在对话里输 /show-me ，或者直接说"内容太多了，给我看"，它就会切换成可视化模式。想要 HTML 讲解页，就补一句 as an html explainer 。

但用了一段时间后，我发现有两个坑值得提醒：

坑一：图是 AI 画的，但 AI 也会画错

尤其是面对小众框架或者复杂业务逻辑时，组件树可能漏掉关键模块，调用树可能编出不存在的调用关系。Mermaid 语法本身是对的，图也能渲染出来，但图里的内容可能是幻觉。

我的做法是： 先看图了解大概结构，具体细节回到代码里核实。 图的价值是建立认知框架，不是替代代码阅读。

坑二：它只管表达形式，不管方案质量

这是最关键的一点。 show-me 能让一个烂方案看起来很漂亮——伪代码写得工整，时序图画得规范，diff 对比清晰。但方案本身靠不住的话，图只是给错误信息包了一层好看的皮。

Reddit 前 CEO 之前公开吐槽过 Claude 的说话风格，说怎么纠正都纠正不过来。Dex Horthy 做 show-me 的初衷，就是解决这种"表达失控"的问题。

但表达规范只能解决"怎么说"，不能解决"说什么"。如果你问了一个错误的问题，或者 AI 给了一个错误的方案， show-me 只会让它错误得更漂亮。

六、Skill 文件本身：为什么它值得读一遍

最后说一个很多人忽略的点： show-me 的 SKILL.md 文件本身，就是一份极好的 Prompt Engineering 教材。

它只有一百多行，但里面体现了很多高级技巧：

• 场景化触发 ：不是笼统地说"多画图"，而是列举了七八种具体场景，每种场景对应一种表达形式。

• 约束的层次性 ：从"优先用伪代码"到"实在不行就生成 HTML"，有一个清晰的优先级 fallback 链。

• 少样本示例 ：每种表达形式都带了具体例子，模型可以直接模仿。

• 兜底策略 ：最后加了一条总约束——"挑最小的那个视图，把关键点说清楚就行，别堆砌"。

这些技巧放在任何 Prompt Engineering 的场景里都适用。哪怕你不用 Claude Code，只是用 ChatGPT 或者 Claude Web 版，把这些规范改写成系统提示词，效果也一样好。

而且因为它是 MIT 协议的开源文件，谁都能读，谁都能改。我们团队已经基于它改了一版内部版本，加了我们自己的代码风格规范和架构图模板。一百多行 Markdown，改起来比改 IDE 插件简单多了。

结语

show-me 火起来，不是因为它做了什么惊天动地的技术创新。恰恰相反，它做的事情很朴素：把"怎么让 AI 说人话"这个问题，工程化成了一份可复用的配置文件。

但朴素不代表没有价值。在 AI 编程助手的能力已经过剩的今天， "怎么让 AI 的输出被人类高效消费" 正在成为新的瓶颈。模型在榜单上越来越聪明，但用起来有个明显退步的地方，就是表达——Dex Horthy 这句话，说到了点子上。

Skill 机制的出现，给了我们一个杠杆：不需要重新训练模型，不需要写复杂的插件，只需要一份写清楚规范的 Markdown 文件，就能让 AI 的输出质量上一个台阶。

从这个角度看， show-me 不只是一个"让 AI 少写字"的 Skill，它代表了一种新的交互范式： 人类不再被动接受 AI 的表达方式，而是主动定义"我想要的信息形态"。

这口锅，可能比龙虾那口更实用。

（本文技术细节参考了 humanlayer/skills 开源仓库、Claude Code 官方文档、Dex Horthy 博客及 Hacker News 讨论。如有疏漏，欢迎指正。）