最近和不少做 AI 编程落地的同学交流时一个高频痛点反复出现Coding Agent 生成代码的速度越来越快但生成的代码越来越“难看懂”。AI 可以几分钟改完十几个文件可是 review 的时候人还得一行一行去猜它的意图。更尴尬的是让 Agent 自己解释代码时它往往只会输出一大段文字逻辑讲得没错但读起来累、记不住、也不好评审。这个问题的解法之一就是今天要聊的 Agent Skillshow-me。它让 Coding Agent 从“只会说”变成“会画、会展示、会一步步讲清楚”。就连 TypeScript 社区里以严谨著称的开发者 Matt Pocock 都公开点赞过这类技能的设计思路。本文将围绕 show-me 展开先讲清楚 Agent Skill 到底是什么再带大家从零安装、配置一个可用的 show-me 技能最后用一个“快速排序代码可视化讲解”的完整案例演示 Coding Agent 如何把代码讲清楚。文章适合以下读者正在使用 Claude Code、Cursor 等 Coding Agent 的开发者想把 AI 生成的代码更好地纳入代码评审流程的团队用 AI 辅助教学、写技术文档、做代码讲解的内容创作者对 Agent Skill、MCP、提示词工程概念还比较模糊的新手。读完本文你将掌握 Agent Skill 的核心原理、show-me 的安装与调用方式以及一套可以复用的“让 Agent 可视化讲解代码”的提示词模板。1. 为什么 Coding Agent 需要“把代码讲清楚”1.1 AI 编程的下一道门槛不是生成而是理解过去两年AI 编程经历了三个阶段的变化代码补全阶段你写一半AI 帮你补完主动权在人对话生成阶段你描述需求AI 返回一段代码主动权开始转移Coding Agent 阶段你给出任务AI 自主读仓库、改多个文件、运行测试、修复报错主动权基本在 Agent 手里。到了第三阶段问题就变了。以前代码是 AI 的“建议”你看了、改了、才合入现在是 AI 直接完成一个完整功能你只能“事后审查”。但审查的前提是理解而理解恰恰是当前 Coding Agent 输出最薄弱的环节。举个常见场景Agent 为了实现一个功能顺手重构了一个工具函数、调整了依赖注入方式、改了数据库连接池参数。它完成任务了但你拿着 diff 时脑子是懵的为什么要改这里这个递归为什么不会爆栈这个异步处理的顺序是不是有问题这条链路画成图是什么样子如果 Agent 只能输出文字说明很多信息是丢失的。比如“这个函数先递归处理左子树再处理右子树然后合并结果”这句话你听懂了但真要你在脑海里构建调用栈还是很费劲。1.2 常见的代码讲解方式对比目前 Coding Agent 讲解代码大致有三种方式讲解方式优点缺点纯文本注释式生成快、直接长文本阅读成本高复杂逻辑难理解Markdown 文档式结构清晰可归档静态文字无法展示动态调用过程可视化展示式直观、便于评审与教学需要额外技能支持模型要能生成 HTML/SVG前两种是 Agent 的“默认能力”第三种就是 show-me 这类 Agent Skill 要解决的问题。之所以强调“可视化”是因为代码本质上是一个动态过程函数调用、数据流转、递归回溯、并发时序这些都不适合用静态文字描述。而 HTML 页面天然支持“步骤条”“高亮”“折叠”“点击交互”非常适合把代码逻辑拆解成一个可交互的讲解页面。1.3 show-me 是什么一个被社区认可的 Agent Skillshow-me 并不是一个特定的编程框架而是一类 Agent Skill 的典型代表。它的核心目标很简单当用户希望“理解代码”时Agent 不只是用文字解释而是生成一个完整的可视化展示页面把代码逻辑、数据流向、调用关系、关键步骤都画出来。这类技能之所以被广泛讨论是因为它刚好补齐了 Coding Agent 的短板对开发者review AI 代码时先看可视化讲解再逐行看代码对团队可以生成一份带图的技术说明沉淀到知识库对教学场景把算法、设计模式、框架源码讲给学生看。Matt Pocock 在社区里推荐这类技能时核心观点也在于此Coding Agent 的价值不只是“写代码”而是“把写代码的思路讲清楚”。当 Agent 能把自己的决策过程视觉化开发者对 AI 产出的信任度会明显提升。2. Agent Skill 原理Skill 与 Coding Agent 是如何配合的2.1 什么是 Agent Skill要理解 show-me必须先理解 Agent Skill。Agent Skill技能包是给 Coding Agent 准备的一组“能力插件”。它通常是一个目录里面包含一个 SKILL.md 主文件描述这个技能的名称、适用场景、执行步骤若干辅助脚本、模板、样式资源。当 Agent 遇到与技能描述匹配的任务时会自动读取 SKILL.md按照里面的指令执行。你可以把 Skill 理解为“给 Agent 的一本操作手册”它告诉 Agent什么情况下应该使用这个能力使用这个能力时按照什么步骤来做最终应该输出什么格式的结果。show-me 就是这样一个技能包它的 SKILL.md 会告诉 Agent“当用户需要理解代码时不要只写文字应该生成一个 HTML 可视化讲解页面并把代码逻辑拆成步骤”。2.2 Skill 与 Agent、MCP、Prompt 的区别很多人第一次接触 Agent Skill 时会把它和 Agent、MCP、Prompt 混在一起。这里做一个简单区分概念作用类比Agent能自主规划、调用工具、执行任务的智能体员工Prompt当前任务的指令和上下文给员工的任务单Skill可复用的专业知识与操作流程员工的操作手册MCP连接外部系统和数据的标准协议员工使用的外部系统接口具体来说Prompt 是一次性的Skill 是可复用的Skill 是给 Agent 补充“怎么做事”的知识而 MCP 是给 Agent 补充“能访问什么外部资源”的能力同一个 Agent 可以挂载多个 Skill比如 PDF 编辑技能、PPT 生成技能、show-me 可视化讲解技能。所以问题“Agent 做项目是不是需要很多个 Skill”答案是不需要盲目堆砌。每个 Skill 只解决一个特定环节的问题按项目实际需要挂载即可。show-me 解决的是“代码讲解”这个环节不负责帮你写业务代码。2.3 Skill 的加载与执行流程虽然不同 Coding Agent 对 Skill 的加载细节有差异但整体流程是相似的Agent 启动后扫描个人级和项目级 Skill 目录读取每个 Skill 的 SKILL.md理解技能名称和适用场景当用户请求与某个 Skill 的 description 匹配时Agent 自动加载该技能用户也可以在对话中显式引用某个 Skill要求 Agent 必须使用它Agent 按照 SKILL.md 中的步骤执行输出规定格式的结果。用一句话概括Skill 让 Agent 从“凭感觉发挥”变成“按规范执行”。show-me 的价值正在于把“讲解代码”这件事规范化、流程化、视觉化。3. 环境准备安装 Coding Agent 与 show-me Skill3.1 环境选择与版本说明show-me 是运行在 Coding Agent 之上的技能所以第一步是准备一个支持 Skill 机制的 Coding Agent。目前比较主流的选择包括Claude Code对 Agent Skill 支持较早技能目录规范也比较清晰Cursor 等 IDE 类 AI 编程工具也在逐步支持技能/规则体系其他兼容 Agent Skill 规范的工具越来越多的开源 Agent 框架开始支持类似能力。不同工具的安装方式差异较大这里不做展开重点以 Skill 目录的通用规范为例。版本方面需要说明Agent 工具迭代很快不同版本对 Skill 的支持程度不同本文示例以当前主流实现为例重点是思路具体路径请以你所使用工具的官方文档为准。3.2 Skill 目录规范与安装方式目前常见的 Agent Skill 目录规范有两种个人级目录对所有项目生效通常位于用户主目录下项目级目录只对当前项目生效适合团队协作时随仓库一起提交。以 Claude Code 风格的目录为例show-me 技能可以放在以下两个位置之一# 个人级推荐自己日常使用 ~/.claude/skills/show-me/ # 项目级推荐随项目提交团队共享 {项目根目录}/.claude/skills/show-me/show-me 技能的目录结构通常如下show-me/ ├── SKILL.md ├── scripts/ │ └── render_template.py └── assets/ └── style.css安装方式有两种方式一从社区仓库克隆或下载后复制到技能目录。# 假设你已经 clone 了包含 show-me 技能的仓库 mkdir -p ~/.claude/skills cp -r ./show-me ~/.claude/skills/方式二手动创建目录和文件。这种方式适合你想自定义技能行为的情况。mkdir -p ~/.claude/skills/show-me touch ~/.claude/skills/show-me/SKILL.md安装完成后可以检查一下目录结构是否完整ls -la ~/.claude/skills/show-me/3.3 编写一个最小可用的 SKILL.md如果社区版本不能满足你的需求你也可以自己写一个精简版 show-me。SKILL.md 的核心是三部分技能元信息、适用场景、执行步骤。下面是一个最小示例--- name: show-me description: 当用户需要理解代码、查看代码逻辑、评审代码或教学讲解时使用本技能生成可视化讲解内容。 --- # show-me ## 适用场景 - 用户说“帮我讲一下这段代码” - 用户要求生成代码流程图、时序图、调用关系图 - 用户需要 review 代码时希望先看可视化说明 ## 执行步骤 1. 阅读用户提供的代码识别核心函数与调用关系。 2. 将代码逻辑拆解为若干步骤。 3. 生成一个自包含的 HTML 文件包含 - 代码结构总览 - 核心函数说明 - 每一步的代码高亮与解释 - 一张用 HTML/CSS 绘制的逻辑示意图 4. 将 HTML 文件保存到输出目录并告诉用户打开方式。这里的关键是“description”Agent 主要靠它判断什么时候加载这个技能。所以描述要写清楚触发场景越具体越容易被正确唤起。4. show-me 的核心能力拆解4.1 能力一生成可视化 HTML 页面show-me 最核心的能力是把代码逻辑转换成一份自包含的 HTML 讲解页面。所谓“自包含”指所有样式、脚本都内联在一个 HTML 文件里用户保存后用浏览器打开即可不需要启动服务器也不依赖外部 CDN。一个典型的 show-me 输出页面会包含以下区块!DOCTYPE html html langzh-CN head meta charsetUTF-8 title快速排序可视化讲解/title style /* 内联样式步骤条、代码高亮、示意图 */ /style /head body h1快速排序代码讲解/h1 div classstep-bar span classstep active1. 选择基准值/span span classstep2. 分区/span span classstep3. 递归排序/span span classstep4. 合并结果/span /div div classcode-block !-- 每行代码对应解释 -- /div script // 内联脚本点击步骤切换高亮 /script /body /html上面这一段只是结构示意。实际生成的页面会根据代码复杂程度自动扩展。对开发者来说这种“步骤条 代码高亮 对应解释”的排版比一大段文字更容易定位问题。4.2 能力二分步骤讲解代码逻辑show-me 的第二个能力是把一个完整函数拆成“能讲给学生听”的步骤。好的代码讲解是有顺序的先讲整体目标这段代码要解决什么问题再讲数据入口输入是什么输出是什么然后按执行顺序拆步骤每一步做了什么为什么这么做最后讲边界情况空输入、重复数据、性能退化。show-me 的 SKILL.md 会要求 Agent 按照这个思路组织输出而不是想到哪讲到哪。这一点非常重要因为 Coding Agent 默认的讲解往往是从第一行按顺序解释到最后一行这对读者很不友好。4.3 能力三辅助代码评审与教学除了“讲代码”show-me 还可以用于代码评审和教学评审场景Agent 生成可视化 diff 说明标注每个文件改了什么、影响面在哪教学场景把算法、设计模式、框架源码生成图文并茂的讲义文档场景直接把可视化页面作为技术文档附件沉淀到团队知识库。这也是 show-me 被很多开发者推荐的核心原因它把 Agent 从“代码生成器”变成了“代码讲解员”。4.4 show-me 的边界与限制show-me 也不是万能的使用前需要了解它的边界它擅长解释“逻辑性强的代码”但不太适合解释“依赖大量外部上下文”的业务系统生成的 HTML 是静态页面无法实时读取数据库或调用后端接口复杂项目的全量代码不适合一次性交给它解释容易超出上下文窗口可视化是“辅助理解”不能替代代码本身更不代表代码没有 bug。理解了这些边界我们在实际使用时就能有的放矢。5. 完整实战让 Agent 用 show-me 讲清楚快速排序下面我们走一遍完整流程。示例选择快速排序因为递归 分区的过程特别适合可视化讲解而且代码短大家都能看懂。5.1 准备示例代码我们先准备一段待讲解的 Python 快速排序代码保存为 quick_sort.pydef quick_sort(arr): if len(arr) 1: return arr pivot arr[len(arr) // 2] left [x for x in arr if x pivot] middle [x for x in arr if x pivot] right [x for x in arr if x pivot] return quick_sort(left) middle quick_sort(right) if __name__ __main__: data [3, 6, 8, 10, 1, 2, 1] print(quick_sort(data))这段代码的逻辑是如果数组长度小于等于 1直接返回取中间元素作为基准值 pivot把数组分成小于、等于、大于 pivot 三部分递归排序左右两部分再合并。对新手来说“递归 分区”两个概念叠在一起光靠文字很难建立直觉。这正是 show-me 的用武之地。5.2 编写提示词在 Coding Agent 对话框中输入以下提示词请使用 show-me 技能讲解下面的 Python 快速排序代码。 文件quick_sort.py 代码 def quick_sort(arr): if len(arr) 1: return arr pivot arr[len(arr) // 2] left [x for x in arr if x pivot] middle [x for x in arr if x pivot] right [x for x in arr if x pivot] return quick_sort(left) middle quick_sort(right) 要求 1. 生成一个自包含的 HTML 可视化讲解页面 2. 用步骤条展示排序的完整过程 3. 对每一行关键代码给出通俗解释 4. 用你熟悉的示例数据 [3, 6, 8, 10, 1, 2, 1] 演示分区过程 5. 页面保存为 quick_sort_visual.html。这里有两个关键点明确点出“使用 show-me 技能”让 Agent 优先加载技能给出具体的输出要求包括文件格式、内容结构、保存路径。提示词越具体输出越可控。5.3 预期输出与运行验证Agent 执行后会在当前目录或指定输出目录生成一个 quick_sort_visual.html 文件。页面大致包含标题快速排序可视化讲解步骤条选择基准值 → 分区 → 递归左半部分 → 递归右半部分 → 合并结果代码区每行代码旁边标注解释演示区以 [3, 6, 8, 10, 1, 2, 1] 为例展示每一轮分区的结果边界说明空数组、只有一个元素、全是相同元素的处理。打开方式很简单# 在项目目录下启动临时静态服务 python3 -m http.server 8080 # 或直接用浏览器打开本地文件 open quick_sort_visual.html如果是远程服务器环境没有浏览器也可以用 curl 检查文件是否生成成功curl -I http://localhost:8080/quick_sort_visual.html预期返回 HTTP 200说明文件可以正常访问。5.4 扩展讲解任意代码的通用 Prompt 模板上面的流程不限于快速排序。你可以把提示词抽象成模板讲解任意代码请使用 show-me 技能讲解以下代码。 文件__文件名__ 代码 __粘贴代码__ 要求 1. 生成一个自包含的 HTML 可视化讲解页面保存为 __输出文件名__.html 2. 先讲整体目标再按执行顺序拆步骤 3. 每个关键代码段配一行通俗解释 4. 标注边界条件和潜在风险 5. 页面适合开发者快速 review 和新人学习。模板中的占位符替换成实际内容即可。建议一次只讲解一个文件或一个函数保证讲解深度。6. 常见问题与排查思路6.1 高频问题排查表根据实际使用反馈show-me 最常见的问题集中在“技能没生效”“输出不符合预期”“页面打不开”三类。我用表格整理了一份排查清单问题现象常见原因解决思路Agent 没有生成可视化页面只输出文字没有加载 show-me 技能提示词未显式引用技能在提示词中明确写上“使用 show-me 技能”检查技能目录技能目录存在但 Agent 不识别SKILL.md 的 frontmatter 格式不对description 描述不清晰检查 name/description 字段description 写清楚触发场景生成的 HTML 页面样式错乱页面依赖了外部 CDN 资源浏览器限制本地文件加载外部资源要求生成“自包含”页面所有 CSS/JS 内联页面打开是空白浏览器阻止了本地 JS 脚本脚本报错用浏览器开发者工具查看 Console 报错检查脚本代码讲解内容太浅只解释语法提示词没有要求拆解执行过程在提示词中加入“先讲目标再按执行顺序拆步骤”一次讲解多个文件上下文不够代码量超出模型上下文窗口拆文件讲解先让 Agent 汇总调用关系再逐个深挖Agent 忽略了技能仍然自由发挥技能的 description 与当前任务匹配度不够调整 SKILL.md 的 description使用“必须使用”等强约束表达6.2 典型报错与修复示例我挑两个最常见的报错场景演示排查过程。场景一技能目录放错位置。现象Agent 完全感知不到 show-me 技能。排查步骤# 1. 确认技能目录是否存在 ls -la ~/.claude/skills/ # 2. 确认目录名和 SKILL.md 是否在正确位置 tree ~/.claude/skills/show-me/ # 3. 确认 SKILL.md 不是空文件 cat ~/.claude/skills/show-me/SKILL.md如果目录不存在重新创建如果目录存在但 SKILL.md 为空补充技能内容。场景二提示词没有触发技能。现象Agent 回答了但只是普通文字没有生成 HTML。原因通常有两种一是提示词里没有出现技能名称Agent 没有把任务与技能关联起来二是 SKILL.md 中 description 写得过于笼统Agent 判断“当前任务不需要技能”。解决方案在提示词中显式引用技能并给出强约束请使用 show-me 技能必须生成 HTML 可视化页面不要只输出文字。这种写法可以大幅提高技能触发率。7. 最佳实践与工程建议7.1 用好 show-me 的提示词技巧结合实战经验我总结了五个技巧区分“讲解型提问”和“实现型提问”。想让 Agent 讲代码就在提问时明确说“讲解”“解释”“可视化”而不是“帮我改一下”。一次只讲一个核心函数。贪多嚼不烂一个页面塞太多内容讲解深度必然下降。给 Agent 指定读者。告诉它“面向刚入门的开发者”或“面向有经验的评审人员”讲解口径完全不同。显式指定输出格式。说明要生成 HTML、保存为什么文件名、是否要内联样式避免 Agent 自由发挥。多轮追问。先让 Agent 生成总览页面再针对某一轮分区追问“这里为什么选择中间元素作为基准值”可以逐步深入。7.2 Skill 与代码评审流程结合show-me 在团队协作中的最佳落点是接入代码评审流程。推荐流程如下Agent 完成功能开发后先要求它用 show-me 生成变更可视化说明开发者在看 diff 之前先看可视化说明建立整体认知带着可视化说明逐文件 review重点关注说明与实际代码不一致的地方把最终确认过的可视化页面归档到团队知识库作为该模块的技术说明。这样做有两个好处一是提高评审效率二是把 AI 的决策过程沉淀成团队资产。特别是对于“Agent 独立完成的功能”可视化说明几乎是唯一能快速理解 Agent 意图的途径。7.3 安全、性能与可维护性最后是工程上必须注意的几点安全边界show-me 生成的是静态 HTML但它可能包含内联脚本。如果要把生成的页面分享给他人建议先检查脚本内容避免被注入恶意代码。不要直接打开来源不明的生成文件。路径规范建议统一输出目录例如每个项目下建一个 docs/visual/ 目录避免 HTML 文件散落在各处。版本管理show-me 技能本身也要纳入版本管理。项目级技能目录随仓库提交保证团队所有人使用同一套讲解规范。性能控制不要试图一次把整个项目塞给 Agent 做可视化。先让 Agent 生成调用关系总览再局部深入能有效控制上下文消耗。本地优先如果涉及敏感代码务必使用本地部署的模型或本地运行的工具链不要把核心代码发送到外部服务。8. 总结与学习路线本文围绕 show-me 这个 Agent Skill讲清楚了以下几个关键点Coding Agent 的瓶颈已经从“生成代码”转移到“讲清代码”Agent Skill 是一组可复用的“操作手册”它让 Agent 的行为更规范show-me 通过生成自包含的 HTML 可视化页面把代码讲解从“文字模式”升级为“可视化模式”安装 Skill 的关键是目录位置和 SKILL.md 的 description 设计使用 show-me 的关键是提示词要显式触发、明确输出要求、分块讲解。如果你正在使用 Coding Agent下一步可以这样练习找一个你熟悉的小算法比如二分查找或链表反转让 Agent 用 show-me 讲解对比“没有技能”和“使用技能”两种输出感受差异把 show-me 接入团队评审流程观察 review 效率变化尝试自己写一个自定义 Skill比如“把 Java 代码转成时序图说明”理解 Skill 的通用原理。AI 编程工具的竞争最终会从“谁能写出更多代码”转向“谁能把代码讲得更清楚”。show-me 只是这个方向上的一个起点但它背后“让 Agent 为人类降低理解成本”的思路值得每个 AI 编程实践者认真对待。如果这篇文章对你有帮助建议收藏备用后续我会继续更新 Agent Skill 的更多实战案例。