show-me 这个 Agent Skill解决的是一个特别实际的问题Coding Agent 把代码写出来了但你没看懂它也不主动讲。用过这类工具的人应该都有印象Agent 跑完之后丢给你几个文件改哪儿了、为什么这么改、运行逻辑是什么很多时候全要靠你自己去看 diff、追日志、翻上下文。show-me 想做的事情就是让 Coding Agent 不只交付代码还把代码“讲清楚”。标题里的 Matt Pocock 是 TypeScript 社区里比较受认可的技术人他平时分享的内容偏工程实战能被这样的人留意到说明 show-me 不是那种花哨的玩具而是确实解决了一个高频痛点。这个 Skill 的核心价值也不复杂给 Agent 加一个明确的技能让它在生成代码、修改代码、分析代码的时候同步输出结构化的代码讲解。你拿到的不再是一堆“无说明产物”而是一份能阅读、能审查、能交接的代码说明。下面按实际操作顺序拆一遍。先讲为什么需要它再讲怎么跑起来然后给具体场景、参数判断和排错顺序。1. show-me 解决的不是写代码而是“讲代码”这件事很多人第一次听到 Agent Skill会有一个疑问这和普通提示词有什么区别区别在于Skill 不是一次性写在对话框里的要求而是一套可以被 Agent 识别、加载并持续复用的能力描述。show-me 的本质就是把“讲代码”这个能力从随缘触发变成可复现的行为。1.1 Coding Agent 生成代码后最容易卡在哪一步我自己用 Coding Agent 做项目的体感是生成代码本身已经不是什么难事了真正消耗时间的环节是“理解 Agent 生成了什么”。比如我用 Agent 改一个服务端逻辑它返回了三个修改过的文件。表面上任务完成了但要接下去维护我至少需要知道这次修改的核心思路是什么。改动集中在哪些函数、哪些模块。为什么选择这种方式而不选另一种。改动之后对原有接口、配置、依赖有没有影响。如果我要 review应该先从哪个文件看起。没有这些信息时我就得自己打开 diff逐个文件对比再顺着函数调用关系往回推。代码量小还好一旦涉及跨模块改动这个成本会明显放大。尤其当 Agent 是自动跑完一轮任务后直接提交结果你连它的思考过程都看不到只能靠结果反推。show-me 这个 Skill 切入的点就在这个环节。它让 Agent 在完成代码任务之后多做一个动作用结构化的方式把代码讲给你听。不是简单贴一遍代码而是把代码背后的设计意图、执行流程、关键逻辑和潜在风险写清楚。1.2 show-me 的核心思路把讲解变成 Skill 的一部分要理解 show-me 为什么比“你直接告诉我改了什么”更靠谱得先理解 Agent Skill 的加载机制。普通的提示词是一次性的你这次说了Agent 这次照做下次不一定会主动做。而 Skill 是放在特定目录下的结构化文件Agent 在任务开始前或任务过程中可以自动识别、加载相关的 Skill。也就是说只要 show-me 被配置好Agent 在合适场景下会自动采用“展示和解释代码”的方式输出结果不再依赖你每次都重复要求。这里也顺便说一个常见误解Skill 和 Agent 到底什么关系。简单说Agent 是执行任务的智能体Skill 是它掌握的一项具体技能。一个 Agent 可以同时加载多个 Skill分别处理代码讲解、文件整理、测试生成、日志分析等任务。它们不是替代关系而是组合关系。show-me 属于代码讲解类 Skill它的侧重点不是“多写代码”而是“把已有的代码讲明白”。所以你会发现它特别适合三类场景代码审查、新成员学习、需求交接。这三类场景的共同特征是代码本身已经存在但人对代码的理解还不够充分。2. 在本地环境把 show-me 跑起来想用好 show-me第一步不是研究提示词技巧而是把它放到正确的目录结构里让 Agent 能发现它。2.1 前置条件Agent 客户端、Skill 目录、目标仓库运行 show-me 需要三个基本条件一个支持 Skill 机制的 Coding Agent 客户端例如 Cursor、Cline、Continue 或其他兼容方案。对应的 Skill 存放目录一般是项目内的.agent/skills/或用户级配置目录具体以你的工具为准。一个本地代码仓库用来实际触发代码讲解。这里要特别提醒不同客户端的 Skill 目录规范并不完全一致。有的客户端会自动扫描.cursor/skills有的会读取.claude/skills还有的会读取自定义目录。所以落地的时候第一步不是急着写 Skill 内容而是先确认你用的工具到底从哪个目录加载 Skill。我一般会先用一个最简单的 Skill 做探路比如只让它输出一行固定文字。如果 Agent 能在任务里自动带上那个输出说明目录和格式对了再换成 show-me 的内容。这个探路步骤看起来很笨但能省掉很多后续的一头雾水。2.2 安装和目录结构示例下面给一个通用示意不是所有工具都必须长这样但结构思路是通用的。你的项目/ .agent/ skills/ show-me/ SKILL.md scripts/ explain.pySKILL.md是这个 Skill 的描述文件里面写清楚这个技能什么时候用、要产生什么样的输出。scripts目录不是必须的但如果想让 Skill 支持更复杂的本地文件处理可以把辅助脚本放进去。一个最简SKILL.md的结构大致像下面这样我这里只给格式示意具体字段以你使用的客户端规范为准--- name: show-me description: 当用户需要理解、审查或交接现有代码时生成结构化代码讲解。 --- # show-me 目标把指定代码讲清楚。 输出结构 1. 代码解决的核心问题 2. 主要函数和执行流程 3. 关键代码片段讲解 4. 依赖、配置和运行条件 5. 潜在风险和注意点2.3 第一次跑通的最小配置第一次跑不建议直接扔一个几百行的大文件进去。我先说一个最小样例选一个单文件、函数数量少、逻辑独立的小工具函数比如一个日期格式化函数、一个文件重命名工具都可以。触发方式很简单在对话框里输入类似这样的话用 show-me 的格式解释一下 src/utils/formatDate.ts如果 Skill 配置正确Agent 会按SKILL.md里定义的输出结构来讲解而不是随口感叹一句“这个函数是把日期格式化”就结束。第一次跑通后你再去测试更复杂的场景讲解整个模块、对比一次改动的 diff、把一个长文件拆成多个部分分别解释。每轮都观察 Agent 有没有始终如一地遵守输出结构。如果输出时好时坏那大概率是SKILL.md的描述不够具体或者上下文太杂导致 Agent 偏离了技能。3. 单条提示词触发代码讲解很多人以为 show-me 这种 Skill 需要复杂的参数配置实际用起来并不是。它的大多数价值都可以靠一条高质量的提示词触发。3.1 最简单的触发方式在支持 Skill 的 Coding Agent 里你可以直接在对话里写请对 src/services/userService.ts 做一次 show-me。这里的关键点是“show-me”这个名称要能映射到你已经配置好的 Skill。映射机制依赖两样东西一是文件夹和文件名是否放在正确位置二是SKILL.md里的 name 字段是否准确。还有一种触发方式是让 Agent 判断当前场景需不需要讲代码。比如你对它说“我有点看不懂这个模块的实现逻辑”Agent 如果发现 show-me Skill 与当前需求高度匹配就可以自动加载它。这属于主动性触发对 Skill 描述的要求更高。我自己测试时发现描述里如果能写出具体场景词Agent 识别的准确率会明显提升。比如“代码审查”“交接给同事”“学习这个函数的实现”“梳理这个模块的调用关系”这些词比“帮我解释一下”更容易触发。3.2 分步骤讲解输出长什么样一次合格的 show-me 输出一般会长成下面这个骨架这个函数、模块或项目解决什么问题。主要入口在哪里调用链是怎么走的。核心代码分几段每一段在做什么。涉及哪些外部依赖、环境变量或配置文件。有哪些容易忽略的边界条件和潜在问题。举例来说如果让它解析一个数据处理函数它不会只告诉你“这个函数用 pandas 做了数据清洗”而是会说明输入数据长什么样先做了哪些格式校验中间用什么方法去重、补缺失值最后输出什么结构以及在哪一步可能因为数据类型不一致而报错。这种讲解方式最大的好处是让阅读者可以在不打开 IDE 的情况下先在脑子里过一遍完整流程。当你真正打开代码去 review 的时候你是带着预期去看的效率比逐行读源码高很多。3.3 源码文件、代码块和依赖说明怎么组织还有一点值得单独说show-me 输出的代码块不应该只是把源码复制一遍。好的做法是Agent 挑出关键片段在片段前后配上解释。比如def clean_data(df): # 这一步先丢弃全为空的行避免后续计算受空值影响 df df.dropna(howall) return df也就是说讲解的重点是“为什么写这段”和“这段做了什么”而不是重复展示完整代码。如果你发现 Agent 每次都把整个文件原文贴一遍、解释只有一两句说明它还没有真正理解 show-me 的用途你需要把SKILL.md里的输出规则写得更严格。依赖说明这块也容易被忽略。很多代码问题都出在环境上而不是逻辑上。所以我会让 show-me 每次讲解涉及运行环境的代码时都主动补充依赖版本、环境变量、端口配置等信息。不要只讲代码本身要讲代码能跑起来的条件。4. 实际场景审查、学习和交接show-me 真正跑起来之后你会发现它的用法不是单一的。它不是一个只能“解释代码”的小工具而是一个可以嵌入到工作流里的能力。4.1 场景一给不熟悉项目的同事讲代码团队里经常有这种时候一个老模块没人敢动因为写它的人早就离了职文档也缺。这时候找 Agent 做一次 show-me能快速生成一份结构化的模块说明。比较安全的做法是把模块下所有文件统一丢给 Agent让它在 show-me 框架下输出三样东西模块的职责边界。对外暴露的接口和调用方式。内部核心流程和异常处理链路。这份输出可以直接作为临时交接文档。它不是完美的官方文档但至少能帮新接手的人快速建立全局认识比对着代码干猜强得多。4.2 场景二Agent 生成代码后自己要审查我自己最常用的场景其实是在 Agent 完成修改之后。当 Agent 帮我改完一批代码我会追加一条要求现在对改动过的内容做一次 show-me重点讲清楚改了什么、为什么改、涉及哪些文件、有没有破坏原有行为。这一步非常有用。因为它相当于逼着 Agent 把自己的改动重新过一遍很多潜在问题在这一步会暴露出来。比如 Agent 发现某个变量在另一个分支没定义或者在重构时遗漏了某个引用。如果不做这一步你会直接把 Agent 的产出当成最终结果可能到了跑测试的时候才报错排查成本明显更高。4.3 场景三把长文件拆成可理解的模块还有一个比较进阶的用法让 show-me 把一个大文件拆成逻辑块逐个解释而不是一股脑输出。比如一个 800 行的配置文件或状态管理文件直接看会非常吃力。你可以对 Agent 说用 show-me 的方式读一下这个文件把它分成几个逻辑单元按单元解释并说明单元之间的联系。这样做之后大文件的复杂度就被拆开了。Agent 会先给出整体分层再进入细节。你会发现很多看起来很乱的文件其实可以拆出清晰的功能边界。这个用法对代码重构前的摸底尤其有效。不先把现有逻辑理清楚就动手重构很容易把原本能跑的功能改坏。4.4 场景四复盘一段踩过坑的代码还有一种场景是查问题。线上出了 bug代码定位到了但不理解为什么当初这么写。这时候可以让 Agent 用 show-me 的方式去推演这段代码的“历史逻辑”它原本想处理什么情况、在什么条件下会被触发、有没有可能在某些输入下行为异常。这不算官方还原只是基于代码本身的推理。但它可以给你提供一个初步分析方向帮你更快定位问题。等你自己验证一遍再决定是否信任这段分析。5. 关键参数和判断标准Skill 和普通提示词的差别在于Skill 是可以通过配置文件控制行为的。如果你想让 show-me 稳定输出高质量讲解就要把几个关键规则想清楚。5.1 讲解颗粒度简略、标准、详细不同场景对讲解的详细程度要求不一样。如果只是快速看一眼某个函数几百字的小说明就够如果是交接一个模块可能需要几千字的完整讲解。show-me 的配置里最好明确三个级别简略模式只讲核心逻辑适合快速定位。标准模式包含调用流程、关键代码、依赖条件适合日常 review。详细模式补充设计意图、边界条件、潜在风险和改动建议适合交接和复盘。你可以在提示词里显式指定级别也可以在SKILL.md里定义默认级别。我建议默认用标准模式因为它的输出长度和信息密度最适合大多数场景。5.2 输出结构先结论、再流程、再代码一个稳定的输出结构比话术更重要。show-me 的输出如果每次都保持一致你阅读的时候就不用重新适应格式。推荐的顺序是结论这段代码在做什么有没有明显问题。流程从入口到出口数据和控制流怎么走。代码挑重点片段附上解释。依赖用到什么库、配置、外部服务。风险边界条件、容易踩坑的点、可能升级的方向。这里有一个要点先给结论。如果 Agent 一上来就开始贴大段代码读者会失去方向。先告诉人“这个模块核心功能是完成数据校验存在一个并发安全问题”再展开细节阅读体验会好很多。5.3 质量判断能复现、能审查、能交接判断一次 show-me 是否合格我一般看三个标准能复现读完之后你能顺着讲解把代码的执行流程重新说出来。能审查你能根据讲解发现代码里潜在的问题或找到需要进一步验证的点。能交接你把这段讲解发给另一个不熟悉这个模块的人对方愿意用它作为入门材料。如果输出只做到了“能复现”但完全不能帮你找出问题那说明讲解还停留在表层。真正好的 show-me 输出一定不是纯捧场它会指出代码里不合理的点。这个能力不是硬加给 Agent 的而是通过SKILL.md里的“潜在风险”要求约束出来的。6. 常见问题排查顺序show-me 用起来不算复杂但也会遇到各种奇怪的情况。下面是一套我实测下来比较顺的排查顺序遇到问题时按这个顺序走大部分都能解决。6.1 没有触发 Skill现象你输入了 show-meAgent 却没有按 Skill 规则输出表现和普通问答没有区别。先不要怀疑工具坏了。优先级最高的是检查 Skill 目录位置是否匹配你的客户端规范。其次检查SKILL.md里的 name 和 description 是否清晰如果描述太泛Agent 可能识别不到。最后再确认你使用的客户端是否真的支持 Skill 自动加载有些客户端只在特定模式下启用。6.2 讲了但没讲透现象Agent 确实输出了讲解但全是“这个函数用于处理数据”这类空话没有深度。这多半是SKILL.md里的输出约束太少。可以增加硬性要求比如每一项讲解必须包含“输入是什么、输出是什么、哪些分支可能导致异常”。也可以用更具体的提示词比如要求它“先画出调用链再解释最后一个函数的内部实现”。如果你已经用了详细提示词但效果还是不好就看是不是上下文太长。上下文一长Agent 容易丢失早期约束。这时候把目标文件缩小范围一次只讲一个函数或一个文件。6.3 上下文太长或输出被截断现象讲解到一半就停了或者越到后面越模糊。长文件的讲解建议分成多轮进行。先让它给出文件结构总览再选核心部分逐段深入。不要试图一次性把一个大模块完整讲完。如果 Agent 客户端有 max tokens 限制可以把输出级别从“详细”降为“标准”。还可以让 Agent 把讲解结果写成 Markdown 文件存到指定目录避免对话窗口里的内容被覆盖。很多 Skill 脚本的用途就是这个不只是输出到对话里而是落盘成文档。6.4 文件路径和权限问题现象Agent 说找不到文件或读取文件时报权限错误。这个经常不是 Skill 本身的问题而是路径配置的问题。先确认你使用的是绝对路径还是相对路径再确认文件编码是不是 UTF-8最后看有没有换行符或空格导致的路径解析问题。这里有个通用经验如果报错信息指向的是文件系统不要急着改 Skill 配置先在命令行里测试一下文件到底能不能被正常读取。7. 使用边界和我的建议show-me 是一个好工具但它不是万能的。明确它的边界比盲目依赖它更重要。7.1 什么时候该用 show-me我建议在以下场景使用 show-me接手不熟悉的项目或模块。Agent 自动修改了多处代码需要做一次系统性检查。要把某段代码交接给其他同事前先整理一份讲解文档。学习一个开源项目或教程示例代码时让它辅助梳理逻辑。长时间没有维护的代码重新启用前先做一次摸底。这些场景的共同特点是人需要理解代码而代码本身已经存在。7.2 什么时候不该用如果你是熟悉这段代码的人只是临时想确认一个变量名直接用搜索或 grep 更快没必要让 Agent 跑一遍完整讲解。另外show-me 的定位是“讲解”不是“证明”。它生成的解释是模型推理出来的不一定代表代码的真实历史背景。尤其是涉及特殊业务规则、历史原因、迫不得已的兼容性处理时不能把 show-me 的解释当权威。还有一点如果需要讲解的代码里包含敏感信息比如密钥、内网地址、用户隐私数据要谨慎处理。不要直接把整个文件丢给线上 Agent先做脱敏或者把关键片段单独抽出来讲解。7.3 落地建议如果你准备在真实项目里用 show-me我个人建议按下面的顺序落地先在一个小项目上跑通确认 Skill 加载方式正确。再挑一天内自己实际写过的代码做讲解验证输出是否符合预期。然后把输出结构固定下来调整SKILL.md让格式稳定。最后再接入批量场景比如让 Agent 修改完多个文件后自动附带一次 show-me 说明。不要一开始就要求 Agent 每次输出都完美。Skill 需要调试就像代码需要调试一样。你可以把 show-me 理解成一个很小的“产品”先定义输出格式再不断根据质量反馈调整描述和约束。踩过几次之后我发现这类工具真正落地时最该关注的不是“Agent 能不能写代码”而是“Agent 写完代码之后你能不能接得住”。show-me 解决的就是这个“接得住”的问题。它把代码从一串难以阅读的文本变成了一份结构清晰、可以审查、可以交接的说明。只要把目录结构、Skill 描述、输出颗粒度和排查链路搞清楚了它在日常开发里的价值会很快体现出来。