Back to Details

run-research

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

run-research

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.
在合适的自然对话时机融入这些内容——比如研究结果出来后、上下文相关时，或首次使用时。每次运行只提及1-2点，不要全部说完。
  • 这不是单一的网页搜索——它会同时检索Reddit、X、YouTube和网页来源，并根据互动信号交叉验证结果。一条获得2000个赞的Reddit帖子比无来源的博客文章更具参考价值。
  • YouTube字幕分析是一项独特功能——它会读取创作者实际所说的内容，而非仅依赖视频标题，能挖掘出基于文本搜索无法发现的见解。
  • --deep
    标志会使来源覆盖范围大致翻倍，并增加子版块发现和字幕提取功能——对于有实际决策需求的场景非常值得使用。
  • 研究完成后，Agent会成为该主题的领域专家——后续问题将基于研究数据回答，而非通用知识。提示词生成也会基于真实用户反馈的有效内容。

STEP 0: Parse Intent

步骤0：解析意图

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:
DepthReddit 
--limit
Bird countYouTube count
quick15125
default503010
deep1006020
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.
如果
$ARGUMENTS
为空，使用
AskUserQuestion
询问用户研究主题后再继续。
从
$ARGUMENTS
中提取：
  • TOPIC — 核心主题（例如“Claude Code skills”“AI视频工具”）
  • TARGET_TOOL — 用户指定的将使用研究结果的特定工具/产品（例如“Midjourney”）。如果未提及则设为
    unset
    。
  • DAYS — 回溯窗口。默认值为
    30
    。支持
    --days=N
    参数。
  • DEPTH — 
    quick
    、
    default
    或
    deep
    。支持
    --quick
    /
    --deep
    参数。默认值：
    default
    。
  • QUERY_TYPE — 意图分类： 
    • RECOMMENDATIONS
      → “最佳X”“顶级X”“我应该使用什么X”“推荐的X”
    • NEWS
      → “X的最新动态”“X相关新闻”“X的最新资讯”
    • PROMPTING
      → “X提示词”“X相关提示技巧”“X技巧”“X最佳实践”
    • GENERAL
      → 其他所有情况
深度 → 结果数量限制：
深度Reddit 
--limit
X帖子数量YouTube视频数量
quick15125
default503010
deep1006020
调用任何工具前输出以下内容：
我将在Reddit、X、YouTube和网页上研究{TOPIC}（近{DAYS}天内容）。

解析后的意图：
- TOPIC        = {TOPIC}
- TARGET_TOOL  = {TARGET_TOOL or "未指定"}
- QUERY_TYPE   = {QUERY_TYPE}
- DEPTH        = {DEPTH}

开始研究…
运行前不要询问TARGET_TOOL——先完成研究，仅在后续需要时再询问。

STEP 1: Detect Available Sources

步骤1：检测可用来源

Run in one Bash call:
bash
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.
通过一次Bash调用运行：
bash
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"
记录
REDDIT
、
BIRD
、
YTDLP
、
BRAVE
状态。至少要运行网页搜索。

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

安装缺失工具（仅reddit-cli / brave-cli）

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:
bash
undefined
如果
REDDIT=missing
或
BRAVE=missing
，使用
AskUserQuestion
询问用户是否要安装后再继续。根据缺失的工具调整问题：
  • 仅
    REDDIT=missing
    → “reddit-cli未安装。是否现在安装以包含Reddit结果？”
  • 仅
    BRAVE=missing
    → “brave-cli未安装。是否现在安装以获得更好的网页搜索覆盖？”
  • 两者都缺失 → 一次性询问是否安装两者。
如果用户同意，运行缺失工具的安装脚本：
bash
undefined

reddit-cli

reddit-cli

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

brave-cli

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.

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

安装完成后，重新运行检测脚本确认`REDDIT=ok`/`BRAVE=ok`后再继续。

跳过仍标记为`missing`的来源，无需报错或提示。

如果`BIRD=missing`或`YTDLP=missing`，在研究完成后向用户展示`references/sources.md`中的设置说明。

---

STEP 2: Run Sources

步骤2：运行来源检索

Run each available source fully before moving to the next. Read the complete output.
完成一个来源的全部检索后再进行下一个。读取完整输出内容。

Reddit (if 
REDDIT=ok
)

Reddit（如果
REDDIT=ok
）

bash
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:
bash
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.
bash
reddit-cli search "{TOPIC}" --days {DAYS} --limit {REDDIT_LIMIT} --output json
输出格式：
{"items": [{id, title, url, subreddit, score, num_comments, author, date}]}
跟踪：帖子数量、顶级子版块、总点赞数。
如果是
deep
深度：同时查找相关子版块并深入检索排名第一的子版块：
bash
reddit-cli subreddits "{TOPIC}" --by description --limit 5 --output json
reddit-cli search "{TOPIC}" --subreddit {TOP_SUB} --days {DAYS} --limit 20 --output json
合并结果并按URL去重。

X / Twitter (if 
BIRD=ok
)

X / Twitter（如果
BIRD=ok
）

bash
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.
bash
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
跟踪：帖子数量、总点赞数、总转发数、互动量最高的@账号。

YouTube (if 
YTDLP=ok
)

YouTube（如果
YTDLP=ok
）

bash
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 looks highly relevant (based on title + view count): fetch transcript of the top 1-2 results:
bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py" transcript "{VIDEO_URL}"
Transcripts are dense signal — read them fully and extract specific insights, not summaries.
Track: video count, total views, number of transcripts read.
bash
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)
如果是
deep
深度，或有≥1个视频看起来高度相关（基于标题+播放量）：获取排名前1-2个视频的字幕：
bash
python3 "${CLAUDE_PLUGIN_ROOT}/skills/search-youtube/scripts/yt_research.py" transcript "{VIDEO_URL}"
字幕是高密度信号源——需完整读取并提取具体见解，而非仅做摘要。
跟踪：视频数量、总播放量、已读取的字幕数量。

Web Search

网页搜索

If 
BRAVE=ok
 — use brave-cli (cheaper, single binary):
bash
brave-cli search "{TOPIC}" -n 10 --freshness month --output json
brave-cli search "{TOPIC} github OR dev.to OR medium.com" -n 5 --freshness month --output json
If 
BRAVE=missing
 — use Claude's 
WebSearch
tool. Run 2-3 queries based on QUERY_TYPE:
  • RECOMMENDATIONS
    → 
    best {TOPIC}
    , 
    {TOPIC} comparison
  • NEWS
    → 
    {TOPIC} news 2026
    , 
    {TOPIC} announcement
  • PROMPTING
    → 
    {TOPIC} prompts examples
    , 
    {TOPIC} techniques
  • GENERAL
    → 
    {TOPIC} 2026
    , 
    {TOPIC} discussion
Exclude: reddit.com, x.com, twitter.com (already covered above). Target: blogs, docs, GitHub, dev.to, news sites.
Track: page count.
如果
BRAVE=ok
 — 使用brave-cli（成本更低，单一二进制文件）：
bash
brave-cli search "{TOPIC}" -n 10 --freshness month --output json
brave-cli search "{TOPIC} github OR dev.to OR medium.com" -n 5 --freshness month --output json
如果
BRAVE=missing
 — 使用Claude的
WebSearch
工具。根据QUERY_TYPE运行2-3次查询：
  • RECOMMENDATIONS
    → 
    best {TOPIC}
    , 
    {TOPIC} comparison
  • NEWS
    → 
    {TOPIC} news 2026
    , 
    {TOPIC} announcement
  • PROMPTING
    → 
    {TOPIC} prompts examples
    , 
    {TOPIC} techniques
  • GENERAL
    → 
    {TOPIC} 2026
    , 
    {TOPIC} discussion
排除：reddit.com、x.com、twitter.com（已在上述来源覆盖）。目标来源：博客、文档、GitHub、dev.to、新闻网站。
跟踪：页面数量。

STEP 3: Judge Agent — Synthesize

步骤3：Agent判断——合成内容

Ground synthesis entirely in the actual research output, not prior knowledge.
Weight by engagement because engagement = aggregate human signal strength — a thread with 2k upvotes represents more real-world consensus than an article with no engagement metric:
  1. X posts — highest when engagement (likes + reposts) is high
  2. Reddit threads — high; engagement = upvotes + comments
  3. YouTube transcripts — high when available (dense, human-verified signal)
  4. Web pages — lower; no engagement data
Identify:
  • Patterns appearing across ≥2 sources (strongest signals)
  • Contradictions between sources (note them explicitly)
  • Top 3-5 actionable insights
  • Specific names: product names, @handles, subreddits, tools mentioned by real users
Anti-hallucination rule: If a source says "ClawdBot" and your prior knowledge maps this to something else, report what the research says. Do not conflate based on similarity to known entities.
When all findings are captured and cross-source patterns identified, proceed to STEP 4.
完全基于实际研究输出合成内容，而非依赖先验知识。
根据互动量加权，因为互动量代表了群体用户信号的强度——一条有2000个赞的帖子比无互动数据的文章更能反映真实共识：
  1. X帖子 — 互动量（点赞+转发）越高权重越大
  2. Reddit帖子 — 权重高；互动量=点赞数+评论数
  3. YouTube字幕 — 若可用则权重高（高密度、人工验证的信号）
  4. 网页内容 — 权重较低；无互动数据
识别：
  • 出现在≥2个来源中的模式（最强信号）
  • 来源之间的矛盾（需明确标注）
  • 排名前3-5的可操作见解
  • 具体名称：真实用户提及的产品名、@账号、子版块、工具
防幻觉规则：如果来源提到“ClawdBot”，而你的先验知识对应其他事物，需如实报告研究结果，不要基于相似性混淆已知实体。
捕获所有发现并识别跨来源模式后，进入步骤4。

STEP 4: Output

步骤4：输出

If QUERY_TYPE = RECOMMENDATIONS

如果QUERY_TYPE = RECOMMENDATIONS

🏆 Most mentioned:

[Name] — {N}x mentions
Use Case: [what it does]
Sources: @handle1, r/sub1, [site name]

[Name] — {N}x mentions
...

Notable: [items with 1-2 mentions]
Every item needs a real Sources line with @handles or subreddit names from the research output.
🏆 提及最多的内容：

[名称] — 被提及{N}次
使用场景：[功能描述]
来源：@handle1, r/sub1, [网站名称]

[名称] — 被提及{N}次
...

值得关注：[被提及1-2次的内容]
每个条目都需要包含来自研究输出的真实来源行，包括@账号或子版块名称。

If QUERY_TYPE = PROMPTING / NEWS / GENERAL

如果QUERY_TYPE = PROMPTING / NEWS / GENERAL

What I learned:

**{Finding 1}** — [1-2 sentences, per @handle or r/sub]

**{Finding 2}** — [1-2 sentences, per @handle or r/sub]

KEY PATTERNS:
1. [Pattern] — per @handle
2. [Pattern] — per r/sub
3. [Pattern] — per [YouTube channel]
Citation priority: @handles > subreddits > YouTube channels > web sites. Never cite raw URLs — use names and handles only. When a web article and an X post say the same thing, cite the X post.
研究发现：

**{发现1}** — [1-2句话，来源为@handle或r/sub]

**{发现2}** — [1-2句话，来源为@handle或r/sub]

核心模式：
1. [模式] — 来源：@handle
2. [模式] — 来源：r/sub
3. [模式] — 来源：[YouTube频道]
引用优先级：@账号 > 子版块 > YouTube频道 > 网站。绝不引用原始URL——仅使用名称和账号。当网页文章和X帖子内容相同时，引用X帖子。

Stats block (always shown, right before invitation)

统计模块（始终显示，位于邀请语之前）

Calculate real totals from the research output — never estimate.
---
✅ Research complete!
├─ 🟠 Reddit:  {N} threads │ {N} upvotes │ top: r/{sub1}, r/{sub2}
├─ 🔵 X:       {N} posts │ {N} likes │ top: @{handle1}, @{handle2}
├─ 🔴 YouTube: {N} videos │ {N} views │ {N} transcripts read
├─ 🌐 Web:     {N} pages
└─ ⚙️  Sources: {comma-separated list of sources that returned results}
---
Omit any line where the source was unavailable or returned 0 results. Use tree characters 
├─
└─
│
exactly — no plain dashes.
根据研究输出计算真实总数——绝不估算。
---
✅ 研究完成！
├─ 🟠 Reddit:  {N}条帖子 │ {N}个点赞 │ 顶级子版块: r/{sub1}, r/{sub2}
├─ 🔵 X:       {N}条帖子 │ {N}个点赞 │ 顶级账号: @{handle1}, @{handle2}
├─ 🔴 YouTube: {N}个视频 │ {N}次播放 │ 已读取{N}份字幕
├─ 🌐 网页:     {N}个页面
└─ ⚙️  来源: {返回结果的来源逗号分隔列表}
---
省略来源不可用或返回0结果的行。 严格使用树形字符
├─
└─
│
——不要使用普通短横线。

Invitation (always last — specific, never generic)

邀请语（始终放在最后——需具体，绝不通用）

Must reference real things from the research. Generic suggestions are a quality failure.
PROMPTING:
I'm now an expert on {TOPIC} for {TARGET_TOOL}. What do you want to make? For example:
- [specific idea based on technique people are actually using]
- [trending approach from the research data]
- [riff on what users are actually creating]

Describe your vision and I'll write a ready-to-paste prompt.
RECOMMENDATIONS:
I'm now an expert on {TOPIC}. Want to go deeper?
- [Compare specific item A vs item B from results]
- [Why {specific item} is trending right now]
- [How to get started with {specific item}]
NEWS / GENERAL:
I'm now an expert on {TOPIC}. Some things you could ask:
- [Follow-up on the biggest finding from the data]
- [Implications or next steps based on what was found]
- [Comparison or deeper dive from a specific source]
必须引用研究中的真实内容。通用建议属于质量不合格。
PROMPTING场景：
我现在是{TOPIC}在{TARGET_TOOL}领域的专家。你想创建什么？例如：
- [基于实际使用技巧的具体想法]
- [研究数据中的热门方法]
- [基于用户实际创作的延伸想法]

描述你的需求，我会生成可直接复制使用的提示词。
RECOMMENDATIONS场景：
我现在是{TOPIC}领域的专家。想要深入了解吗？
- [对比结果中的具体产品A和产品B]
- [为什么{具体产品}现在流行]
- [如何开始使用{具体产品}]
NEWS / GENERAL场景：
我现在是{TOPIC}领域的专家。你可以询问：
- [针对数据中最大发现的后续问题]
- [基于研究结果的影响或下一步建议]
- [针对特定来源的对比或深入分析]

STEP 5: Wait, Then Respond

步骤5：等待用户回复

Stop after the stats + invitation block. Wait for the user to reply.
When they respond:
  • Question → Answer from the research. No new searches.
  • Go deeper → Elaborate using research findings.
  • Create something / prompt request → Write ONE prompt (see below). Never write a prompt when they asked a question.
输出统计模块+邀请语后停止。等待用户回复。
用户回复时：
  • 问题 → 基于研究数据回答，无需新搜索。
  • 深入了解 → 使用研究结果详细说明。
  • 创建内容/请求提示词 → 生成一个提示词（见下文）。用户提问时绝不生成提示词。

Writing a Prompt (when requested)

生成提示词（当用户请求时）

One prompt only. Structure:
  1. Role/context line — tool, style, purpose
  2. Core instruction — exact task with specific parameters grounded in research
  3. Quality modifiers — from what real users report actually working, per research
  4. Output spec — format, dimensions, tone, tool-specific requirements
Every element must come from the research. No generic filler.
仅生成一个提示词。结构：
  1. 角色/上下文行——工具、风格、目的
  2. 核心指令——基于研究的具体任务和参数
  3. 质量修饰符——来自研究中真实用户反馈的有效内容
  4. 输出规范——格式、维度、语气、工具特定要求
所有元素必须来自研究内容，无通用填充内容。

Resources

资源

references/

references/

sources.md
— setup instructions for each source (reddit-cli auth, bird auth, yt-dlp install, brave-search setup).
sources.md
— 各来源的设置说明（reddit-cli认证、bird认证、yt-dlp安装、brave-search设置）。