The /research Skill

What it does

research answers a question by reading the sources that own the answer, then leaves a cited Markdown file in the repo. It works only from primary sources: 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 session ends.

When to reach for it

Type /research, or the agent reaches for it automatically when a task turns into reading legwork.

Reach for it when the next step is finding something out 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:

The line between research and grill-with-docs is the shelf life of what comes back. 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 grilling, not researching.

Delegated legwork

The reading runs as a background agent. You keep working while it follows each claim to its primary source, 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.

Common questions

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

No. This is an open 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 subagent 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.

What counts as a "high-trust" primary source, and who decides?

The model does. The skill names the 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.

Does a later session reuse what an earlier run found?

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 grilling session, point a ticket at it.

Why not just ask the agent to go read the docs?

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 harness'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.

When does it stop reading?

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 subagent per research ticket and runs them in parallel. Each one records its findings on a throwaway research/<name> branch, with a context pointer from the ticket. Research tickets are the one exception to wayfinder's one-ticket-per-session rule, because they are AFK: nothing waits on you. Those branches have two known problems. Users have seen the subagent open a draft PR from a branch that is never meant to merge (issue #576). And deleting the branch later breaks the context pointers in the tickets.

It's working if

• Your own session keeps going. If you are sitting watching it read, the delegation didn't happen.
• Exactly one new background task appears. A second one with a near-identical name is the nesting bug.
• One new Markdown file shows up, in the folder the repo already uses for notes, and the agent tells you the path.
• 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.
• You can make the decision you were stuck on from the file alone, without going back to the sources yourself.

Where it fits

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. grilling and grill-with-docs ask sharper questions when they already have the facts, and to-spec can synthesise against it. wayfinder is the one skill that invokes it directly. It resolves each research ticket on its map with a /research subagent. For the whole map, see ask-matt.