Claude Skill

semantic-scholar-deep

Deep research over the Semantic Scholar Graph API. Covers endpoints missing from allenai's lookup skill — paper references (backward citations), recommendations, batch paper lookup (up to 500 IDs), snippet search, and multi-hop citation graph traversal (BFS forward/backward). Use

LLM Mart · 0 points · 6 views 0 listing impressions 0 install-command copies
Download codealive-ai-ai-driven-development-skills_semantic-scholar-deep-68a302a.zip · 20 KB

Install

skills CLI npx skills add https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/semantic-scholar-deep
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install codealive-ai-ai-driven-development@llmmart
Git git clone https://github.com/CodeAlive-AI/ai-driven-development.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole codealive-ai/ai-driven-development collection as a plugin from our marketplace. Git is the plain clone.

README

semantic-scholar-deep

Deep research over the Semantic Scholar Graph API. Covers the endpoints missing from the official allenai/asta-plugins semantic-scholar-lookup skill — backward references, recommendations, batch lookup (up to 500 IDs per call), snippet full-text search, and multi-hop citation-graph BFS.

Install

npx skills add CodeAlive-AI/ai-driven-development@semantic-scholar-deep -g -y

Works anonymously out of the box — most endpoints (paper lookup, references, recommendations, batch) respond without an API key. The keyword /paper/search endpoint is heavily rate-limited on the anonymous tier, so for large sweeps set SEMANTIC_SCHOLAR_API_KEY (request one at https://www.semanticscholar.org/product/api#api-key).

Prerequisites

This skill stands alone for scripts-only usage (invoke the Python CLIs directly). For the full deep-research pipeline (orchestrated by the bundled subagent, see below), you also need:

Tool Why How
Exa MCP Neural paper discovery across arXiv / OpenReview / PubMed / bioRxiv — the S2 search endpoint is too rate-limited to be the primary discovery path claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"
allenai semantic-scholar-lookup skill First-party asta papers CLI for fast metadata + forward citations (complements our backward-references / recommendations coverage) npx skills add "allenai/asta-plugins@Semantic Scholar Lookup" -g -y
Python 3.8+ Scripts are stdlib-only, no pip install Usually already present

Without the above, the bundled subagent falls back to what it can reach (S2-only), but Exa dramatically improves discovery quality and freshness.

Quick start

Inline usage (one specific endpoint):

> Get the references that DOI:10.18653/v1/N18-3011 cites
> Recommend 20 papers related to this paperId
> Batch-resolve these 30 arXiv IDs: 2404.18496 2502.02757 ...
> Build a citation graph of depth 2 around paperId X

Delegated usage (multi-step research via the bundled subagent):

> Find recent papers on LLM code review
> Do a literature review on retrieval-augmented generation since 2024
> Novelty check: is my idea <X> already published?

What it ships

Python CLIs (scripts/)

  • ss_client.py — stdlib-only S2 client with exponential backoff on HTTP 429/5xx. Subcommands: search, paper, citations, references, recommendations, batch, author-search, author, author-papers, snippets.
  • citation_graph.py — BFS traversal around a seed paper. Options: --direction forward|backward|both, --depth N, --max-nodes N. Outputs JSON with nodes + edges, designed for summarization rather than in-context dumping.

References (references/)

  • endpoints.md — complete field reference, query-parameter list, and ID-format matrix for every endpoint.
  • workflows.md — 5 ready-made deep-research patterns: literature review from a topic, citation graph around a seed, novelty check, author trajectory, evidence for a claim.

Bundled subagent (agents/deep-paper-researcher.md, optional)

A paired subagent definition for token-isolated research. Manually install once:

cp ~/.agents/skills/semantic-scholar-deep/agents/deep-paper-researcher.md ~/.claude/agents/

Then restart the session. Features:

  • Input validation — today's date anchoring + caller-paraphrased-window detection (catches cases where the calling agent translates "recent" into an invented "2024-2026" window)
  • Freshness Mode classifier — RECENT (default last 6 months, sort by publication date), FOUNDATIONAL (sort by citations, no date floor), MIXED (two slices side-by-side)
  • Sort-then-tiebreak ranking — never multiplies citations × recency into a single score, so fresh papers with zero citations aren't buried under older high-citation ones
  • Compact report format with explicit Anchor date / Mode / Window header — readers can see and redirect the choice

Key design decisions

  • Stdlib only — no requests dependency. Works on any Python 3.8+ install.
  • Backoff over hard-failure — HTTP 429 / 5xx get exponential retry up to 30s, honoring Retry-After. Anonymous tier is usable for small graphs.
  • Progressive disclosure — SKILL.md stays under 150 lines; deep endpoint-by-endpoint docs and workflow templates live in references/.
  • Token hygiene — scripts emit raw JSON to stdout by design. For graphs >50 nodes, use --output to write to disk and summarize via jq/python3 rather than piping full payloads into the agent's context.
  • Not a discovery engine — keyword search works but is the weakest endpoint on the anonymous tier; the bundled subagent delegates discovery to Exa MCP and uses S2 for structured expansion (references, recommendations, batch).

Rate limits

Endpoint Anonymous tier With API key
paper by ID ~1 RPS, reliable Much higher
references / recommendations ~1 RPS, reliable Much higher
batch (up to 500 IDs) ~1 RPS Much higher
search (keyword) Frequently 429 Reliable

The client respects Retry-After and does up to 5 retries with exponential backoff (1→30s).

File structure

semantic-scholar-deep/
├── SKILL.md                       # Agent-facing instructions (dispatch rule, when to use)
├── README.md                      # This file
├── scripts/
│   ├── ss_client.py              # Full S2 API client (stdlib only)
│   └── citation_graph.py         # BFS traversal
├── references/
│   ├── endpoints.md              # Per-endpoint field and parameter reference
│   └── workflows.md              # 5 deep-research patterns
└── agents/
    └── deep-paper-researcher.md  # Optional paired subagent definition

License

MIT

Skill manifest

Semantic Scholar — Deep Research

Purpose: fill the gaps that semantic-scholar-lookup (allenai) leaves — references, recommendations, batch, and multi-hop citation-graph traversal.

Contents

Dispatch Rule (read first)

Two execution modes:

Inline (run the Bash scripts yourself)

Use when the user asks for one specific endpoint:

  • "get references of paper X" → ss_client.py references <id>
  • "recommendations for paper Y" → ss_client.py recommendations <id>
  • "batch-resolve these 30 DOIs" → ss_client.py batch ...
  • "find the snippet where X is said" → ss_client.py snippets "..."

Fast, cheap, no orchestration overhead.

Delegate to deep-paper-researcher subagent

Use when the task is multi-step or would otherwise flood the context:

  • Literature review on a topic
  • Citation graph / network analysis around a seed paper
  • Novelty check for an idea
  • State-of-the-art survey
  • Anything that requires merging Exa discovery + S2 graph + ranking

Mandatory prompt contents. The subagent runs in isolated context with no access to this conversation's system reminders. Include exactly these two things:

  1. Today's date — inline as Today is YYYY-MM-DD. Pull from the currentDate system-reminder field, or run date -I via Bash before delegating if it's missing. Never rely on training-data intuitions about the current year.
  2. User's request, verbatim — pass the user's original phrasing (topic + any freshness words like "современные / recent / классические / seminal" and any explicit dates like "since 2024"). Translate language if needed but do not paraphrase trigger words into date windows.

Do NOT do any of these:

  • Do NOT classify freshness yourself (RECENT/FOUNDATIONAL/MIXED). The subagent does that from the verbatim user request.
  • Do NOT invent a date window. If the user said "современные / recent / latest" without a year, the subagent defaults to last 6 months — don't preempt it with "2024-2026".
  • Do NOT drop the trigger words. The subagent relies on them to pick the right mode.

Call:

Agent(
  subagent_type="deep-paper-researcher",
  description="<3–5 word task>",
  prompt="Today is 2026-04-22.\n\nUser's request: найди современные 10 статей про AI Code Review на arXiv.\n\n<optional: output format hints, language preference>"
  # model: "opus"  ← add only when the user opts in (see below)
)

The subagent's Freshness Mode section handles classification; keep this layer thin.

Model selection (Sonnet default, Opus on demand)

The subagent's model frontmatter is sonnet — that's the default.

Override to Opus by passing model: "opus" to the Agent tool only if the user explicitly requests deeper reasoning. Triggers (any of):

  • English: "deep dive", "thorough", "rigorous", "use Opus", "high quality", "comprehensive", "exhaustive"
  • Russian: "глубокий/глубже", "тщательный/тщательно", "подробно", "в режиме Опус/Opus", "максимально качественно", "серьёзный ресерч"

Never auto-upgrade to Opus without a user signal — Sonnet handles the default literature-review workflow fine and costs less.

When to Use

Trigger this skill for:

  • Citation graph / network over a seed paper or topic
  • Backward references (what does this paper cite?) — not covered by allenai
  • Forward citations with pagination beyond 1000 results
  • Recommendations — related-paper discovery from a seed
  • Batch lookup — resolve 50-500 DOI/arXiv/CorpusId/S2 IDs in one call
  • Snippet search — find specific passages across the S2 corpus

Do NOT use for:

  • Simple "get paper by ID" or "who cited this" — use semantic-scholar-lookup (faster, no Python)
  • Broad topical discovery — use web_search_advanced_exa with category: "research paper" (Exa MCP)
  • Consumer-level literature questions — use the deep-paper-researcher subagent, which orchestrates all three tools

Scripts

Located under ${SKILL_DIR}/scripts/.

ss_client.py — raw API client

Subcommands (all output JSON on stdout):

Command Endpoint Notes
search <query> /graph/v1/paper/search --bulk switches to /search/bulk (up to 1000/page)
paper <id> /graph/v1/paper/{id} ID forms: raw, DOI:, ARXIV:, CorpusId:, PMID:, URL:
citations <id> /graph/v1/paper/{id}/citations paginated; up to 1000 per page
references <id> /graph/v1/paper/{id}/references paginated; up to 1000 per page
recommendations <id> /recommendations/v1/papers/forpaper/{id} --pool recent|all-cs
batch <id1> <id2> ... POST /graph/v1/paper/batch up to 500 IDs
author-search <query> /graph/v1/author/search
author <id> /graph/v1/author/{id}
author-papers <id> /graph/v1/author/{id}/papers
snippets <query> /graph/v1/snippet/search Full-text snippets

Common flags: --limit, --offset, --fields, --year, --fields-of-study, --venue, --min-citation-count.

citation_graph.py — BFS traversal

python3 ${SKILL_DIR}/scripts/citation_graph.py <paperId> \
    --direction both \
    --depth 2 \
    --max-nodes 200 \
    --per-hop-limit 50 \
    --output graph.json

Directions: forward (citations), backward (references), both. Output schema described in the script docstring — nodes: {paperId → metadata+depth}, edges: [{src, dst, direction}].

Authentication & Rate Limits

  • Without API key: ~1 RPS shared, 100 queries/5min bursts. Fine for small graphs.
  • With SEMANTIC_SCHOLAR_API_KEY env var: much higher limits.
  • Apply: https://www.semanticscholar.org/product/api#api-key
  • The client does exponential backoff (1→30s) on HTTP 429/5xx, respects Retry-After.

Progressive Disclosure

  • references/endpoints.md — complete field list per endpoint + query examples
  • references/workflows.md — lit-review, novelty-check, seed-expansion patterns

Output Hygiene

Scripts emit raw JSON — redirect to files for anything beyond ~20 results. For graphs >50 nodes always pass --output graph.json to avoid flooding the conversation context.

Integration

Typical pipeline inside the deep-paper-researcher subagent:

  1. Discovery — mcp__exa__web_search_advanced_exa (neural + multi-source)
  2. ID resolution — ss_client.py search / batch to get paperId from titles or DOIs
  3. Graph expansion — citation_graph.py with the top 3-5 seeds
  4. Synthesis — distill nodes/edges into a ranked report

Optional: Bundled Subagent

A paired subagent definition ships alongside the skill at agents/deep-paper-researcher.md. It orchestrates Exa MCP + allenai semantic-scholar-lookup + this skill's scripts into a token-isolated research agent with:

  • Mandatory input validation (today's date anchoring + caller-paraphrased-window detection)
  • Freshness Mode classifier (RECENT / FOUNDATIONAL / MIXED)
  • Sort-then-tiebreak ranking (never multiplies citations × recency into a single score)
  • Compact report format with explicit Anchor date / Mode / Window header

To install for Claude Code (manual, one-time):

cp ~/.agents/skills/semantic-scholar-deep/agents/deep-paper-researcher.md ~/.claude/agents/

(Path may differ on other agents — copy to the agent's subagents directory, then restart the session.)

Prerequisites for full pipeline: Exa MCP connected, allenai/asta-plugins@"Semantic Scholar Lookup" skill installed.

Files (ai-driven-development)
  • agents
    • deep-paper-researcher.md 10.4 KB
      Loading…
  • references
    • endpoints.md 4.7 KB
      Loading…
    • workflows.md 4.1 KB
      Loading…
  • scripts
    • citation_graph.py 4.8 KB
      Loading…
    • ss_client.py 10.2 KB
      Loading…
  • README.md 5.9 KB
    # semantic-scholar-deep
    
    Deep research over the Semantic Scholar Graph API. Covers the endpoints missing from the official [allenai/asta-plugins](https://github.com/allenai/asta-plugins) `semantic-scholar-lookup` skill — backward **references**, **recommendations**, **batch** lookup (up to 500 IDs per call), **snippet** full-text search, and multi-hop **citation-graph BFS**.
    
    ## Install
    
    ```bash
    npx skills add CodeAlive-AI/ai-driven-development@semantic-scholar-deep -g -y
    ```
    
    Works anonymously out of the box — most endpoints (paper lookup, references, recommendations, batch) respond without an API key. The keyword `/paper/search` endpoint is heavily rate-limited on the anonymous tier, so for large sweeps set `SEMANTIC_SCHOLAR_API_KEY` (request one at <https://www.semanticscholar.org/product/api#api-key>).
    
    ## Prerequisites
    
    This skill stands alone for scripts-only usage (invoke the Python CLIs directly). For the full **deep-research pipeline** (orchestrated by the bundled subagent, see below), you also need:
    
    | Tool | Why | How |
    |------|-----|-----|
    | **Exa MCP** | Neural paper discovery across arXiv / OpenReview / PubMed / bioRxiv — the S2 `search` endpoint is too rate-limited to be the primary discovery path | `claude mcp add --transport http exa "https://mcp.exa.ai/mcp?tools=web_search_advanced_exa"` |
    | **allenai `semantic-scholar-lookup` skill** | First-party `asta papers` CLI for fast metadata + forward citations (complements our backward-references / recommendations coverage) | `npx skills add "allenai/asta-plugins@Semantic Scholar Lookup" -g -y` |
    | **Python 3.8+** | Scripts are stdlib-only, no pip install | Usually already present |
    
    Without the above, the bundled subagent falls back to what it can reach (S2-only), but Exa dramatically improves discovery quality and freshness.
    
    ## Quick start
    
    Inline usage (one specific endpoint):
    
    ```
    > Get the references that DOI:10.18653/v1/N18-3011 cites
    > Recommend 20 papers related to this paperId
    > Batch-resolve these 30 arXiv IDs: 2404.18496 2502.02757 ...
    > Build a citation graph of depth 2 around paperId X
    ```
    
    Delegated usage (multi-step research via the bundled subagent):
    
    ```
    > Find recent papers on LLM code review
    > Do a literature review on retrieval-augmented generation since 2024
    > Novelty check: is my idea <X> already published?
    ```
    
    ## What it ships
    
    ### Python CLIs (`scripts/`)
    
    - **`ss_client.py`** — stdlib-only S2 client with exponential backoff on HTTP 429/5xx. Subcommands: `search`, `paper`, `citations`, `references`, `recommendations`, `batch`, `author-search`, `author`, `author-papers`, `snippets`.
    - **`citation_graph.py`** — BFS traversal around a seed paper. Options: `--direction forward|backward|both`, `--depth N`, `--max-nodes N`. Outputs JSON with `nodes` + `edges`, designed for summarization rather than in-context dumping.
    
    ### References (`references/`)
    
    - **`endpoints.md`** — complete field reference, query-parameter list, and ID-format matrix for every endpoint.
    - **`workflows.md`** — 5 ready-made deep-research patterns: literature review from a topic, citation graph around a seed, novelty check, author trajectory, evidence for a claim.
    
    ### Bundled subagent (`agents/deep-paper-researcher.md`, optional)
    
    A paired subagent definition for token-isolated research. Manually install once:
    
    ```bash
    cp ~/.agents/skills/semantic-scholar-deep/agents/deep-paper-researcher.md ~/.claude/agents/
    ```
    
    Then restart the session. Features:
    
    - Input validation — today's date anchoring + caller-paraphrased-window detection (catches cases where the calling agent translates "recent" into an invented "2024-2026" window)
    - Freshness Mode classifier — `RECENT` (default last 6 months, sort by publication date), `FOUNDATIONAL` (sort by citations, no date floor), `MIXED` (two slices side-by-side)
    - Sort-then-tiebreak ranking — never multiplies `citations × recency` into a single score, so fresh papers with zero citations aren't buried under older high-citation ones
    - Compact report format with explicit `Anchor date` / `Mode` / `Window` header — readers can see and redirect the choice
    
    ## Key design decisions
    
    - **Stdlib only** — no `requests` dependency. Works on any Python 3.8+ install.
    - **Backoff over hard-failure** — HTTP 429 / 5xx get exponential retry up to 30s, honoring `Retry-After`. Anonymous tier is usable for small graphs.
    - **Progressive disclosure** — `SKILL.md` stays under 150 lines; deep endpoint-by-endpoint docs and workflow templates live in `references/`.
    - **Token hygiene** — scripts emit raw JSON to stdout by design. For graphs >50 nodes, use `--output` to write to disk and summarize via `jq`/`python3` rather than piping full payloads into the agent's context.
    - **Not a discovery engine** — keyword `search` works but is the weakest endpoint on the anonymous tier; the bundled subagent delegates discovery to Exa MCP and uses S2 for structured expansion (references, recommendations, batch).
    
    ## Rate limits
    
    | Endpoint | Anonymous tier | With API key |
    |----------|----------------|--------------|
    | `paper` by ID | ~1 RPS, reliable | Much higher |
    | `references` / `recommendations` | ~1 RPS, reliable | Much higher |
    | `batch` (up to 500 IDs) | ~1 RPS | Much higher |
    | `search` (keyword) | Frequently 429 | Reliable |
    
    The client respects `Retry-After` and does up to 5 retries with exponential backoff (1→30s).
    
    ## File structure
    
    ```
    semantic-scholar-deep/
    ├── SKILL.md                       # Agent-facing instructions (dispatch rule, when to use)
    ├── README.md                      # This file
    ├── scripts/
    │   ├── ss_client.py              # Full S2 API client (stdlib only)
    │   └── citation_graph.py         # BFS traversal
    ├── references/
    │   ├── endpoints.md              # Per-endpoint field and parameter reference
    │   └── workflows.md              # 5 deep-research patterns
    └── agents/
        └── deep-paper-researcher.md  # Optional paired subagent definition
    ```
    
    ## License
    
    MIT
    
  • SKILL.md 8.8 KB
    ---
    name: semantic-scholar-deep
    description: Deep research over the Semantic Scholar Graph API. Covers endpoints missing from allenai's lookup skill — paper references (backward citations), recommendations, batch paper lookup (up to 500 IDs), snippet search, and multi-hop citation graph traversal (BFS forward/backward). Use when the user asks to build a citation graph, expand a literature seed, find related work, run a reference network traversal, explore what a paper cites or what cites it beyond simple lookup, or batch-resolve many DOI/arXiv/S2 IDs. For multi-step research questions, delegate to the deep-paper-researcher subagent to keep the main context clean. Not for single paper-by-ID lookups (use semantic-scholar-lookup) or topical discovery (use web_search_advanced_exa).
    allowed-tools: Bash(python3:*), Read, Write, Edit, Glob, Grep, Agent
    ---
    
    # Semantic Scholar — Deep Research
    
    Purpose: fill the gaps that `semantic-scholar-lookup` (allenai) leaves — `references`, `recommendations`, `batch`, and multi-hop citation-graph traversal.
    
    ## Contents
    
    - [Dispatch Rule](#dispatch-rule-read-first) — inline vs delegate; model selection
    - [When to Use](#when-to-use) — trigger scenarios
    - [Scripts](#scripts) — `ss_client.py` + `citation_graph.py`
    - [Authentication & Rate Limits](#authentication--rate-limits)
    - [Progressive Disclosure](#progressive-disclosure) — deeper references
    - [Output Hygiene](#output-hygiene)
    - [Integration](#integration) — typical pipeline with the subagent
    
    ## Dispatch Rule (read first)
    
    Two execution modes:
    
    ### Inline (run the Bash scripts yourself)
    
    Use when the user asks for **one specific endpoint**:
    - "get references of paper X" → `ss_client.py references <id>`
    - "recommendations for paper Y" → `ss_client.py recommendations <id>`
    - "batch-resolve these 30 DOIs" → `ss_client.py batch ...`
    - "find the snippet where X is said" → `ss_client.py snippets "..."`
    
    Fast, cheap, no orchestration overhead.
    
    ### Delegate to `deep-paper-researcher` subagent
    
    Use when the task is **multi-step** or would otherwise flood the context:
    - Literature review on a topic
    - Citation graph / network analysis around a seed paper
    - Novelty check for an idea
    - State-of-the-art survey
    - Anything that requires merging Exa discovery + S2 graph + ranking
    
    **Mandatory prompt contents.** The subagent runs in isolated context with no access to this conversation's system reminders. Include exactly these two things:
    
    1. **Today's date** — inline as `Today is YYYY-MM-DD.` Pull from the `currentDate` system-reminder field, or run `date -I` via Bash before delegating if it's missing. Never rely on training-data intuitions about the current year.
    2. **User's request, verbatim** — pass the user's original phrasing (topic + any freshness words like "современные / recent / классические / seminal" and any explicit dates like "since 2024"). Translate language if needed but do not paraphrase trigger words into date windows.
    
    **Do NOT do any of these:**
    - Do NOT classify freshness yourself (RECENT/FOUNDATIONAL/MIXED). The subagent does that from the verbatim user request.
    - Do NOT invent a date window. If the user said "современные / recent / latest" without a year, the subagent defaults to last 6 months — don't preempt it with "2024-2026".
    - Do NOT drop the trigger words. The subagent relies on them to pick the right mode.
    
    Call:
    ```
    Agent(
      subagent_type="deep-paper-researcher",
      description="<3–5 word task>",
      prompt="Today is 2026-04-22.\n\nUser's request: найди современные 10 статей про AI Code Review на arXiv.\n\n<optional: output format hints, language preference>"
      # model: "opus"  ← add only when the user opts in (see below)
    )
    ```
    
    The subagent's Freshness Mode section handles classification; keep this layer thin.
    
    ### Model selection (Sonnet default, Opus on demand)
    
    The subagent's `model` frontmatter is `sonnet` — that's the default.
    
    Override to Opus by passing `model: "opus"` to the `Agent` tool **only if the user explicitly requests deeper reasoning**. Triggers (any of):
    - English: "deep dive", "thorough", "rigorous", "use Opus", "high quality", "comprehensive", "exhaustive"
    - Russian: "глубокий/глубже", "тщательный/тщательно", "подробно", "в режиме Опус/Opus", "максимально качественно", "серьёзный ресерч"
    
    Never auto-upgrade to Opus without a user signal — Sonnet handles the default literature-review workflow fine and costs less.
    
    ## When to Use
    
    Trigger this skill for:
    - **Citation graph / network** over a seed paper or topic
    - **Backward references** (what does this paper cite?) — *not* covered by allenai
    - **Forward citations** with pagination beyond 1000 results
    - **Recommendations** — related-paper discovery from a seed
    - **Batch lookup** — resolve 50-500 DOI/arXiv/CorpusId/S2 IDs in one call
    - **Snippet search** — find specific passages across the S2 corpus
    
    **Do NOT use** for:
    - Simple "get paper by ID" or "who cited this" — use `semantic-scholar-lookup` (faster, no Python)
    - Broad topical discovery — use `web_search_advanced_exa` with `category: "research paper"` (Exa MCP)
    - Consumer-level literature questions — use the `deep-paper-researcher` subagent, which orchestrates all three tools
    
    ## Scripts
    
    Located under `${SKILL_DIR}/scripts/`.
    
    ### `ss_client.py` — raw API client
    
    Subcommands (all output JSON on stdout):
    
    | Command | Endpoint | Notes |
    |---------|----------|-------|
    | `search <query>` | `/graph/v1/paper/search` | `--bulk` switches to `/search/bulk` (up to 1000/page) |
    | `paper <id>` | `/graph/v1/paper/{id}` | ID forms: raw, `DOI:`, `ARXIV:`, `CorpusId:`, `PMID:`, `URL:` |
    | `citations <id>` | `/graph/v1/paper/{id}/citations` | paginated; up to 1000 per page |
    | `references <id>` | `/graph/v1/paper/{id}/references` | paginated; up to 1000 per page |
    | `recommendations <id>` | `/recommendations/v1/papers/forpaper/{id}` | `--pool recent|all-cs` |
    | `batch <id1> <id2> ...` | `POST /graph/v1/paper/batch` | up to 500 IDs |
    | `author-search <query>` | `/graph/v1/author/search` | |
    | `author <id>` | `/graph/v1/author/{id}` | |
    | `author-papers <id>` | `/graph/v1/author/{id}/papers` | |
    | `snippets <query>` | `/graph/v1/snippet/search` | Full-text snippets |
    
    Common flags: `--limit`, `--offset`, `--fields`, `--year`, `--fields-of-study`, `--venue`, `--min-citation-count`.
    
    ### `citation_graph.py` — BFS traversal
    
    ```
    python3 ${SKILL_DIR}/scripts/citation_graph.py <paperId> \
        --direction both \
        --depth 2 \
        --max-nodes 200 \
        --per-hop-limit 50 \
        --output graph.json
    ```
    
    Directions: `forward` (citations), `backward` (references), `both`. Output schema described in the script docstring — `nodes: {paperId → metadata+depth}`, `edges: [{src, dst, direction}]`.
    
    ## Authentication & Rate Limits
    
    - Without API key: ~1 RPS shared, 100 queries/5min bursts. Fine for small graphs.
    - With `SEMANTIC_SCHOLAR_API_KEY` env var: much higher limits.
    - Apply: https://www.semanticscholar.org/product/api#api-key
    - The client does exponential backoff (1→30s) on HTTP 429/5xx, respects `Retry-After`.
    
    ## Progressive Disclosure
    
    - `references/endpoints.md` — complete field list per endpoint + query examples
    - `references/workflows.md` — lit-review, novelty-check, seed-expansion patterns
    
    ## Output Hygiene
    
    Scripts emit raw JSON — redirect to files for anything beyond ~20 results. For graphs >50 nodes always pass `--output graph.json` to avoid flooding the conversation context.
    
    ## Integration
    
    Typical pipeline inside the `deep-paper-researcher` subagent:
    
    1. **Discovery** — `mcp__exa__web_search_advanced_exa` (neural + multi-source)
    2. **ID resolution** — `ss_client.py search` / `batch` to get `paperId` from titles or DOIs
    3. **Graph expansion** — `citation_graph.py` with the top 3-5 seeds
    4. **Synthesis** — distill nodes/edges into a ranked report
    
    ## Optional: Bundled Subagent
    
    A paired subagent definition ships alongside the skill at `agents/deep-paper-researcher.md`. It orchestrates Exa MCP + allenai `semantic-scholar-lookup` + this skill's scripts into a token-isolated research agent with:
    
    - Mandatory input validation (today's date anchoring + caller-paraphrased-window detection)
    - Freshness Mode classifier (RECENT / FOUNDATIONAL / MIXED)
    - Sort-then-tiebreak ranking (never multiplies citations × recency into a single score)
    - Compact report format with explicit `Anchor date` / `Mode` / `Window` header
    
    To install for Claude Code (manual, one-time):
    
    ```bash
    cp ~/.agents/skills/semantic-scholar-deep/agents/deep-paper-researcher.md ~/.claude/agents/
    ```
    
    (Path may differ on other agents — copy to the agent's subagents directory, then restart the session.)
    
    Prerequisites for full pipeline: Exa MCP connected, `allenai/asta-plugins@"Semantic Scholar Lookup"` skill installed.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.