research hands reading legwork to a background agent: a second agent that does the reading while you keep working.
That agent investigates your question against primary sources: official docs, source code, specs and first-party APIs, "not a secondary write-up of them." It follows every claim back to the source that owns it. Then it writes the findings to one Markdown file, citing each claim's source.
When to use it
Use it when you need facts gathered before you decide something. For example:
what a database host's free plan includes, from its official docs;
how a Python task queue retries failed jobs, from its docs and source code;
what a payment provider's API sends to your FastAPI backend, from that provider's own reference.
It suits reading that would take a while, because you keep working while it reads.
When not to use it
You need decisions, not facts. Use grill-with-docs. The findings feed your thinking; they don't replace the interview.
You need one fact from your own repo in the middle of an interview.grilling already sends a sub-agent to look up facts like that.
The answer isn't written anywhere, only in someone's head. Use to-questionnaire to ask them.
What it needs to start
A clear question, and a repo to save the findings in. The background agent also needs to reach the sources, such as the web or the code it should read.
What it creates
One Markdown file in the repo, with each claim's source cited. The agent saves it where the repo already keeps such notes. If there's no such place, it picks a sensible one and tells you where.
It creates no Issues, branches or pull requests. The file is something to take into the main flow at grill-with-docs, "since research feeds the thinking rather than replacing it."
Going deeper
6 min read · Going deeper not read
Why it exists
Matt opened pull request #409 on 2026-07-01 (merged the next day) to add research, and described it as "Deliberately tiny — grilling/grill-me sized." A week later his v1.1 release notes (2026-07-08) said it was added "To support the Wayfinder workflow", and that you can "Use it anytime you need to do a research session without breaking your flow."
His page on the Skill (updated 2026-08-24) names what it replaced: "a two-line prompt saying exactly that was the practice this skill replaced." The Skill adds two things that prompt doesn't. It runs in the background, so your session's context stays clean. And the primary-source rule and the cited file are the same on every run, whatever words you used to ask. If a two-line prompt answers a small question, his advice is to use the two-line prompt.
The icon on Matt's "The /research Skill" page on aihero.dev. From aihero.dev, 30 October 2026.
How it works underneath
Pull request #409 says the Skill "Leans on two leading words (primary sources, background agent) to stay terse." A leading word, in writing-for-agents' terms, is "a compact concept already living in the model's pretraining". So two bold phrases carry a whole way of working, and the file stays a few lines long.
Citations (60)
From snapshot/skills/research/SKILL.md, line 3: “Investigate a question against high-trust primary sources and capture the findings as a Markdown file in the repo. Use when the user wants a topic researched, docs or API facts gathered, or reading legwork delegated to a background agent.”
From snapshot/skills/research/SKILL.md, lines 10–12: “Investigate the question against primary sources (official docs, source code, specs, first-party APIs), not a secondary write-up of them. Follow every claim back to the source that owns it. 2. Write the findings to a single Markdown file, citing each claim's source. 3. Save it where the repo already keeps such notes; match the existing convention, and if there is none, put it somewhere sensible and say where.”
From snapshot/skills/ask-matt/SKILL.md, line 88: “The file it produces is something to take the main flow at , since research feeds the thinking rather than replacing it.”
In Claude Code, research's background agent runs as a background subagent: it runs while you keep working. Claude Code's docs say "Each subagent runs in its own context window", so the pages it reads never fill yours. On 2026-10-29, Matt's pull request #1341 added one sentence to the Skill: "Start it with a fresh context window." Some Codex models fork the parent conversation when they start a subagent, and the pull request says that fork "throws away the reason for using a subagent: a clean context that sees only its brief."
What counts as "high-trust" is left to the model. Matt's page says "there is no allowlist, no domain gate, and no verification pass." Your only check is the citation on each claim: follow two or three of them.
wayfinder is the one Skill that calls research itself. For each research Ticket on its map, it starts a subagent that runs research, and keeps the findings "on a throwaway research/<name> branch". That branch is pushed but never merged.
A real example
On 2026-08-03 a user added a measured run to issue #530. They had started two research runs at once, and one of them went wrong in three steps.
The first agent used 31k tokens and spawned a nested worker. Then it reported that it had launched a background research agent, having read nothing itself.
Told to stop delegating, it did a full pass itself: 171k tokens and 110 tool calls.
About half an hour later the nested worker finished the same research again: 248k tokens. It found the file already there and merged into it, so nothing looked wrong.
That came to about 450k tokens across three runs. A clean run on another topic in the same session cost 188k. The reporter wrote that the worst part was not the cost: the third run "ran entirely out of view".
The first agentspawned a nested worker
a full pass itself171k tokens and 110 tool calls
the nested workerfinished the same research again: 248k tokens
about 450k tokens across three runs
Where it goes wrong
It starts a second agent. The Skill tells the caller to "spin up a background agent". The agent it starts can take that line as meant for itself too, as in the run above (issue #530, opened 2026-07-13). Matt's page, updated 2026-08-24, calls this "an open bug". The issue itself is newer: it was closed as not planned on 2026-10-06. Matt's repo now records that "The harness should be responsible for stopping infinite subagent loops, not skills." Claude Code lets subagents nest "up to three layers below the main conversation". So the check is yours. Matt's page says a working run shows "Exactly one new background task"; stop any second one with a near-identical name.
It does nothing. If your own instructions forbid an agent from handing work on, the background agent declines, "and the skill does nothing without telling you."
It loses everything when stopped. Issue #1272 (opened 2026-10-14, still open) reports research agents, started with the reporter's own hand-written briefs, stopped mid-run with all their findings in context and "nothing was on disk". The Skill never says when to start writing. After the reporter told their agents to create the file in the first few tool calls, the next run was killed twice and still kept its first two sections.
It reads too much, or misses the point. The Skill has no stopping rule, so agents go "far too deep" or miss "the one detail that mattered". Matt's page says "You have to set the scope": one API, one behaviour or one version claim comes back far better than "research X".
It goes stale. Nothing loads an old research file on its own, and the file records what was true on the day it was written. Matt's page reports the community view: keep ADRs, not research files.
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't), give research one narrow question about your backend: "How does Alembic's autogenerate handle a renamed column? Use Alembic's own docs and source." Add one line to the request: create the file in your first few tool calls, and update it after each source.
Keep working on something else while it reads. Then check four things:
exactly one new background task appeared, and you stopped any duplicate;
one new Markdown file landed in your notes folder, and the agent told you its path;
two citations, picked at random, open Alembic's own docs or source, not a write-up of them;
you can decide how to handle renames in your migrations from the file alone.
Going deeper's Check questions are asked in Next up.
into
/grill-with-docs
From snapshot/skills/grilling/SKILL.md, line 28: “When a frontier question needs a fact from the environment (filesystem, tools, etc.), dispatch a sub-agent with a fresh context window to find it”
From snapshot/skills/ask-matt/SKILL.md, line 89: “comes in when the thing blocking you isn't in your head or the codebase but in someone else's, and it writes them a questionnaire to fill in.”
From snapshot/web/aihero.dev/skills-research.md, line 87: “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”
From snapshot/web/github.com/mattpocock-skills-pull-1341.md, line 31: “Some Codex models fork the parent conversation when they spawn a subagent. The fork inherits the parent's context window, which throws away the reason for using a subagent: a clean context that sees only its brief.”
From snapshot/web/aihero.dev/skills-research.md, line 79: “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.”
From snapshot/skills/wayfinder/SKILL.md, line 115: “For each research ticket you just created, spin up a subagent with a fresh context window that calls the Skill tool with "research" to resolve it in parallel, capturing its findings on a throwaway research/<name> branch with a context pointer from the ticket. Push the branch but open no PR: it is never merged.”
From snapshot/web/github.com/mattpocock-skills-issues-530.md, line 43: “First run (31k tokens, 2 tool calls, ~1 min): instead of researching, it called Agent itself and spawned a nested worker, then reported back "I've launched a background research agent to investigate..."”
From snapshot/web/github.com/mattpocock-skills-issues-530.md, line 44: “I noticed no output file existed and sent the agent a message telling it to stop delegating and do the work directly. It complied and did a full pass itself (171k tokens, 110 tool calls, ~20 min).”
From snapshot/web/github.com/mattpocock-skills-issues-530.md, line 45: “~30 min later it separately notified completion, having done the entire same research task a second time (248k tokens, 147 tool calls, ~26 min) — it found the output file already existed (from step 2) and merged into it rather than failing, so the duplication wasn't even visible as an error.”
From snapshot/web/github.com/mattpocock-skills-issues-530.md, line 47: “a parallel, correctly-behaved research invocation on a different topic in the same session cost 188k tokens / 75 tool calls for comparison). The scariest part isn't the token cost, it's that step 3 ran entirely out of view”
From snapshot/web/aihero.dev/skills-research.md, line 71: “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.”
From snapshot/web/github.com/mattpocock-skills-issues-1272.md, line 35: “After we added "create the file within the first few tool calls, with a heading per section, and update it after each source" to our dispatch briefs, the next run was killed twice and still kept its first two sections intact.”
From snapshot/web/aihero.dev/skills-research.md, lines 99–103: “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.”
