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
Install
npx skills add https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/semantic-scholar-deep
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install codealive-ai-ai-driven-development@llmmart
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 withnodes+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 × recencyinto 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/Windowheader — readers can see and redirect the choice
Key design decisions
- Stdlib only — no
requestsdependency. 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.mdstays under 150 lines; deep endpoint-by-endpoint docs and workflow templates live inreferences/. - Token hygiene — scripts emit raw JSON to stdout by design. For graphs >50 nodes, use
--outputto write to disk and summarize viajq/python3rather than piping full payloads into the agent's context. - Not a discovery engine — keyword
searchworks 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 — inline vs delegate; model selection
- When to Use — trigger scenarios
- Scripts —
ss_client.py+citation_graph.py - Authentication & Rate Limits
- Progressive Disclosure — deeper references
- Output Hygiene
- 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:
- Today's date — inline as
Today is YYYY-MM-DD.Pull from thecurrentDatesystem-reminder field, or rundate -Ivia Bash before delegating if it's missing. Never rely on training-data intuitions about the current year. - 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_exawithcategory: "research paper"(Exa MCP) - Consumer-level literature questions — use the
deep-paper-researchersubagent, 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_KEYenv 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 examplesreferences/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:
- Discovery —
mcp__exa__web_search_advanced_exa(neural + multi-source) - ID resolution —
ss_client.py search/batchto getpaperIdfrom titles or DOIs - Graph expansion —
citation_graph.pywith the top 3-5 seeds - 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/Windowheader
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.
Reviews (0)
No reviews yet.
No comments yet.