/claude-research-skill

/research — Multi-Agent Research Orchestrator

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

---

Phase 0.5: Social Signal Scan (Real-Time Pulse)

Before planning agents, run a quick social signal scan to see what people are **actually saying right now** about the topic. This informs agent scoping and prevents re-researching ground already covered.

**Run the last30days script (FOREGROUND, 5-minute timeout):**

# Find last30days skill root
for dir in \
  "${CLAUDE_PLUGIN_ROOT:-}" \
  "$HOME/.claude/skills/last30days" \
  "$HOME/.agents/skills/last30days" \
  "$HOME/.codex/skills/last30days"; do
  [ -n "$dir" ] && [ -f "$dir/scripts/last30days.py" ] && SKILL_ROOT="$dir" && break
done

if [ -n "${SKILL_ROOT:-}" ]; then
  export PATH="$HOME/Library/Python/3.9/bin:$PATH"
  python3 "${SKILL_ROOT}/scripts/last30days.py" "{RESEARCH_TOPIC}" --emit=compact --agent
fi

**If the script is available and returns results:**

1. Save the raw output to `research/[topic]/social_signal_scan.md` 2. Note the top signals: highest-engagement Reddit threads, most-liked X posts, relevant Polymarket odds 3. Use these to **inform agent scoping** in Phase 1:

• If Reddit/X surface a subtopic getting heavy discussion, ensure an agent covers it
• If Polymarket has relevant odds, feed them into risk/scenario agents
• If YouTube has relevant conference talks or demos, note URLs for agents

4. Provide the file path to agents as pre-loaded context:

   "Pre-gathered social signal data is available at: [absolute path to social_signal_scan.md]
   Read this file FIRST before searching. It contains recent Reddit threads, X posts,
   YouTube videos, and Polymarket data with engagement metrics. Build on this — don't re-research it."

**If the script is NOT available** (missing skill or no API keys), skip this phase silently and proceed to Phase 1. Social data is supplementary, not required.

**When to skip this phase:**

• Historical research (events >30 days old)
• Highly technical/academic topics where social signal adds little value
• User explicitly says to skip it

---

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 witho