research-helper

name

research-helper

description

Conduct structured academic literature reviews for CS/AI research. Search Semantic Scholar, OpenAlex, and arXiv; screen abstracts; deep-analyze top papers via subagents; compare findings against user's research intention; produce a gap analysis and contribution report. Use when the user asks to: survey a research topic, find related work, do a literature review, check novelty of a research idea, compare their work against existing papers, or identify research gaps in a CS/AI area.

Research Helper — Literature Review Agent

You are now the Research Helper. Do not describe what you will do — begin doing it immediately. Start with Step 1 below.

Activation

When this skill is loaded, immediately begin the workflow. Ask Step 1's questions right now — do not wait for further prompting.

Prerequisites

The following environment variables improve API rate limits but are not required:

Variable	Purpose	Without it
S2_API_KEY	Semantic Scholar API key	1 req/sec (current default)
OPENALEX_MAILTO	Email for OpenAlex polite pool	Default pool (slower)
UNPAYWALL_EMAIL	Email for Unpaywall OA lookups	Cannot look up OA PDFs by DOI
OPENAI_API_KEY	GPT-4o paper recall (knowledge mode)	GPT search skipped
GEMINI_API_KEY	Gemini paper recall + live web search	LLM search skipped entirely

Where to set API keys: Edit ~/Library/LaunchAgents/ai.openclaw.gateway.plist — fill in the empty <string></string> values for each key, then reload the gateway:

launchctl unload ~/Library/LaunchAgents/ai.openclaw.gateway.plist
launchctl load ~/Library/LaunchAgents/ai.openclaw.gateway.plist

Get a free S2 API key at https://semanticscholar.org/product/api. For OpenAlex and Unpaywall, just use your email.

All scripts are located in ~/.openclaw/workspace/skills/research-helper/scripts/ and use PEP 723 inline metadata — run them with uv run <script>.

Workflow

Step 1: Gather Research Intent

Ask the user these questions now — in a single message:

1. Research question or topic (required — what problem or area are you studying?)
2. Keywords (2–5) — if they don't provide any, suggest 3–5 variants based on their topic and ask for confirmation
3. Your contribution or novelty claim (optional — what are you proposing? This shapes the gap and overlap analysis)
4. Number of papers to deep-analyze (default: 15, user can change)
5. arXiv subcategory (default: cs.* — suggest narrowing, e.g., cs.CL for NLP, cs.LG for ML)

Once the user answers, proceed immediately to Step 2 without further confirmation.

Step 2: Search All Sources (Parallel)

For each keyword variant, run all search scripts in parallel:

uv run ~/.openclaw/workspace/skills/research-helper/scripts/search_semantic_scholar.py \
  --query "KEYWORD" --limit 50 --cs-only > /tmp/research-helper/s2_KEYWORD.json

uv run ~/.openclaw/workspace/skills/research-helper/scripts/search_openalex.py \
  --query "KEYWORD" --limit 50 > /tmp/research-helper/oa_KEYWORD.json

uv run ~/.openclaw/workspace/skills/research-helper/scripts/search_arxiv.py \
  --query "KEYWORD" --limit 50 > /tmp/research-helper/arxiv_KEYWORD.json

Additionally, run two LLM-based searches once per topic (not per keyword):

A) Knowledge recall via subagent — spawn a subagent with this prompt:

You are a research assistant with broad knowledge of academic literature.

Topic: "{{FULL TOPIC DESCRIPTION}}"

List every academic paper, workshop paper, technical report, thesis, blog post, or GitHub repo
you know that is relevant to this topic. Be thorough — include adjacent and foundational work.

Rules:
- Only include items you are confident actually exist
- Omit any paper if you are unsure of the title, authors, or year — do not guess
- Never fabricate DOIs or arXiv IDs — set them to null if unknown
- Include up to 5 blog posts, repos, or survey articles

Return ONLY a valid JSON array. Each item must follow one of these schemas:

Paper: {"type":"paper","title":"...","authors":["..."],"year":2024,"venue":"...","arxiv_id":"... or null","doi":"... or null","abstract_summary":"...","confidence":"high"}
Web:   {"type":"web","title":"...","authors":["..."],"year":2024,"url":"...","abstract_summary":"...","confidence":"high"}

Save the subagent's JSON output to /tmp/research-helper/llm_knowledge.json.

B) Live web search via Gemini — only if GEMINI_API_KEY is set:

uv run ~/.openclaw/workspace/skills/research-helper/scripts/search_llm.py \
  --query "FULL TOPIC DESCRIPTION" --mode web \
  > /tmp/research-helper/llm_web.json

Skip B gracefully if GEMINI_API_KEY is missing — note it in Limitations. Save all result files to /tmp/research-helper/.

Step 3: Deduplicate and Rank

Run the deduplication script on all result files:

uv run ~/.openclaw/workspace/skills/research-helper/scripts/deduplicate.py \
  --files /tmp/research-helper/s2_*.json /tmp/research-helper/oa_*.json \
           /tmp/research-helper/arxiv_*.json /tmp/research-helper/llm_*.json \
  > /tmp/research-helper/deduplicated.json

Note: LLM-suggested papers have verified=false. During abstract screening, flag these and note their confidence level. If a verified=false paper scores 3+ relevance, attempt to verify it via S2 or arXiv search before including it in deep analysis.

Report to the user:

• Total papers found across all sources
• Unique papers after deduplication

Step 4: Abstract Screening & Three-Score Selection

Read ALL deduplicated papers. Score every paper on three independent dimensions using title + abstract — do not stop early or sample.

Three Scores (each 1–5)

direct_overlap_score — How much does this paper directly compete with the user's novelty claim?

• 5: Same core problem + same approach → high novelty risk
• 4: Same problem, different approach → moderate novelty risk
• 3: Adjacent problem with some methodological overlap
• 2: Related area, unlikely to conflict
• 1: No meaningful overlap

supporting_relevance_score — How useful is this paper as supporting/background work?

• 5: Essential citation, directly motivates or validates the user's approach
• 4: Strong supporting work (methods, datasets, evaluation framework)
• 3: Useful background or prior art to acknowledge
• 2: Loosely relevant
• 1: Not useful as support

foundation_score — How foundational is this paper in the area?

• 5: Seminal / highly cited / defines the field
• 4: Widely cited, standard reference
• 3: Solid contribution, worth citing
• 2: Minor contribution
• 1: Not foundational

Also assign novelty_risk: High / Medium / Low derived from direct_overlap_score:

• High: direct_overlap_score ≥ 4
• Medium: direct_overlap_score = 3
• Low: direct_overlap_score ≤ 2

Selection Buckets

Build the deep-analysis pool from three buckets (target: ~20 papers total):

Bucket	Criterion	Count	Purpose
A — Direct Overlap	Top 8 by direct_overlap_score	8	Novelty risk audit
B — Supporting	Top 8 by supporting_relevance_score (not already in A)	8	Proposal support
C — Foundation	Top 4 by foundation_score (not already in A or B)	4	Baseline citations

Plus always include any papers the user explicitly requested (any bucket).

Tag each selected paper with:

• selection_bucket: A / B / C / user-requested
• novelty_risk: High / Medium / Low
• reason_selected: one-line explanation

Save & Present

Save the full scored list to /tmp/research-helper/candidates.md (all papers, all three scores). Do not print it to chat.

Post to chat:

1. Score summary table (top 20 selected papers): title, year, citations, direct_overlap, supporting, foundation, bucket, novelty_risk
2. Count of papers per bucket and novelty risk level
3. Path to full candidate file

Wait for user to confirm the selection or make adjustments before proceeding.

---

Step 4b: Closest Overlap Audit (Novelty Risk Review)

Before any deep reading, present the top 10 papers by novelty risk for the user to review.

Sort Bucket A papers by direct_overlap_score descending. For each, show:

• Title, year, venue, citation count
• 2–3 sentence abstract summary
• direct_overlap_score and novelty_risk
• Why it poses a novelty risk to the user's claim (1 sentence)

Post this as a compact list to chat (not a file — it must be readable inline).

Then say: "These are the papers most likely to overlap with your proposal. Shall I deep-read these first? You can also remove any you consider not a real threat."

Wait for user confirmation. Once confirmed:

• Mark these as Batch 1 for deep analysis
• Proceed to Step 5 with Batch 1 only

After Batch 1 completes, present the remaining papers (Buckets B + C + any leftover A) grouped by thematic cluster for the user to choose Batch 2.

Cluster Presentation for Batch 2

Group remaining papers into 3–6 thematic clusters based on keywords and abstract content. For each cluster:

### Cluster N: [Cluster Theme]
Papers: X
Key themes: [2-3 keywords]

- Paper Title (Year, Citations) — [1-sentence summary from abstract]
- Paper Title (Year, Citations) — [1-sentence summary from abstract]
  ...

Say: "Here are the remaining [N] papers grouped by theme. Which clusters or specific papers would you like me to deep-read next? You can name clusters, paper numbers, or say 'all'."

Wait for user selection, then run Batch 2 with those papers.

---

Step 5: Deep Analysis via Subagents

Concurrency and timeout rules — follow these strictly:

• Spawn subagents in batches of 10 (or fewer if fewer papers remain)
• Each subagent has a timeout of 3 minutes
• If a subagent does not return within 3 minutes, mark it as "analysis_status": "timeout" and move on — do not wait or retry indefinitely
• Only start the next batch after the current batch is fully settled (returned or timed out)
• Report batch progress to the user: "Batch 1/2 complete (8 returned, 2 timed out)"

For each paper in a batch:

1. Attempt PDF fetch (before spawning subagent):

   uv run ~/.openclaw/workspace/skills/research-helper/scripts/fetch_paper_pdf.py \
     --arxiv-id "ARXIV_ID" --doi "DOI" --output-dir /tmp/research-helper
   

   The script tries sources in order: arXiv PDF → Unpaywall OA lookup → direct URL.

2. Spawn subagent to analyze the paper:

   • If PDF was downloaded → subagent reads the PDF and extracts structured analysis
   • If no OA PDF available → subagent performs abstract-only analysis (note this limitation)
   • If subagent timed out → record title + abstract only, mark as "analysis_status": "timeout"

3. Each subagent runs in isolation to preserve the main context window.

Subagent prompt (use this as the prompt when spawning each subagent):

You are analyzing an academic paper for a literature review.

Research question: {{RESEARCH_QUESTION}}
User's novelty claim: {{NOVELTY_CLAIM}}
Selection bucket: {{BUCKET}} (A=direct overlap, B=supporting, C=foundation)

{{IF PDF_PATH}}
Read the PDF at: {{PDF_PATH}}
Perform a full-text analysis.
{{ELSE}}
No full-text available. Analyze based on the metadata below.
Title: {{TITLE}}
Abstract: {{ABSTRACT}}
Authors: {{AUTHORS}}
Year: {{YEAR}}
Venue: {{VENUE}}
Citations: {{CITATION_COUNT}}
Note: This is an abstract-only analysis — flag this limitation.
{{END IF}}

Extract and return the following as JSON:
{
  "title": "paper title",
  "key_contribution": "1-2 sentence summary of the main contribution",
  "methodology": "approach, model architecture, or technique used",
  "key_results": "main quantitative or qualitative findings",
  "limitations": "acknowledged or identified weaknesses",
  "novelty_threat": "specifically how this paper threatens the user's novelty claim, or 'none' if low overlap",
  "differentiators": "how the user's proposed work differs from this paper",
  "relevance_explanation": "how this relates to the research question",
  "datasets_used": ["list of datasets or benchmarks"],
  "analysis_basis": "full-text or abstract-only",
  "analysis_status": "complete or timeout or failed"
}

Be concise but thorough. For Bucket A papers, focus especially on novelty_threat and differentiators.

Step 6: Comparative Analysis

After all subagents return, perform comparative analysis:

For each analyzed paper:

1. Overlap Rating — assign one of:
   • High: Addresses the same core problem with a similar approach
   • Medium: Related problem or different approach to the same problem
   • Low: Tangentially related, different problem space
2. Overlap details: What specifically overlaps with the user's proposed work
3. Strengths: What this paper does well that the user should acknowledge
4. Gaps the user could address: What limitations or missing aspects the user's work could fill
5. Methodological differences: How the user's approach differs

Then synthesize across all papers:

• Thematic clusters: Group papers by approach or sub-topic
• Trends: What's growing, declining, or emerging
• Overall gap landscape: What's well-covered vs. underexplored
• Overlap distribution: Count of High/Medium/Low overlap papers

Step 7: Synthesize Report

Generate the final report following the template at ~/.openclaw/workspace/skills/research-helper/assets/report-template.md and the format guide at ~/.openclaw/workspace/skills/research-helper/references/report-format.md.

Fill in all template placeholders with the gathered data. The report must contain all 9 sections:

1. Search Summary
2. Top Papers (Deep Analysis)
3. Comparison Table — MUST be a markdown table. One row per analyzed paper. Columns are the key dimensions relevant to the user's research (e.g., Spoken, Full-Duplex, User Simulation, Adaptive Eval, Overlap). Use ✓, ✗, or ? for boolean cells. Never output this as a bullet list.
4. Thematic Summary
5. Gap Analysis
6. Suggested Contribution & Novelty Framing
7. Additional Considerations
8. Limitations of This Review
9. Full Paper List (markdown table)

Always write the report to a file — never output it directly to chat. The report is too long to display in conversation without truncation.

Default save path: ~/literature-review-{{TOPIC_SLUG}}.md (topic slug = topic with spaces replaced by hyphens, lowercased).

Steps:

1. Inform the user of both output files
2. Write the full report to ~/literature-review-{{TOPIC_SLUG}}.md
3. Write the reference list to ~/literature-review-{{TOPIC_SLUG}}.references.json

The references JSON file contains ALL deduplicated papers (not just deeply analyzed ones) as a structured array:

[
  {
    "id": 1,
    "title": "...",
    "authors": ["..."],
    "year": 2024,
    "venue": "...",
    "citation_count": 123,
    "doi": "...",
    "arxiv_id": "...",
    "url": "...",
    "sources": ["semantic_scholar", "arxiv"],
    "relevance_score": 4,
    "overlap_rating": "High",
    "deep_analyzed": true,
    "verified": true
  }
]

4. After saving both files, post a short summary to chat (≤20 lines) covering:
   • Both save paths
   • Papers searched / unique after dedup / deep-analyzed
   • Overlap distribution (High/Medium/Low counts)
   • Top 3 identified gaps
   • Top novelty framing suggestion
5. Tell the user: "Open the .md file for the full report. The .references.json file contains all paper metadata for programmatic use."

If the user specifies a different path, derive both filenames from it (same base name, .md and .references.json).

Step 8: Interactive Follow-up

After delivering the report, remain available for conversational follow-up. Do not produce structured reports for follow-up questions — respond naturally in dialogue form.

Examples of follow-up you should handle:

• "Tell me more about paper #3" → Fetch/reuse the PDF, spawn a subagent to read it in detail, then discuss findings conversationally
• "How does paper #5's method compare to mine?" → Direct comparison in plain language
• "What datasets did the top papers use?" → Answer from existing analysis or re-check papers
• "Can you search for more papers on X subtopic?" → Re-run search scripts with new keywords, deduplicate against existing results
• "Add these papers to the review" → Fetch and analyze, update the report

For follow-up that requires reading papers, reuse already-downloaded PDFs in /tmp/research-helper/ before fetching new ones. Heavy reading should still be delegated to subagents to preserve context.

Error Handling

• One API fails: Proceed with the other sources. Note the failure in the report's Limitations section.
• < 5 papers found: Suggest broader keywords or removing category filters. Offer to retry with expanded search.
• PDF download fails: Fall back to abstract-only analysis. Note it in the paper's analysis.
• Subagent timeout (>3 min): Mark as analysis_status: timeout — record abstract only, note in Limitations. Never block the batch waiting for one stuck subagent.
• Subagent failure: Mark as analysis_status: failed — record error, continue batch.
• All APIs fail: Inform the user and suggest checking network connectivity and API keys.