安装此技能
npx skills@latest add mattpocock/skills --skill=research 然后在你的编码 agent 里输入 /research 。
本页目录
它做什么
research 通过阅读拥有答案的那些来源来回答一个问题，然后在仓库里留下一份带引用的 Markdown 文件。它只从**一手来源（primary source）**工作：官方文档、源代码、规范、第一方 API。它把每一条主张都追溯到拥有它的来源，所以当 API 自己的文档可以访问时，它不会复述一篇博客文章对那个 API 的说法。
它不会在对话里回答你。输出是一个文件，写在仓库已经存放这类笔记的地方，每条主张上都带一个链接。你得到的是一份可以据以反应、可以交给另一个 agent、也可以扔掉的文档，而不是一个在会话（session）结束时就不见了的答案。
什么时候用它
输入 /research，或者当一个任务变成阅读类的跑腿活时由 agent 自动去拿它。
当下一步是从工作目录之外弄清楚某件事（一个第三方 API 的行为如何、一份规范说了什么、一个版本主张是否成立），而你宁愿不让自己的线程停下来做这些阅读时，就用它。你需要什么决定了用哪个技能：
| 你需要什么 | 该用哪个 |
|---|---|
| 一个决定正在等待的外部事实 | research |
| 一个和你一起、通过访谈做出的决定 | grilling |
一个写进 GLOSSARY.md 和 ADR 的长久架构决定 | grill-with-docs |
| 弄清楚某个做法在你的代码库里是否行得通 | prototype |
| 一个大到一场会话装不下的计划 | wayfinder |
research 与 grill-with-docs 之间的分界线是拿回来的东西的保质期。调研（research）产出短命的事实，比如这个库的认证机制截至本周的行为。一份 ADR 记录一个你会保留的决定。如果你产出的是决定而不是事实，那你是在质询（grilling），不是在调研。
委派出去的跑腿活
阅读由一个**后台 agent（background agent）**来跑。你继续工作，而它把每条主张追到其一手来源，写一个 Markdown 文件，然后回来汇报。调研是你委派出去的跑腿活，不是外包出去的思考。你得到一份可以据以质询、规划或设计的文档，而决定仍然由你来做。
没有什么能阻止这个后台 agent 自己再生成另一个后台 agent。这是这个技能记录得最充分的问题。
决定文件去哪儿的是仓库，不是技能。它遵循仓库里已经存在的笔记惯例，不管那是什么。如果没有，它会挑一个合理的位置，并告诉你在哪里。它每次运行写一个文件。
常见问题
它生成了第二个 research agent。这是应该发生的吗？
不应该。这是一个未解决的 bug，issue #530。技能让它的调用方启动一个后台 agent，但没有限制 agent 类型。于是调用方生成一个 general-purpose agent，它有 Agent 工具和同样的指令，于是又把它们执行一遍。一位报告者测量到，一个调研任务在三次重叠的运行中花了大约 45 万 token，而那个重复的实例在半小时后才完成，用户根本看不见它。它也会在 Claude Code 之外发生。用户确认在 Codex 搭配 GPT-5.6-sol 时也出现了同样的嵌套。没有已发布的修复。用户已经用自己的补丁改了他们安装的那份副本，加了一行，告诉已经是子代理（subagent）的 agent 自己去做这项工作。这有帮助，但它只是一条指令，不是结构性修复。调用这个技能之后，盯着你的后台任务列表，把重复的那个停掉。
相反的失败也会发生。如果你自己的全局指令禁止 agent 再次委派工作，后台 agent 会拒绝这项任务，而技能什么都不做，也不告诉你。
文件应该放在哪里，我该提交它吗？
技能把文件放在仓库已经存放笔记的地方，没有更多意见。社区的看法基本已经定了：保留 ADR，不保留调研文件。一个讨论这个问题的 Discord 帖子说得最清楚：「ADR 保留。其他一切做完之后就归档或删除。否则它会变成工作的残渣，而且如果你已经偏离了规范文档/调研，它会毒化未来的仓库读取。」一份调研文件记录的是它被写下的那天为真的东西，所以一份过期的调研文件比没有更糟。权衡下来，这些文件不属于 git，也没有存放它们的标准位置。人们改用 Obsidian、单独的知识仓库，或者 issue 追踪器。
什么算「高信任」的一手来源，由谁来决定？
由模型（model）决定。技能只点名有资格的来源种类（官方文档、源代码、规范、第一方 API），没有允许列表，没有域名门槛，也没有核查环节。这是这个技能最初被提出时最响亮的反对意见，而且没有人公开回答过它：「五个调研子代理指向垃圾，只会让你更快地得到五个自信的错误答案。你怎么把关什么算高信任来源？」你唯一的保护是每条主张上的引用。顺着其中两三条追下去。如果它们落在那件事的摘要上而不是那件事本身，这次运行就失败了。
后面的会话会复用早先一次运行发现的东西吗？
不会。没有任何东西会自动加载过去的调研文件。文件留在仓库里，直到有人类或某个技能指向它。这是设计早期受到的最强烈质疑：「价值在于这份 markdown 变成 agent 之后会重读的上下文（context），而不是取回本身。一个写一次就死掉的文件不过是一次花哨的搜索。」已发布的技能并没有解决它。在实践中，只有当你自己把它喂进下一步时，这个文件才有用：把它附到一份规范文档上，把它引用进一场质询会话，或者让一张工单（ticket）指向它。
为什么不干脆让 agent 去读文档？
你可以，而一条正好这么说的两行提示词，就是这个技能所取代的做法。技能给了你两样那条提示词给不了的东西。它在后台运行，所以你这场会话的上下文保持干净。而且一手来源约束和带引用的文件输出每次都是一样的，而不是取决于你怎么措辞那条提示词。和运行环境（harness）自带的深度研究模式相比，区别在于文件与一手来源规则，而不在于搜索。如果一条两行提示词就能在一个小问题上给你所需的东西，那就用那条两行提示词。
它什么时候停止阅读？
这个技能没有停止标准。这表现为两种看起来相反、成因却相同的抱怨：agent 走得实在太深，以及 agent 宽泛地覆盖一个主题却漏掉唯一要紧的那个细节。一位实践者这样说：「深度研究类技能有时候有点太深了。而让 agent 去做调研，通常的结果是漏掉关键细节。」你必须自己设定范围。一个狭窄、可回答的问题（一个 API、一个行为、一个版本主张）拿回来的结果，比「调研 X」好得多。
/wayfinder 创建了调研工单（research ticket）。那些要我自己解决吗？
不用，它现在会为你触发它们。在 v1.1 以来的未发布改动里，一场绘制地图的会话会为每张调研工单生成一个 /research 子代理，并并行运行它们。每一个都把发现记录在一条用完即弃的 research/<name> 分支上，工单里留一个指向它的上下文指针（context pointer）。调研工单是 wayfinder「每场会话一张工单」规则的唯一例外，因为它们是离开键盘（AFK）的：没有任何东西在等你。一个已知问题：之后删除那条分支，会破坏工单里的上下文指针。
它生效的标志
- 你自己的会话继续推进。如果你坐在那里看着它阅读，那么委派就没有发生。
- 恰好出现一个新的后台任务。第二个名字几乎一样的任务就是嵌套 bug。
- 出现一个新的 Markdown 文件，位于仓库已经用来放笔记的那个文件夹里，而且 agent 会告诉你路径。
- 里面每一条主张都带链接，随便挑两条追下去，会落到一份官方文档、一份规范或者源文件本身，而不是某个人对它的转述。
- 只凭这份文件，你就能做出你原本卡住的那个决定，不必自己再回到来源那里。
它在体系中的位置
research 是一个随时可用的独立技能（Standalones）。它给思考类技能提供输入，不是构建链上的一步。你把它的文件带进流程里。grilling 和 grill-with-docs 在已经掌握事实时会问出更锋利的问题，而 to-spec 可以对照它做综合。wayfinder 是唯一直接调用它的技能。它用 /research 子代理解决地图上的每一张调研工单。关于整张地图，见 ask-matt。