/research 技能

它的作用

research 通过阅读拥有答案的来源来回答问题，然后在仓库里留下一份带引用的 Markdown 文件。它只从 第一手资料: official docs, source code, specs, first-party APIs. It follows every claim back to the source that owns it, so it will not repeat a blog post's account of an API when the API's own docs are reachable.

It does not answer you in the conversation. The output is a file, written where the repo already keeps such notes, with a link on each claim. You get a document you can react to, hand to another agent, or throw away, rather than an answer that is gone when the 会话 结束。

何时使用

输入 /research，或这个 agent 当任务变成阅读跑腿时自动调用它。

当下一步是 查明某事 from outside the working directory (how a third-party API behaves, what a spec says, whether a version claim holds), and you'd rather not stall your own thread doing the reading. What you need decides which skill:

之间的分界线 research and grill-with-docs 是 返回内容的上架寿命. Research produces short-lived facts, such as what this library's auth mechanism does as of this week. An ADR records a decision you keep. If what you are producing is a decision rather than a fact, you are 追问审视，不是研究。

委派出去的跑腿活

The reading runs as a 后台智能体. You keep working while it follows each claim to its 第一手资料, writes one Markdown file, and reports back. Research is legwork you delegate, not thinking you outsource. You get a document to grill, plan, or design against, and you still make the decision.

Nothing stops the background agent from spawning another background agent of its own. This is the skill's best-documented problem.

The repo decides where the file goes, not the skill. It follows whatever convention already exists for notes. If there is none, it picks a sensible place and tells you where. It writes one file per run.

常见问题

It spawned a second research agent. Is that meant to happen?

不。这是一个开放 bug， issue #530. The skill tells its caller to spin up a background agent but does not restrict the agent type. So the caller spawns a general-purpose agent, which has the Agent tool and the same instructions, and follows them again. One reporter measured a single research task costing roughly 450k tokens across three overlapping runs, and the duplicate finished half an hour later where the user could not see it. It also happens outside Claude Code. Users confirmed the same nesting in Codex with GPT-5.6-sol. There is no shipped fix. Users have patched their own installed copy with a line telling an agent that is already a 子智能体 to do the work itself, That helps, but it is only an instruction, not a structural fix. After you invoke the skill, watch your background task list and stop the duplicate.

The opposite failure also happens. If your own global instructions forbid an agent from re-delegating work, the background agent declines the task, and the skill does nothing without telling you.

Where should the file live, and should I commit it?

The skill puts the file where the repo already keeps notes and has no further opinion. The community view is mostly settled: keep ADRs, not research files. One Discord thread on this question put it most clearly: "ADRs yes. Everything else archive or delete after done. It otherwise becomes cruft of work and can poison future repo reads if you've drifted away from the spec/research." A research file records what was true on the day it was written, so a stale one is worse than none. On balance, these files don't belong in git, and there is no standard home for them. People use Obsidian, a separate knowledge repo, or the issue tracker instead.

什么算「高可信」第一手来源，由谁决定？

这个 model 会的。该技能指明 kinds of source that qualify (official docs, source code, specs, first-party APIs), and there is no allowlist, no domain gate, and no verification pass. This was the loudest objection when the skill was first proposed, and nobody has answered it publicly: "Five research subagents pointed at junk just gives you five confident wrong answers faster. How are you gating what counts as high-trust sources?" Your only protection is the citation on each claim. Follow two or three of them. If they land on a summary of the thing rather than the thing, the run failed.

后来的会话会复用之前运行发现的东西吗？

No. Nothing loads a past research file automatically. The file stays in the repo until a human or a skill points at it. This was the strongest early challenge to the design: "the value's the markdown becoming context the agent re-reads later, not the fetch itself. A write-once dead file is just a fancy search." The shipped skill does not solve it. In practice, the file is useful only when you feed it into the next step yourself: attach it to a spec, quote it into a 追问审视 会话，把 ticket 对着它。

为什么不直接让智能体去读文档？

You can, and a two-line prompt saying exactly that was the practice this skill replaced. The skill gives you two things the prompt does not. It runs in the background, so your session's context stays clean. And the primary-source constraint and the cited-file output are the same every time, rather than depending on how you phrased the prompt. Compared with a 运行框架's own deep-research mode, the difference is the file and the primary-source rule, not the search. If a two-line prompt gets you what you need on a small question, use the two-line prompt.

它何时停止阅读？

The skill has no stopping criterion. This shows up as two complaints that look opposite but have the same cause: agents that go far too deep, and agents that cover a topic broadly but miss the one detail that mattered. One practitioner put it as "deep-research skills are a bit too deep sometimes. And telling an agent to research usually results in missing crucial details." You have to set the scope. A narrow, answerable question (one API, one behaviour, one version claim) comes back far better than "research X".

/wayfinder created research tickets. Do I resolve those myself?

No, it now fires them for you. In the unreleased changes since v1.1, a charting session spawns one /research 子智能体 per research ticket and runs them in parallel. Each one records its findings on a throwaway research/<name> branch, with a 上下文指针 从任务中。研究任务是 wayfinder 每会话一个任务规则的唯一例外，因为它们是 AFK: nothing waits on you. One known problem: deleting the branch later breaks the context pointers in the tickets.

做到以下就算成功

• 你自己的会话继续运行。如果你坐在那里看它阅读，说明委托没有发生。
• 恰好出现一个新的后台任务。第二个名字几乎相同的，就是嵌套 bug。
• 出现一个新的 Markdown 文件，在仓库已用于笔记的文件夹里，智能体会告诉你路径。
• Every claim in it carries a link, and following two at random lands you on an official doc, a spec, or the source file itself, not on someone's write-up of it.
• 你可以仅凭文件做出卡住你的决策，无需自己回头查来源。

在流程中的位置

research is a reach-for-it-anytime standalone. It feeds the thinking skills and is not a step in the build chain. You take its file into the flow. 追问审视 and grill-with-docs ask sharper questions when they already have the facts, and to-spec 可以对照它进行综合。 wayfinder is the one skill that invokes it directly. It resolves each research ticket on its map with a /research 子智能体。整个地图，见 ask-matt.