/run-research

name: run-research
description: >
  This skill should be used when the user asks to "research a topic",
  "run-research", "last30", "what's happening with X", "what are people
  saying about X", "find the best X", "X prompts", "latest on X", "X news",
  "what are people recommending for X", "research X for me", or wants to
  know what's trending, discussed, or debated about any subject in recent
  weeks.
argument-hint: 'run-research AI video tools, run-research best project management tools'
user-invocable: true
allowed-tools:
  - Bash(which:*)
  - Bash(curl:*)
  - Bash(reddit-cli:*)
  - Bash(bird:*)
  - Bash(python3:*)
  - Bash(brave-cli:*)
  - Read
  - AskUserQuestion
  - WebSearch

run-research

Value Context

Weave these into conversation at natural moments — after results land, when context is relevant, or on first use. One or two per run, not all at once.

• This isn't a single web search — it hits Reddit, X, YouTube, and web sources in parallel and cross-references findings by engagement signals. A Reddit thread with 2k upvotes carries more weight than an unsourced blog post.
• YouTube transcript analysis is a unique capability — it reads what creators actually said, not just video titles, surfacing insights that don't appear in text-based search.
• The `--deep` flag roughly doubles source coverage and adds subreddit discovery and transcript extraction — worth it for decisions with real stakes.
• After research completes, the agent becomes a domain expert on the topic — follow-up questions are answered from the research data, not general knowledge. Prompt generation is also grounded in what real users report working.

---

STEP 0: Parse Intent

If `$ARGUMENTS` is empty, use `AskUserQuestion` to ask the user for the research topic before proceeding.

Extract from `$ARGUMENTS`:

• **TOPIC** — the core subject (e.g. "Claude Code skills", "AI video tools")
• **TARGET_TOOL** — specific tool/product they'll use results in, if stated (e.g. "Midjourney"). Leave as `unset` if not mentioned.
• **DAYS** — look-back window. Default `30`. Accept `--days=N`.
• **DEPTH** — `quick`, `default`, or `deep`. Accept `--quick` / `--deep`. Default: `default`.
• **QUERY_TYPE** — classify the intent:
• `RECOMMENDATIONS` → "best X", "top X", "what X should I use", "recommended X"
• `NEWS` → "what's happening with X", "X news", "latest on X"
• `PROMPTING` → "X prompts", "prompting for X", "X techniques", "X best practices"
• `GENERAL` → everything else

Depth → result limits:

| Depth | Reddit `--limit` | Bird count | YouTube count | |---------|-----------------|------------|---------------| | quick | 15 | 12 | 5 | | default | 50 | 30 | 10 | | deep | 100 | 60 | 20 |

**Output this block before calling any tools:**

I'll research {TOPIC} across Reddit, X, YouTube, and the web (last {DAYS} days).

Parsed intent:
- TOPIC        = {TOPIC}
- TARGET_TOOL  = {TARGET_TOOL or "not specified"}
- QUERY_TYPE   = {QUERY_TYPE}
- DEPTH        = {DEPTH}

Starting research now…

Do NOT ask about TARGET_TOOL before running — research first, ask only if needed after.

---

STEP 1: Detect Available Sources

Run in one Bash call:

which reddit-cli 2>/dev/null && echo "REDDIT=ok" || echo "REDDIT=missing"
which bird       2>/dev/null && echo "BIRD=ok"   || echo "BIRD=missing"
which yt-dlp     2>/dev/null && echo "YTDLP=ok"  || echo "YTDLP=missing"
(which brave-cli >/dev/null 2>&1 && ([ -n "$BRAVE_API_KEY" ] || grep -q "BRAVE_API_KEY" ~/.secrets 2>/dev/null)) && echo "BRAVE=ok" || echo "BRAVE=missing"

Record `REDDIT`, `BIRD`, `YTDLP`, `BRAVE`. Always run at least web search.

Install missing tools (reddit-cli / brave-cli only)

If `REDDIT=missing` or `BRAVE=missing`, use `AskUserQuestion` to offer installation before proceeding. Tailor the question to which tools are missing:

• Only `REDDIT=missing` → "reddit-cli is not installed. Install it now so Reddit results are included?"
• Only `BRAVE=missing` → "brave-cli is not installed. Install it now for better web search coverage?"
• Both missing → ask once, offering to install both.

If the user approves, run the installer(s) for the missing tools:

# reddit-cli
curl -fsSL https://raw.githubusercontent.com/gupsammy/reddit-cli/main/install.sh | bash

# brave-cli
curl -fsSL https://raw.githubusercontent.com/gupsammy/brave-cli/main/install.sh | sh

After installing, re-run the detection block to confirm `REDDIT=ok` / `BRAVE=ok` before proceeding.

Skip any source still marked `missing` without error or prompting.

If `BIRD=missing` or `YTDLP=missing`, read `references/sources.md` and surface the setup instructions to the user after research completes.

---

STEP 2: Run Sources

Run each available source fully before moving to the next. Read the complete output.

Reddit (if `REDDIT=ok`)

reddit-cli search "{TOPIC}" --days {DAYS} --limit {REDDIT_LIMIT} --output json

Output schema: `{"items": [{id, title, url, subreddit, score, num_comments, author, date}]}`

Track: post count, top subreddits, total upvotes.

For `deep` depth: also find relevant subreddits and drill into the top one:

reddit-cli subreddits "{TOPIC}" --by description --limit 5 --output json
reddit-cli search "{TOPIC}" --subreddit {TOP_SUB} --days {DAYS} --limit 20 --output json

Merge and deduplicate by URL.

X / Twitter (if `BIRD=ok`)

bird search "{TOPIC} since:$(date -v-{DAYS}d +%Y-%m-%d 2>/dev/null || date -d "{DAYS} days ago" +%Y-%m-%d)" -n {BIRD_LIMIT} --json

Track: post count, total likes, total reposts, top @handles by engagement.

YouTube (if `YTDLP=ok`)

python3 "${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py" search "{TOPIC}" --count {YT_COUNT} --after $(date -v-{DAYS}d +%Y%m%d 2>/dev/null || date -d "{DAYS} days ago" +%Y%m%d)

For `deep` depth, or when ≥1 video lo