/claude-research-skill

/research — Multi-Agent Research Orchestrator

Decompose a research question into parallel agent workstreams, launch them, monitor progress, and synthesize results.

---

Phase 1: Plan the Research

When the user asks to research something:

1. **Understand the question.** What exactly are we trying to learn? Who is it for? What decisions will it inform?

2. **Decompose into agent workstreams.** Each agent should have:

• A clear, non-overlapping scope (e.g., "Market sizing & competitive landscape", "Technical feasibility & architecture", "Regulatory & compliance landscape")
• 3-6 specific sections they must write
• A target output length (~500-1500 lines of markdown per agent is the sweet spot)

3. **Plan the synthesis agent.** This runs AFTER all research agents complete. Its job is to read all agent outputs and produce a single coherent synthesis document with cross-cutting insights, contradictions, and recommendations.

4. **Present the plan to the user.** Format:

## Research Plan: [Topic]

### Agent 1: [Name]
**Scope:** [1-2 sentence scope]
**Sections:**
1. [Section name]
2. [Section name]
3. ...
**Output file:** research/[topic]/[agent-name].md

### Agent 2: [Name]
...

### Synthesis Agent
**Runs after:** All research agents complete
**Output file:** research/[topic]/synthesis.md

5. **Wait for user approval** before proceeding. Do NOT launch agents until the user confirms the plan.

---

Phase 2: Create Skeleton Files

Once the user approves the plan:

1. **Create the output directory:** `research/[topic]/`

2. **For each research agent, create a skeleton markdown file** at the planned path. The skeleton MUST include:

# [Agent Name]: [Scope Title]

**Status:** IN PROGRESS
**Last updated:** [timestamp]

---

## CRITICAL INSTRUCTIONS FOR AGENT

> **YOU WILL BE STOPPED AND RELAUNCHED IF YOU VIOLATE THIS PROTOCOL.**
>
> The ONLY acceptable pattern is: **Search -> Edit -> Search -> Edit -> Search -> Edit.**
> NEVER: Search -> Search. NO EXCEPTIONS. NOT EVEN ONCE.
>
> After EVERY search or fetch, IMMEDIATELY Edit this file with what you learned.
> If you do two searches in a row without an Edit to this file, you are VIOLATING THE PROTOCOL and will be killed.
>
> Work through sections in order. For each section:
> 1. Search/fetch for information
> 2. IMMEDIATELY write findings to this file under that section
> 3. Search/fetch for more information on the same section
> 4. IMMEDIATELY update this file with additional findings
> 5. Move to next section only after writing current section
>
> If a web fetch returns a 403 error, WRITE WHAT YOU HAVE before trying another URL.
>
> Every number needs a source. Every source needs a clickable URL inline.
> Do NOT collect sources at the end -- put them inline with the facts.
>
> When you are DONE with all sections, change "Status: IN PROGRESS" to "Status: COMPLETE" at the top.

---

## 1. [First Section Name]

[To be filled by research agent]

## 2. [Second Section Name]

[To be filled by research agent]

...

3. **Also create the synthesis skeleton** with similar critical instructions, but noting it should read from the other agent output files.

---

Phase 3: Launch Research Agents

Launch ALL research agents in parallel using the Task tool with `run_in_background: true`.

Each agent prompt MUST include:

1. **The research question and their specific scope** -- be precise about boundaries 2. **The exact file path they must write to** -- absolute path 3. **The section list they must complete** -- numbered, in order 4. **The critical write protocol** -- copy verbatim:

CRITICAL WRITE PROTOCOL -- READ THIS BEFORE DOING ANYTHING:

YOU WILL BE STOPPED AND RELAUNCHED IF YOU VIOLATE THIS PROTOCOL.

The ONLY acceptable pattern is: Search -> Edit -> Search -> Edit -> Search -> Edit.
NEVER: Search -> Search. NO EXCEPTIONS. NOT EVEN ONCE.

You MUST Edit your output file after EVERY SINGLE search or web fetch.
If you do two searches in a row without an Edit to your file, you are VIOLATING THE PROTOCOL and will be killed.

Work through your sections IN ORDER (1, 2, 3...). For each section:
1. Do ONE search or web fetch
2. IMMEDIATELY Edit the file to write what you learned under that section
3. Do another search if needed
4. IMMEDIATELY Edit the file again with additional findings
5. Only move to the next section after the current one has real content

If a web fetch returns a 403 error, do NOT try multiple alternative URLs before writing.
Write what you have so far, THEN try another URL, THEN write again.

Every quantitative claim needs an inline source URL: [Source Name](https://url.com)
Do NOT put sources at the bottom. Inline only.

When ALL sections are complete, change the file's Status line from "IN PROGRESS" to "COMPLETE".

5. **Any relevant context files they should read first** -- provide absolute paths 6. **Use `subagent_type: "general-purpose"`** for all research agents

**IMPORTANT:** Use `run_in_background: true` for all research agents so they run in parallel.

After launching, tell the user how many agents are running and their output file paths.

---

Phase 4: Monitor Progress

Use escalating check-in intervals:

Check-in 1: ~30 seconds after launch

• Read each agent's output file to verify they've started writing
• Report to user: which agents have started writing, which haven't
• If any agent has an empty file (no content beyond the skeleton), flag it -- the agent may be stuck in a research loop

Check-in 2: ~2 minutes after launch

• Read each agent's output file
• Report: approximate progress (which sections have content, rough line counts)
• Flag any agent that hasn't progressed since last check

Check-in 3: ~5 minutes after launch

• Read each agent's output file
• Report: which agents are complete (Status: COMPLETE), which are still working
• **STUCK AGENT RULE:** If an agent's line count has NOT increased between two consecutive check-ins, it is stuck. Do NOT wait -- sto