academic-research-mapper

What this skill does

# Research Landscape Mapper — Understand a Field Before You Build or Write

You have access to the TinyFish CLI (`tinyfish`), a tool that runs browser automations from the terminal using natural language goals. This skill uses it to search arXiv, Semantic Scholar, and Google Scholar in parallel, then synthesizes results into a structured landscape report with identified gaps.

## Pre-flight Check (REQUIRED)

Before making any TinyFish call, always run BOTH checks:

**1. CLI installed?**

bash/zsh:
```bash
which tinyfish && tinyfish --version || echo "TINYFISH_CLI_NOT_INSTALLED"
```

PowerShell:
```powershell
Get-Command tinyfish; tinyfish --version
```

If not installed, stop and tell the user:
> Install the TinyFish CLI: `npm install -g @tiny-fish/cli`

**2. Authenticated?**

```bash
tinyfish auth status
```

If not authenticated, stop and tell the user:

> You need a TinyFish API key. Get one at: https://agent.tinyfish.ai/api-keys
>
> Then authenticate:
>
> **Option 1 — CLI login (interactive):**
> ```
> tinyfish auth login
> ```
>
> **Option 2 — bash/zsh (Mac/Linux, current session):**
> ```bash
> export TINYFISH_API_KEY="your-api-key-here"
> ```
>
> **Option 3 — bash/zsh (persist across sessions, add to ~/.bashrc or ~/.zshrc):**
> ```bash
> echo 'export TINYFISH_API_KEY="your-api-key-here"' >> ~/.zshrc
> source ~/.zshrc
> ```
>
> **Option 4 — PowerShell (current session only):**
> ```powershell
> $env:TINYFISH_API_KEY="your-api-key-here"
> ```
>
> **Option 5 — Claude Code settings:** Add to `~/.claude/settings.local.json`:
> ```json
> {
>   "env": {
>     "TINYFISH_API_KEY": "your-api-key-here"
>   }
> }
> ```

Do NOT proceed until both checks pass.

---

## What This Skill Does

Given a research topic (e.g. *"retrieval-augmented generation"* or *"protein structure prediction"*), this skill:

1. Searches **arXiv** for preprints sorted by most recent — capturing what is being worked on right now
2. Searches **Semantic Scholar** for papers ranked by relevance with citation counts — identifying what the field considers important
3. Searches **Google Scholar** for broad coverage including published venues not yet on arXiv

It then deduplicates across all three sources by title similarity, clusters papers into subtopics, and synthesizes findings into a structured landscape report: what is well-studied, what is emerging, and where the gaps are.

---

## Core Command

```bash
tinyfish agent run --url <url> "<goal>"
```

### Flags

| Flag | Purpose |
|------|---------|
| `--url <url>` | Target website URL for the agent to navigate |
| `--sync` | Wait for the full result before returning (required when you need output before next step) |
| `--async` | Submit and return a run ID immediately — use when firing parallel agents |
| `--pretty` | Human-readable formatted output for debugging |

---

## Keyword Strategy

The quality of results depends entirely on your search terms. Before running anything, derive 2–3 keyword variants from the topic. Each source has different vocabulary norms — academic terms work best on Semantic Scholar, shorter compressed terms work best on arXiv.

| Topic | Primary keywords | Variant A | Variant B |
|-------|-----------------|-----------|-----------|
| Retrieval-augmented generation | `retrieval augmented generation` | `RAG language model` | `dense retrieval QA` |
| Protein structure prediction | `protein structure prediction` | `AlphaFold protein folding` | `ab initio structure biology` |
| Neural architecture search | `neural architecture search` | `NAS automated machine learning` | `hyperparameter optimization deep learning` |
| Federated learning privacy | `federated learning` | `federated learning differential privacy` | `distributed training privacy` |

Use the primary keywords for the first parallel pass. If any source returns fewer than 5 results, run a second pass with the variant keywords on that source only.

---

## Step-by-Step Workflow

### Step 1 — Derive keywords and build URLs

Before running any agents, construct all three search URLs. Do this in your head or in a scratch note — do not make TinyFish calls yet.

**arXiv URL pattern:**
```
https://arxiv.org/search/?query=<keywords>&searchtype=all&order=-announced_date_first
```

**Semantic Scholar URL pattern:**
```
https://www.semanticscholar.org/search?q=<keywords>&sort=Relevance
```

**Google Scholar URL pattern:**
```
https://scholar.google.com/scholar?q=<keywords>&as_sdt=0%2C5&hl=en
```

Replace `<keywords>` with URL-encoded primary keywords (spaces become `+`).

---

### Step 2 — Search all three sources in parallel

Fire all three agents simultaneously. Do NOT wait for one to finish before starting the next.

**arXiv — sorted by most recent:**
```bash
tinyfish agent run --sync \
  --url "https://arxiv.org/search/?query=retrieval+augmented+generation&searchtype=all&order=-announced_date_first" \
  "Extract the top 15 search results as JSON: [{\"title\": str, \"authors\": [str], \"year\": str, \"abstract_snippet\": str (first 150 chars of abstract), \"arxiv_id\": str, \"url\": str}]. If a result has no year visible, use the submission date year."
```

**Semantic Scholar — sorted by relevance with citation counts:**
```bash
tinyfish agent run --sync \
  --url "https://www.semanticscholar.org/search?q=retrieval+augmented+generation&sort=Relevance" \
  "Extract the top 15 search results as JSON: [{\"title\": str, \"authors\": [str], \"year\": str, \"citation_count\": str, \"venue\": str, \"abstract_snippet\": str (first 150 chars), \"url\": str}]. Scroll down to load more results if fewer than 10 are visible."
```

**Google Scholar — broad coverage:**
```bash
tinyfish agent run --sync \
  --url "https://scholar.google.com/scholar?q=retrieval+augmented+generation&as_sdt=0%2C5&hl=en" \
  "Extract the top 15 search results as JSON: [{\"title\": str, \"authors\": [str], \"year\": str, \"citation_count\": str, \"venue\": str, \"snippet\": str, \"url\": str}]. Citation count appears after 'Cited by' — extract that number."
```

---

## Parallel Execution

All three source searches are fully independent. Always fire them simultaneously.

**Good — parallel calls (fire and wait):**
```bash
tinyfish agent run --sync \
  --url "https://arxiv.org/search/?query=retrieval+augmented+generation&searchtype=all&order=-announced_date_first" \
  "Extract the top 15 results as JSON: [{\"title\": str, \"authors\": [str], \"year\": str, \"abstract_snippet\": str, \"arxiv_id\": str, \"url\": str}]" > /tmp/arxiv_results.json &

tinyfish agent run --sync \
  --url "https://www.semanticscholar.org/search?q=retrieval+augmented+generation&sort=Relevance" \
  "Extract the top 15 results as JSON: [{\"title\": str, \"authors\": [str], \"year\": str, \"citation_count\": str, \"venue\": str, \"abstract_snippet\": str, \"url\": str}]" > /tmp/s2_results.json &

tinyfish agent run --sync \
  --url "https://scholar.google.com/scholar?q=retrieval+augmented+generation&as_sdt=0%2C5&hl=en" \
  "Extract the top 15 results as JSON: [{\"title\": str, \"authors\": [str], \"year\": str, \"citation_count\": str, \"venue\": str, \"snippet\": str, \"url\": str}]" > /tmp/scholar_results.json &

wait
echo "All three sources complete."
```

**Bad — sequential calls:**
```bash
# Do NOT do this — triples the wait time for no benefit
tinyfish agent run --url "https://arxiv.org/..." "search arxiv, then also search semantic scholar, then also search google scholar"
```

Each source is always its own separate call. Never combine them into one goal.

---

### Step 3 — Handle sparse results (if needed)

After the parallel run completes, check each result set. If any source returned fewer than 5 papers, run a second pass on that source with variant keywords:

```bash
# Example: arXiv returned only 3 results for primary keywords
tinyfish agent run --sync \
  --url "https://arxiv.org/search/?query=RAG+language+model&searchtype=all&order=-announced_date_first" \
  "Extract the top 15 results as JSON: [{\"title\": str, \