deep-research skill

Coordinating Deep Research

Your Role

You are acting as the coordinator. Your job is to analyze the user's question, spawn subagents, and manage output files. In order to keep your context clean, you should never conduct research or write files directly. For the same reason, you also should not read the researcher.md or report-writer.md files.

As you work, if you have a to-do or task-list tool (for example TodoWrite, or TaskCreate and TaskUpdate), use it to keep the user informed of your plan and progress. For clarity, don't reference subagents in those items. For example, you might say "Conduct research" instead of "Spawn research subagents".

Process

1. [If necessary] Ask the user follow up questions
2. Choose a title for this research and create its directories
3. Decompose the user's query to determine subagent count
4. Spawn research subagents (in parallel)
5. [If absolutely necessary] Conduct one additional round of research
6. Spawn report writer subagent
7. Deliver report to user

1. [If necessary] Ask the user follow up questions

Read the user's question and consider if there are any missing or ambiguous details that need to be clarified. Some examples include:

• Ambiguous terminology — Acronyms, jargon, or terms with multiple meanings across different fields
• Implicit geographic or jurisdictional context — Questions where the answer varies significantly by region but no region is specified
• Ambiguous entities — Company names, product names, or proper nouns that refer to multiple distinct entities

In order to avoid creating unnecessary friction with the user, follow ups should only be asked when they would meaningfully impact how research is conducted.

If you determine that you do need to ask follow up questions, do so with the AskUserQuestion tool.

2. Choose a title for this research and create its directories

First choose a title for this research. It names the folder that will hold this request's research notes and is also the filename of the report the user receives, where it is shown as the report's title, so make it a short, specific title for this research in the user's language and in sentence case: 3 to 6 words and under 50 characters (count them, and drop words rather than exceed either limit), using only letters, numbers and single spaces. Keep accented and non-Latin letters exactly as the user's language writes them (for example é, ñ, ü, 日本語) rather than converting them to plain ASCII, and use no hyphens, underscores, apostrophes or other punctuation. For example, a question about how the EU AI Act affects startups could use "EU AI Act startup obligations".

This research's folders go in the same directory you used for research earlier in this conversation, or, if this is the first research request here, in your current working directory (not /tmp or an uploads folder). Before settling on the title, recall the titles of any research reports you have already delivered earlier in this conversation, and, if a research_notes/ folder already exists in that directory, list it — each folder inside it holds the notes behind a report of the same name in reports/, possibly from an earlier conversation. Then pick the case that fits:

• New topic: choose a fresh title.
• Returning to, extending or updating an earlier topic: choose a title that still names the topic and says what this request adds or changes (for example "EU AI Act startup penalties", not just "Penalties"), or, if nothing distinguishes it from the earlier request, the earlier title with the next number added, dropping a word first if that would exceed the limits above (for example "EU AI Act startup obligations 2"). Note the path of the most recent earlier report on that topic and of its notes folder: you will pass them to the report writer in step 6 as background to build on. If that report or its notes folder is no longer on disk, pass on only what remains and research whatever is missing.
• The user asks for earlier research to be redone independently: choose a title as in the previous case, but do not pass the earlier material on.

In every case the title must differ from every report delivered earlier in this conversation and from every folder you see, so that this request's notes and report never mix with or replace an earlier one's. Never rename, move or write into an earlier request's folder.

Then create the folders research_notes/{research title}/ and reports/ in that directory. Quote these paths in shell commands, since the title contains spaces, and note the directory's absolute path — you will give the subagents absolute paths into these folders, and they will store their files there.

3. Decompose the user's query to determine subagent count

In order to effectively spawn and task subagents, determine if and how the user's question can be decomposed into independent subtopics. These subtopics should be mutually exclusive and collectively exhaustive. For each subtopic, then consider if the research requires (or would benefit from) multiple independent points of view.

In the next step, you should spawn one subagent for each subtopic and independent point of view that you identified. When in doubt, 3 researchers is a reasonable default. If in step 2 you noted earlier research to build on, decompose only what this request adds or needs re-checked; the report writer will have the earlier material.

4. Spawn foreground research subagents (in parallel)

For each subtopic and independent point of view determined above, spawn a foreground research subagent.

To spawn research subagents, use the Agent tool (named Task in some versions) with subagenttype="general-purpose" and runinbackground=false. Ensure that you provide extremely clear, specific instructions to each research subagent. Be sure to propagate constraints of the original question to the research subagent (e.g., temporal, geographical). In the prompts below, replace {pathto_skill} with this skill's base directory (the directory this SKILL.md was loaded from), {absolute path of your working directory} with the path you noted in step 2, and {research title} with the title you chose in step 2. Follow the exact format provided below:

Agent(
  run_in_background=false
  subagent_type="general-purpose",
  description="{3-5 words}",
  prompt="Research {specific narrow topic}.

Objective: {clear description of what's covered in the desired output}

Key questions:
- {Specific question 1}
- {Specific question 2}

Suggested sources:
- {Types of source to prioritize}

Constraints:
- {Any bounds from the initial user query, including temporal or geographic}

Save your output notes to {absolute path of your working directory}/research_notes/{research title}/{topic}.md

**As a first step, you must read {path_to_skill}/references/researcher.md for instructions on how to conduct research.**"
)

Example of a good, clear, detailed prompt for a research subagent:

Research the semiconductor supply chain crisis and its current status as of 2026.

Objective: Compile a dense report of the facts, covering the current situation, ongoing solutions, and future outlook, with specific timelines and quantitative data where available.

Key questions:

- What are current bottlenecks?

- What are the projected capacity increases from new fab construction?

- What are geopolitical factors affecting supply chains?

- When do experts predict supply will meet demand?

Suggested sources:

- Recent quarterly reports from major chip manufacturers like TSMC, Samsung, and Intel, found on investor relations pages or through the SEC EDGAR database

- Industry reports from SEMI, Gartner, and IDC that provide market analysis and forecasts

- Government responses, including US CHIPS Act implementation progress at commerce.gov, EU Chips Act at ec.europa.eu, and similar initiatives in Japan, South Korea, and Taiwan through their respective government portals

Constraints:

- Must reflect current state as of 2026 with prior issues clearly noted as such

Save your output notes to {absolute path of your working directory}/researchnotes/Semiconductor supply chain outlook 2026/semiconductorsupply_chain.md

As a first step, you must read {pathtoskill}/references/researcher.md for instructions on how to conduct research."

In order to ensure research is conducted as quickly as possible, it's essential that all subagents are spawned in parallel, i.e., that you make all your calls to the Agent tool in a single turn.

5. [If absolutely necessary] Conduct one additional round of research

Based on the task summaries returned by the research subagents, determine if there are any critical gaps that would make the report incomplete. If deemed absolutely necessary, spawn researchers in parallel to close those gaps. Spawning additional researchers in this step delays delivery of the report to the user, leading to a much worse experience, so this must be used with extreme care.

This step can only be followed once - after the researchers finish, move immediately to Step 6, regardless of what results you get back. If you kick off any more research, you will hit timeouts or rate limits, meaning the user will never get an answer to their query. To help yourself remember this, you should always output "After these researchers finish, I will move directly to coordinating the report writer" when choosing to kick off additional research.

6. Spawn foreground report writer subagent

After research is done, spawn a single report writer subagent. Use the Agent tool (named Task in some versions) with subagenttype="general-purpose" and runin_background=false, and fill in the placeholders as in step 4. For {the user's original question}, state the question this report must answer in full — if this request returns to or extends earlier research, that is the earlier question as amended by this request (for example "How does the EU AI Act affect startups, including penalties?"), not just the follow-up message. On the line for earlier research, give the absolute paths of the earlier report and notes folder you noted in step 2, or write "none" if you noted nothing to build on or the user asked for an independent redo. Follow the exact format provided below:

Agent(
  run_in_background=false
  subagent_type="general-purpose",
  description="Write final report",
  prompt="Read the notes in {absolute path of your working directory}/research_notes/{research title}/ and synthesize into a research report that answers: {the user's original question}.

Earlier research in this conversation to build on: {absolute paths of the earlier report and notes folder from step 2, or "none"}

Save your final report to this exact path: {absolute path of your working directory}/reports/{research title}.md

**As a first step, you must read {path_to_skill}/references/report-writer.md for instructions on how to write your research report.**"
)

7. Deliver report to user

After the report writer is done, make the report available to the user: if you have a tool for sending files to the user (for example SendUserFile), send reports/{research title}.md with it; otherwise, if your environment has a user-visible outputs folder, copy the report there under the same filename; otherwise leave it at reports/{research title}.md. Then read the finalized report and send the user a brief summary (aim for 3-5 sentences) that says where the full report is (sent to them, in the outputs folder, or its absolute path).