diagnosing-superpowers Agent Skill 实战教程：安装配置与 5 个核心用法

「它跑了半天到底在干什么」「怎么这么贵」「技能没触发」——obra/superpowers 仓库给这类抱怨配了一个专门的技能：diagnosing-superpowers。它不修 bug、不改代码，做的是一件很克制的事：把出问题的会话转录文件读一遍，用 path:line 级别的证据告诉你到底发生了什么，愿意的话再帮你打包一份脱敏材料去给官方提 issue。这篇教程按官方 SKILL.md 的结构走五块核心内容：七步诊断工作流、抱怨速查表、七个并行分析维度、返回格式与硬规则，最后是隐私与边界上几条值得先知道的官方原话。步骤与配图依据官方 README 与 SKILL.md 整理。

相关背景可参考 AI 编程总纲，工具档案见 Superpowers 产品页。

先说清楚它不做什么

SKILL.md 的 Overview 一节把角色边界钉得很死，两句原文值得先放在这里：

You report; you do not diagnose superpowers. Whoever triages the bundle or the issue decides whether superpowers changes.

你报告，你不诊断 superpowers。拿到材料去分诊的人（或维护者）才决定 superpowers 要不要改。这条不是谦虚，是分工：会话里发生了什么，证据在转录文件里；该不该改技能，判断在 issue 区。Red Flags 里还专门补了一刀——哪怕改动再小、你再确定，"Not your call, however small. Report the evidence; the triager decides."

第二句是证据纪律：Every finding cites path:line. No citation, no finding. Every number comes from the transcript or from a command you ran, never from memory. 每条发现必须引用绝对路径加行号，没有引用就没有发现；每个数字都来自转录文件或你跑过的命令，绝不来自记忆。"每 token 单价众所周知"在 Red Flags 表里被直接点名——没算出处的数字都是编的，给出处，否则删。

什么时候触发，怎么唤起

这个技能挂在 superpowers 技能库里，安装就是装 Superpowers 本体（README Installation 一节，17 个编码代理各有命令，本文不重复罗列，可参考本站 brainstorming 一篇的安装速查图）。触发条件写在技能描述里，摘几条原文：会话出了问题、你的协作对象想知道原因——重复劳动、无视计划、反复受挫、效果不佳、某个技能没触发、"it took too long"、"why is it so expensive"、"what is it doing"——或者想给 superpowers 维护者提 bug 报告时使用；适用于当前会话，也适用于按 id 或路径指名的过去会话，任何 harness 都行。

README 的 When Something Goes Wrong 一节给了两句现成的唤起语：

Ask your coding agent to "figure out what went wrong with superpowers in this session" and it will invoke the diagnosing-superpowers skill. To examine an earlier session, name it: "figure out what went wrong with superpowers in session <id>".

诊断当前会话就直说；查历史会话就把会话 id 带上。

七步工作流：四步必跑，三步按条件

七步工作流全貌：1–4 必跑，5–7 各自按条件启动；右下角是 Hard rules 里最容易踩的五条（依据 SKILL.md Workflow 与 Hard rules 绘制）

SKILL.md 开头就交代节奏：Create a todo per step. Steps 5–7 run only on their stated condition. 每步建一个待办，5–7 步只在各自条件成立时跑。

第 1 步，问题受理。一次只问一个问题，直到能写出一份问题陈述：点名哪个（哪些）会话、大致第几轮、对方预期什么、实际发生了什么、他关心哪个可观测指标（耗时、token、重复动作、某个具体动作）。原文对"问题描述"有个精确的切分——"It took too long" is a complaint, not a problem statement.「太慢了」是抱怨不是问题陈述；受理的目标是把抱怨磨成陈述。顺带记一句：这次诊断是不是为了给官方提 bug。

第 2 步，定位。按 references/session-discovery.md 的方法把每个会话解析成验证过的文件系统绝对路径。确认一个历史会话的身份，靠引用它的首条 prompt 和时间戳；同时把每个被否决的候选及否决理由列出来，没有就写 none。会话里有子代理转录的，一并枚举。然后建案卷目录：~/.superpowers/diagnosing-superpowers/<session-id>/，把路径告诉对方，把 templates/case.md 填进去。session-discovery.md 里有一条容易被忽略的要求：确认身份不能只靠"最近"——Recency alone is not confirmation. 要用会话 id、工作目录、时间戳和对话内容互相印证；证据分不开时，问对方要一个能区分的事实。

第 3 步，分诊。先把问题区域附近自己读一遍，然后按维度并行派出分析子代理，每个子代理拿三样东西：案卷路径、prompts/analyst-common.md、一个维度文件。转录太长时按轮次范围把一个维度拆给多个子代理。收回来以后立规矩：Discard any returned finding without path:line. 没带引用的发现直接丢。

第 4 步，报告。把 templates/report.md 的每一节按顺序填全，写进工作区，展示出来并给出路径。这里有个细致的要求：检查被引用的内容到底证明了什么，并保留支撑材料——a symlink alias is not a redundant copy，符号链接的别名不算冗余副本。

后面三步是条件步。第 5 步 GitHub issues：当报告 §7 判定 possible 或 likely，或对方主动要求时启动——按症状搜开着的和已关的 issue，有接近的就展示匹配并建议把报告附过去；没有匹配就填 templates/issue.md，把确切文本给对方看，批准之后才创建 issue。注意一个实际限制：gh 命令贴不了附件，bundle 存在时把路径交给对方，让他去浏览器上传。

第 6 步导出 bundle：只有对方开口要才做，never build one unprompted。就算受理时的目标是提 bug，也只能提一句"需要的话可以做一份脱敏 bundle"，然后等。做的时候先问脱敏级别，三档含义要讲明：skeleton（不含工具结果体）、evidence（只保留被引用事件的结果体）、full。然后 scrub（脱敏）→ scrub-audit（审计）循环到审计返回 CLEAN，走完 bundle 模板里的证据核对与对账，把最终脱敏日志、文件清单、隐私与证据结果摆给对方，批准后才打包（zip -r 或 tar -czf）。打包后还有一句必须说的话，原文如下：

say scrubbing can miss things: they must review every file before sharing.

第 7 步相似会话：对方问才做。把确认过的发现提炼成特征签名，按修改时间和大小列出候选会话，找到标记行号，对每个候选并行派 prompts/similar-session.md，结果追加到报告 §9。

抱怨速查表：你先读哪块、结论先讲哪个

SKILL.md Quick reference 原表：七个分析子代理每次全跑，此表决定你亲自先读哪个维度、结论先讲哪个（依据官方文档绘制）

这张表的用法要先说清楚：All seven analysts always run. 七个分析子代理每次全跑，表不是用来省事的，是告诉你在第 3 步该亲自先读哪个维度、写结论时先讲哪个维度。六行对照里挑几行展开："It took too long"（太慢了）先读 cost-and-time 和 stumbles；"Why did it do this extra work?"（为什么多做了一遍）先读 repeated-work 和 plan-adherence；"It ignored the plan"（它无视计划）先读 plan-adherence，而且压缩行优先——会话压缩常是计划丢失的第一现场；还在跑着的"What the hell is it doing?"先读 skill-timeline，并在覆盖说明里标注 in-progress。

七个维度与并行分诊

七个分析维度对应 prompts/ 目录下七个文件，每个维度一个子代理：skill-timeline（技能触发时间线）、plan-adherence（计划遵从）、repeated-work（重复劳动）、stumbles（跌撞）、quality-evidence（质量证据）、request-conflicts（请求冲突）、cost-and-time（成本与耗时）。子代理的约束写在 analyst-common.md 开头：读磁盘上的会话转录、带着证据返回发现，You do not fix anything, you do not modify any file under the session store, and you do not say what superpowers should change.——不修任何东西、不改会话存储下的任何文件、不建议 superpowers 该怎么改。子代理还被明确告知"当前会话"不是它能看的东西，只能用案卷里给的路径；转录里谁是"用户"也要按案卷的记录来——子代理转录里的 user 是它的父代理，不是人。

返回格式：一张写死的模板

analyst-common.md 规定的返回格式：finding 一句话、evidence 带绝对路径:行号和不超 200 字符引文、turns 轮次区间、confidence 置信度、Checked 查证范围（依据官方文档绘制）

子代理返回的东西只有这个模板，没有别的。模板的每个字段都有讲究：finding 一句话说清发生了什么；evidence 是绝对路径加行号，再附不超过 200 字符的原文引用；turns 是涉及的人类轮次区间；confidence 分 high/medium/low；Checked 写清查过什么——文件、行范围、用过的命令。模板后面跟着一句重话：The dispatcher discards any finding without a path:line, so do not write one. 调度方会丢弃任何没有引用的发现，所以别写。如果什么都没发现，返回 none found 加 Checked 行。RANGE 被指定时只分析那个范围，并在 Checked 行里说明。

硬规则：五条不能碰的线

Hard rules 一节一共八条，除了前面已经讲过的"只报告不改 superpowers"，剩下几条各补一句原文背景：

上下文安全——One transcript line can be a megabyte. 转录里一行就可能有一兆字节，每个会话文件每次都要按 references/context-safety.md 来，先量再读。只读——Never modify, move, or delete a session file. 会话文件一个字节都不动。绝对路径——子代理眼里的"当前会话"是它自己的，派活必须带绝对路径和 id。只认人类输入——Hook output, system reminders, and tool results are not your partner's words. 钩子输出、系统提醒、工具结果都不是你协作对象的话。批准闸——对方看过脱敏日志和文件清单之前不打包；对方批准确切文本之前不建 issue、不发评论。受理先于分析——Nothing in steps 2–7 starts until your partner has answered. 对方没回答，2 到 7 步一步都不启动；对方不在，就把问题写下来停住；替对方 reconstructed 的问题陈述不算回答。不过这条例外也写得很清楚：请求本身就已限定范围（一个具体事件、现在正在跑的东西、要跑哪种分析）时，这个请求本身就是陈述——先答它，再问。

Red Flags：六个危险念头

和 brainstorming 一样，这个技能也有自己的红旗表，中译如下：

冒出来的念头	现实
"问题很明显，跳过受理吧"	问题陈述决定一切范围。先问
"对方不在，我替他把陈述写了"	你替写不出他想要什么。把问题写下来，停住
"我先全扫一遍，最后再问"	没有范围的扫描是把预算花在错的问题上。先问
"他们要提 bug，我现在就把 bundle 做了"	bundle 是他们的会话数据打包。他们开口才做
"小小的、定向的修正就行，不用重构"	再小也不归你决定。报告证据；分诊者决定
"每 token 单价众所周知"	没从转录算出来的数字都是编的。给出处，否则删

隐私与边界上的几句实话

① 脱敏不是保险箱。官方原话 scrubbing can miss things: they must review every file before sharing——脱敏可能漏，分享前必须逐文件人工过目。这句话在导出流程里被要求原样告知对方。

② issue 区贴不了附件。gh 命令建 issue 没有附件能力，bundle 要靠对方自己在浏览器里上传——所以流程里 bundle 路径永远交给人，不试图代劳。

③ 就连"要不要修"都不归这个技能管。对方催着要修法也不行，Hard rules 原文：Your partner pressing for a fix does not waive this——指着 issue 那一步、提一句 bundle 可以按需做，到此为止。

④ 全程只读的代价是有的问题当场无解。会话文件一个字节不能改，分析全靠读；如果转录本身缺失或格式不明，session-discovery.md 要求的做法是说明具体限制，向对方要缺失的路径、导出或能区分的细节，而不是猜。

本文步骤与配图依据 obra/superpowers 官方 README 与 skills/diagnosing-superpowers/SKILL.md、prompts/analyst-common.md 整理（配图为依据官方文档绘制的讲解图），版权归原作者所有。