research

name	research
description	Comprehensive research skill using Zai MCP web search and native Claude Code tools

Research Skill - Multi-Agent Ralph v2.88

Smart Research with Zai MCP Integration - Leverages Zai MCP for comprehensive web search, article fetching, and content analysis.

Based on the principle that research should be thorough, well-sourced, and actionable.

Quick Start

# Via skill invocation
/research Latest React 19 patterns and best practices

# Via CLI
ralph research "TypeScript 5.0 performance optimizations"

# Focus on specific sources
/research "Next.js App Router" --sources github,docs

Key Changes in v2.88

• Zai MCP as primary: Uses mcp__web-search-prime__webSearchPrime instead of Minimax
• Native WebFetch: Uses Claude Code's native WebFetch for content retrieval
• Multi-source fetching: Supports GitHub, CSDN, Juejin, Linux.do article extraction
• Model-agnostic: Works with any model configured in settings.json

Available Tools

1. mcp__web-search-prime__webSearchPrime (Primary Search)

Purpose: Comprehensive web search with high-quality results

Parameters:

search_query: string      # The search query (max 70 characters recommended)
content_size: string      # "medium" (400-600 words) or "high" (2500 words)
location: string          # "cn" (Chinese) or "us" (non-Chinese)
search_recency_filter: string  # oneDay, oneWeek, oneMonth, oneYear, noLimit
search_domain_filter: string   # Optional: limit to specific domain

Optimal Patterns:

# Good: Specific, time-bounded
mcp__web-search-prime__webSearchPrime:
  search_query: "React 19 useOptimistic hook examples 2025"
  search_recency_filter: "oneMonth"
  content_size: "medium"

# Good: Error-focused debugging
mcp__web-search-prime__webSearchPrime:
  search_query: "TypeError cannot read property undefined Next.js 15"
  location: "us"

# Good: Documentation search
mcp__web-search-prime__webSearchPrime:
  search_query: "Claude Code MCP configuration"
  search_domain_filter: "docs.anthropic.com"

# Bad: Too vague
mcp__web-search-prime__webSearchPrime:
  search_query: "javascript"  # Too broad, be specific

2. Native WebFetch (Content Retrieval)

Purpose: Fetch and analyze full web page content

When to Use:

• Deep-dive into specific articles found via search
• Documentation reading
• GitHub repository exploration
• API documentation analysis

3. mcp__web-search__fetchGithubReadme

Purpose: Extract README content from GitHub repositories

Parameters:

url: string  # GitHub repository URL

Example:

mcp__web-search__fetchGithubReadme:
  url: "https://github.com/vercel/next.js"

4. mcp__web-reader__webReader

Purpose: Convert URL content to LLM-friendly format

Parameters:

url: string              # URL to fetch and read
return_format: string    # "markdown" (default) or "text"
retain_images: boolean   # Keep images (default: true)
with_links_summary: boolean  # Include links summary
with_images_summary: boolean # Include images summary

Example:

mcp__web-reader__webReader:
  url: "https://docs.anthropic.com/claude/docs"
  return_format: "markdown"
  with_links_summary: true

5. Chinese Article Fetchers

mcp__web-search__fetchCsdnArticle

url: string  # CSDN article URL

mcp__web-search__fetchJuejinArticle

url: string  # Juejin article URL

mcp__web-search__fetchLinuxDoArticle

url: string  # Linux.do post URL

Research Workflow (5 Steps)

Step 1: INITIAL SEARCH

# Broad search first
mcp__web-search-prime__webSearchPrime:
  search_query: "${TOPIC} overview guide 2025"
  content_size: "high"
  search_recency_filter: "oneMonth"

Step 2: REFINE & DEEPEN

# Targeted follow-up searches based on initial results
mcp__web-search-prime__webSearchPrime:
  search_query: "${SPECIFIC_ASPECT} implementation ${TOPIC}"
  search_recency_filter: "oneWeek"

Step 3: FETCH CONTENT

# For documentation sites
mcp__web-reader__webReader:
  url: "${DOC_URL}"
  return_format: "markdown"

# For GitHub repos
mcp__web-search__fetchGithubReadme:
  url: "${REPO_URL}"

Step 4: SYNTHESIZE

Compile findings into structured report:

• Summary: Key findings in 2-3 sentences
• Sources: All URLs with brief descriptions
• Details: Relevant code snippets and explanations
• Recommendations: Suggested approach based on research
• Related Topics: Areas for further exploration

Step 5: PERSIST

Save research to memory for future reference:

ralph ledger save research "Research on ${TOPIC}: [key findings]"

Research Templates

Technology Research

# 1. Official docs
mcp__web-search-prime__webSearchPrime:
  search_query: "${TECH} official documentation"
  search_domain_filter: "official-site.com"

# 2. Best practices
mcp__web-search-prime__webSearchPrime:
  search_query: "${TECH} best practices 2025"

# 3. GitHub examples
mcp__web-search-prime__webSearchPrime:
  search_query: "${TECH} examples github"

Error Research

# 1. Exact error message
mcp__web-search-prime__webSearchPrime:
  search_query: "${ERROR_MESSAGE} ${FRAMEWORK}"

# 2. Stack Overflow solutions
mcp__web-search-prime__webSearchPrime:
  search_query: "site:stackoverflow.com ${ERROR_MESSAGE}"

# 3. GitHub issues
mcp__web-search-prime__webSearchPrime:
  search_query: "site:github.com ${ERROR_MESSAGE}"

Security Research

# 1. CVE lookup
mcp__web-search-prime__webSearchPrime:
  search_query: "CVE ${VERSION} vulnerability"

# 2. Security advisories
mcp__web-search-prime__webSearchPrime:
  search_query: "${PACKAGE} security advisory 2025"

# 3. Exploit database
mcp__web-search-prime__webSearchPrime:
  search_query: "${CVE_ID} exploit"

Integration with Ralph Loop

# Research phase in orchestrator
Task:
  prompt: |
    Research latest patterns for $TOPIC using mcp__web-search-prime__webSearchPrime.
    Use mcp__web-reader__webReader for detailed content.
    Compile findings into structured report with sources.

# Code research
Task:
  prompt: |
    Search for $TOPIC implementation examples on GitHub.
    Use mcp__web-search__fetchGithubReadme to analyze repositories.
    Identify best patterns and anti-patterns.

Comparison: Zai MCP vs Minimax

Feature	Zai MCP	Minimax MCP
Web Search	webSearchPrime	web_search
Content Quality	High (2500 words max)	Medium
Chinese Content	Excellent (CSDN, Juejin)	Basic
GitHub Integration	fetchGithubReadme	None
URL Reader	webReader	None
Domain Filtering	Yes	No
Recency Filter	Yes	No
Cost	Free (no API key)	~$0.008/query

When to Use Each Tool

Scenario	Recommended Tool
General web search	mcp__web-search-prime__webSearchPrime
Chinese tech articles	mcp__web-search__fetchCsdnArticle, fetchJuejinArticle
GitHub repositories	mcp__web-search__fetchGithubReadme
Documentation reading	mcp__web-reader__webReader
Real-time data	Native WebFetch
Code search in repo	Grep, Glob (not web search)

Anti-Patterns

• Too broad queries: "javascript" - always be specific
• Skipping sources: Always cite URLs
• Ignoring recency: Use recency filter for fast-moving topics
• Single source: Cross-reference multiple sources
• No synthesis: Don't just list results, analyze them
• Missing memory: Save learnings for future sessions

Output Format

Structure research reports as:

# Research: [TOPIC]

**Date**: YYYY-MM-DD
**Sources**: X articles analyzed

## Summary
[2-3 sentence key findings]

## Key Findings
1. [Finding 1]
   - Source: [URL]
   - Details: [Explanation]

2. [Finding 2]
   - Source: [URL]
   - Details: [Explanation]

## Code Examples
```language
// Relevant code snippets

Recommendations

1. [Recommendation 1]
2. [Recommendation 2]

Related Topics

• [Topic for further research]

Sources

1. Title - [Brief description]
2. Title - [Brief description]

## CLI Commands

```bash
# Standard research
ralph research "topic description"

# With source focus
ralph research "topic" --sources github,docs

# Chinese content
ralph research "topic" --location cn

Related Skills

• /orchestrator - Full orchestration with research phase
• /smart-fork - Pattern extraction from external repos
• /clarify - Requirement clarification with research

Agent Teams Integration (v2.88)

Optimal Scenario: B (Pure Custom Subagents)

Why Scenario B for Research

• Independent execution: Research is mostly self-contained
• Specialization > Coordination: Tool expertise matters more than inter-agent coordination
• Simpler setup: No team overhead for single-purpose research tasks
• Tool restrictions: ralph-researcher has specialized tools (WebSearch, WebFetch)

Scenario Analysis

Criterion	Weight	Score	Rationale
Coordination Need	25%	3/10	Research is independent
Specialization Need	25%	9/10	Specialized web tools required
Quality Gate Need	20%	5/10	Moderate validation needs
Tool Restriction Need	15%	8/10	Read-only tools important
Scalability	15%	7/10	Scales with topic complexity
Total	100%	7.5/10	Scenario B optimal

Workflow

# Scenario B: Direct spawn without TeamCreate
Task(subagent_type="ralph-researcher", prompt="Research ${TOPIC}")
→ Execute with specialized tools
→ Compile structured report
→ Return findings

Usage

Direct Spawn (Recommended):

Task:
  subagent_type: "ralph-researcher"
  prompt: |
    Research ${TOPIC} using:
    1. mcp__web-search-prime__webSearchPrime for initial search
    2. mcp__web-reader__webReader for content extraction
    3. mcp__web-search__fetchGithubReadme for GitHub repos
    Compile into structured report with all sources.

Parallel Research (Multiple Topics):

# Spawn multiple researchers for different topics
Task(subagent_type="ralph-researcher", prompt="Research React 19 features")
Task(subagent_type="ralph-researcher", prompt="Research TypeScript 5.5")
Task(subagent_type="ralph-researcher", prompt="Research Node.js performance")
# Results aggregated independently

References

• Zai MCP Documentation
• Claude Code Skills Documentation
• Web Search Tool Documentation