来自
@humanlayer_dev
团队
@dexhorthy
，教 Agent 用简洁的图示、代码形态草图和单点聚焦的 HTML 页面，让用户直观看懂当前讨论的话题。
https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md
核心指令三句话：
· 跳过铺垫，文字尽量短
· 帮用户"看见"当前话题
· 选择能把关键点讲清楚的最小视图
它解决的真实问题
Agent 解释代码时的默认习惯是大段散文：先复述问题、再分点阐述、最后总结。这种输出信息密度低，且难以校验。但工程师真正想看的往往是"结构"——调用顺序、组件嵌套、文件归属、前后差异。这些内容天然适合用树、图、diff 表达。show-me 把这种"用形状说话"的直觉固化为一套可复用的选择规则。
八种视图和适用边界
Skill 的主体是一张"话题类型 → 表达形式"的映射表，每种形式都给了一个精简样例。理解这份 Skill 的关键在于看清每种形式回答的是什么问题：
1. 伪代码（text）- 逻辑怎么走？
适用于：算法、条件分支、缓存策略
2. 调用树 - 运行时谁调了谁？
适用于：排查一次请求的执行链路
3. 组件树（tsx） - UI 由什么组成？状态挂在哪？
适用于：React/前端结构，含文件路径与模块边界
4. 浅层文件树 - 哪个目录负责什么？
适用于：大型重构、职责划分
5. Mermaid - 多个参与者之间怎么交互？
适用于：前后端、进程间、数据流
6. diff - 相对现状变了什么？
适用于：变更提案、代码评审
7. 完整代码块 - 目标形态是什么？
适用于：用户需要直接复制的实现
8. 独立 HTML 文件 - 太密、太视觉化，其他形式装不下
适用于：布局对比、状态机、信息图、短幻灯片
对 diff 的特别强调
Skill 中篇幅最多的部分是 diff，而且它提出了一个不常见的要求：diff 的形状要匹配话题的形状。
传统 diff 只作用于源代码。但这份 Skill 给出了四种非代码 diff：
· 组件树 diff：+ <RunSkillButton /> 插入到现有 JSX 层级中
· 文件树 diff：- transport.ts → + transport/ 目录拆分
· 调用树 diff：在调用栈里 + expandSkillMention，把 navigateToSession 下挂新的子调用
· 控制流 diff：伪代码里 - write content 替换为带缓存判断的分支
这个思路的价值在于：用户讨论到哪个抽象层，diff 就在哪个抽象层呈现。讨论架构时不需要看到具体函数体的变化，讨论调用链时不需要看到文件移动。这比"直接贴源代码 diff"精确得多。
HTML 兜底形式的约束
当 Mermaid 装不下时，Skill 允许写一个独立 HTML 文件，但附带了几条硬约束：
· 一个文件只讲一个点（"one focused HTML file"）
· 视觉要贴合被讨论产品的配色、字体、间距、组件——不是通用模板
· 用真实的标签和数据，不用占位符
· 同时适配桌面与移动端
· 生成后用 open 命令直接打开，不让用户自己找文件
收尾的三条元规则
Skill 末尾的 guidance 段是整份文档的"约束器"，防止前面的工具箱被滥用：
1. 视图紧贴文字。 每个视图放在它所支撑的短文本旁边，而不是集中堆在末尾。
2. 只保留必要元素。 调用、文件、props、状态、边界——凡是与用户当前问题或当前讨论点的候选方案无关的，一律裁掉。
3. 少即是多。 "可能用一种，可能用几种，不太可能全用。用判断力，不要淹没用户。"