{"id":"ff0cc386-a3e2-4321-ae24-10a97075abe8","shortId":"5vD2Ye","kind":"skill","title":"semantic-scholar-deep","tagline":"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","description":"# Semantic Scholar — Deep Research\n\nPurpose: fill the gaps that `semantic-scholar-lookup` (allenai) leaves — `references`, `recommendations`, `batch`, and multi-hop citation-graph traversal.\n\n## Contents\n\n- [Dispatch Rule](#dispatch-rule-read-first) — inline vs delegate; model selection\n- [When to Use](#when-to-use) — trigger scenarios\n- [Scripts](#scripts) — `ss_client.py` + `citation_graph.py`\n- [Authentication & Rate Limits](#authentication--rate-limits)\n- [Progressive Disclosure](#progressive-disclosure) — deeper references\n- [Output Hygiene](#output-hygiene)\n- [Integration](#integration) — typical pipeline with the subagent\n\n## Dispatch Rule (read first)\n\nTwo execution modes:\n\n### Inline (run the Bash scripts yourself)\n\nUse when the user asks for **one specific endpoint**:\n- \"get references of paper X\" → `ss_client.py references <id>`\n- \"recommendations for paper Y\" → `ss_client.py recommendations <id>`\n- \"batch-resolve these 30 DOIs\" → `ss_client.py batch ...`\n- \"find the snippet where X is said\" → `ss_client.py snippets \"...\"`\n\nFast, cheap, no orchestration overhead.\n\n### Delegate to `deep-paper-researcher` subagent\n\nUse when the task is **multi-step** or would otherwise flood the context:\n- Literature review on a topic\n- Citation graph / network analysis around a seed paper\n- Novelty check for an idea\n- State-of-the-art survey\n- Anything that requires merging Exa discovery + S2 graph + ranking\n\n**Mandatory prompt contents.** The subagent runs in isolated context with no access to this conversation's system reminders. Include exactly these two things:\n\n1. **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.\n2. **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.\n\n**Do NOT do any of these:**\n- Do NOT classify freshness yourself (RECENT/FOUNDATIONAL/MIXED). The subagent does that from the verbatim user request.\n- 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\".\n- Do NOT drop the trigger words. The subagent relies on them to pick the right mode.\n\nCall:\n```\nAgent(\n  subagent_type=\"deep-paper-researcher\",\n  description=\"<3–5 word task>\",\n  prompt=\"Today is 2026-04-22.\\n\\nUser's request: найди современные 10 статей про AI Code Review на arXiv.\\n\\n<optional: output format hints, language preference>\"\n  # model: \"opus\"  ← add only when the user opts in (see below)\n)\n```\n\nThe subagent's Freshness Mode section handles classification; keep this layer thin.\n\n### Model selection (Sonnet default, Opus on demand)\n\nThe subagent's `model` frontmatter is `sonnet` — that's the default.\n\nOverride to Opus by passing `model: \"opus\"` to the `Agent` tool **only if the user explicitly requests deeper reasoning**. Triggers (any of):\n- English: \"deep dive\", \"thorough\", \"rigorous\", \"use Opus\", \"high quality\", \"comprehensive\", \"exhaustive\"\n- Russian: \"глубокий/глубже\", \"тщательный/тщательно\", \"подробно\", \"в режиме Опус/Opus\", \"максимально качественно\", \"серьёзный ресерч\"\n\nNever auto-upgrade to Opus without a user signal — Sonnet handles the default literature-review workflow fine and costs less.\n\n## When to Use\n\nTrigger this skill for:\n- **Citation graph / network** over a seed paper or topic\n- **Backward references** (what does this paper cite?) — *not* covered by allenai\n- **Forward citations** with pagination beyond 1000 results\n- **Recommendations** — related-paper discovery from a seed\n- **Batch lookup** — resolve 50-500 DOI/arXiv/CorpusId/S2 IDs in one call\n- **Snippet search** — find specific passages across the S2 corpus\n\n**Do NOT use** for:\n- Simple \"get paper by ID\" or \"who cited this\" — use `semantic-scholar-lookup` (faster, no Python)\n- Broad topical discovery — use `web_search_advanced_exa` with `category: \"research paper\"` (Exa MCP)\n- Consumer-level literature questions — use the `deep-paper-researcher` subagent, which orchestrates all three tools\n\n## Scripts\n\nLocated under `${SKILL_DIR}/scripts/`.\n\n### `ss_client.py` — raw API client\n\nSubcommands (all output JSON on stdout):\n\n| Command | Endpoint | Notes |\n|---------|----------|-------|\n| `search <query>` | `/graph/v1/paper/search` | `--bulk` switches to `/search/bulk` (up to 1000/page) |\n| `paper <id>` | `/graph/v1/paper/{id}` | ID forms: raw, `DOI:`, `ARXIV:`, `CorpusId:`, `PMID:`, `URL:` |\n| `citations <id>` | `/graph/v1/paper/{id}/citations` | paginated; up to 1000 per page |\n| `references <id>` | `/graph/v1/paper/{id}/references` | paginated; up to 1000 per page |\n| `recommendations <id>` | `/recommendations/v1/papers/forpaper/{id}` | `--pool recent|all-cs` |\n| `batch <id1> <id2> ...` | `POST /graph/v1/paper/batch` | up to 500 IDs |\n| `author-search <query>` | `/graph/v1/author/search` | |\n| `author <id>` | `/graph/v1/author/{id}` | |\n| `author-papers <id>` | `/graph/v1/author/{id}/papers` | |\n| `snippets <query>` | `/graph/v1/snippet/search` | Full-text snippets |\n\nCommon flags: `--limit`, `--offset`, `--fields`, `--year`, `--fields-of-study`, `--venue`, `--min-citation-count`.\n\n### `citation_graph.py` — BFS traversal\n\n```\npython3 ${SKILL_DIR}/scripts/citation_graph.py <paperId> \\\n    --direction both \\\n    --depth 2 \\\n    --max-nodes 200 \\\n    --per-hop-limit 50 \\\n    --output graph.json\n```\n\nDirections: `forward` (citations), `backward` (references), `both`. Output schema described in the script docstring — `nodes: {paperId → metadata+depth}`, `edges: [{src, dst, direction}]`.\n\n## Authentication & Rate Limits\n\n- Without API key: ~1 RPS shared, 100 queries/5min bursts. Fine for small graphs.\n- With `SEMANTIC_SCHOLAR_API_KEY` env var: much higher limits.\n- Apply: https://www.semanticscholar.org/product/api#api-key\n- The client does exponential backoff (1→30s) on HTTP 429/5xx, respects `Retry-After`.\n\n## Progressive Disclosure\n\n- `references/endpoints.md` — complete field list per endpoint + query examples\n- `references/workflows.md` — lit-review, novelty-check, seed-expansion patterns\n\n## Output Hygiene\n\nScripts 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.\n\n## Integration\n\nTypical pipeline inside the `deep-paper-researcher` subagent:\n\n1. **Discovery** — `mcp__exa__web_search_advanced_exa` (neural + multi-source)\n2. **ID resolution** — `ss_client.py search` / `batch` to get `paperId` from titles or DOIs\n3. **Graph expansion** — `citation_graph.py` with the top 3-5 seeds\n4. **Synthesis** — distill nodes/edges into a ranked report\n\n## Optional: Bundled Subagent\n\nA 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:\n\n- Mandatory input validation (today's date anchoring + caller-paraphrased-window detection)\n- Freshness Mode classifier (RECENT / FOUNDATIONAL / MIXED)\n- Sort-then-tiebreak ranking (never multiplies citations × recency into a single score)\n- Compact report format with explicit `Anchor date` / `Mode` / `Window` header\n\nTo install for Claude Code (manual, one-time):\n\n```bash\ncp ~/.agents/skills/semantic-scholar-deep/agents/deep-paper-researcher.md ~/.claude/agents/\n```\n\n(Path may differ on other agents — copy to the agent's subagents directory, then restart the session.)\n\nPrerequisites for full pipeline: Exa MCP connected, `allenai/asta-plugins@\"Semantic Scholar Lookup\"` skill installed.","tags":["semantic","scholar","deep","driven","development","codealive-ai","agent-safety","agent-skills","ai-coding","ai-driven-development","ai-safety","antigravity"],"capabilities":["skill","source-codealive-ai","skill-semantic-scholar-deep","topic-agent-safety","topic-agent-skills","topic-ai-coding","topic-ai-driven-development","topic-ai-safety","topic-antigravity","topic-bash","topic-claude-code","topic-codex-cli","topic-cursor","topic-developer-tools","topic-gemini-cli"],"categories":["ai-driven-development"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/CodeAlive-AI/ai-driven-development/semantic-scholar-deep","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add CodeAlive-AI/ai-driven-development","source_repo":"https://github.com/CodeAlive-AI/ai-driven-development","install_from":"skills.sh"}},"qualityScore":"0.483","qualityRationale":"deterministic score 0.48 from registry signals: · indexed on github topic:agent-skills · 67 github stars · SKILL.md body (7,879 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:57:07.560Z","embedding":null,"createdAt":"2026-05-04T06:56:23.799Z","updatedAt":"2026-05-18T18:57:07.560Z","lastSeenAt":"2026-05-18T18:57:07.560Z","tsv":"'-04':424 '-2026':390 '-22':425 '-5':958 '-500':604 '/.agents/skills/semantic-scholar-deep/agents/deep-paper-researcher.md':1054 '/.claude/agents':1055 '/citations':713 '/graph/v1/author':750,755 '/graph/v1/author/search':748 '/graph/v1/paper':700,711,721 '/graph/v1/paper/batch':740 '/graph/v1/paper/search':691 '/graph/v1/snippet/search':759 '/opus':531 '/papers':757 '/product/api#api-key':851 '/recommendations/v1/papers/forpaper':731 '/references':723 '/scripts':676 '/scripts/citation_graph.py':785 '/search/bulk':695 '1':257,828,857,925 '10':432 '100':831 '1000':590,717,727 '1000/page':698 '2':300,789,937 '20':899 '200':793 '2024':326,389 '2026':423 '3':416,950,957 '30':162 '30s':858 '4':960 '429/5xx':861 '5':417 '50':603,798,903 '500':31,743 '6':382 'access':245 'across':615 'add':450 'advanc':646,931 'agent':408,498,1000,1061,1065 'agents/deep-paper-researcher.md':980 'ai':435 'all-c':735 'allenai':17,58,584,985 'allenai/asta-plugins':1080 'alongsid':976 'alway':905 'analysi':209 'anchor':1008,1038 'anyth':225,897 'api':12,679,826,841 'appli':848 'around':210 'art':223 'arxiv':439,706 'ask':140 'authent':97,100,822 'author':746,749,753 'author-pap':752 'author-search':745 'auto':538 'auto-upgrad':537 'avoid':910 'backoff':856 'backward':23,574,804 'bash':133,282,1052 'batch':26,62,159,165,600,738,942 'batch-resolv':158 'beyond':589,898 'bfs':42,780 'broad':640 'bulk':692 'bundl':969 'burst':833 'call':407,609 'caller':1010 'caller-paraphrased-window':1009 'categori':649 'cheap':176 'check':215,882 'citat':24,39,68,206,565,586,710,777,803,1027 'citation-graph':67 'citation_graph.py':96,779,953 'cite':580,630 'classif':466 'classifi':348,1016 'claud':1046 'client':680,853 'code':436,1047 'command':687 'common':764 'compact':1033 'complet':869 'comprehens':520 'connect':1079 'consum':655 'consumer-level':654 'content':71,236 'context':200,242,914 'convers':248,913 'copi':1062 'corpus':618 'corpusid':707 'cost':556 'count':778 'cover':13,582 'cp':1053 'cs':737 'current':298 'currentd':272 'data':294 'date':260,279,323,338,365,1007,1039 'dd':268 'deep':4,5,47,183,412,512,662,921 'deep-paper-research':182,411,661,920 'deeper':109,506 'default':379,474,488,549 'definit':974 'deleg':81,180,284 'demand':477 'depth':788,817 'describ':809 'descript':415 'detect':1013 'differ':1058 'dir':675,784 'direct':786,801,821 'directori':1068 'disclosur':105,108,867 'discoveri':230,596,642,926 'dispatch':72,75,123 'dispatch-rule-read-first':74 'distil':962 'dive':513 'docstr':813 'doi':163,705,949 'doi/arxiv/corpusid/s2':605 'drop':393 'dst':820 'edg':818 'emit':890 'endpoint':14,144,688,873 'english':511 'env':843 'exa':229,647,652,928,932,983,1077 'exact':253 'exampl':875 'execut':128 'exhaust':521 'expans':885,952 'explicit':322,504,1037 'exponenti':855 'fast':175 'faster':637 'field':276,768,771,870 'fields-of-studi':770 'file':895 'fill':50 'find':166,612 'fine':554,834 'first':78,126 'flag':765 'flood':198,911 'form':703 'format':444,1035 'forward':585,802 'forward/backward':43 'foundat':1018 'fresh':313,349,462,1014 'frontmatt':482 'full':761,1075 'full-text':760 'gap':52 'get':145,624,944 'graph':11,40,69,207,232,566,837,902,951 'graph.json':800,908 'handl':465,547 'header':1042 'high':518 'higher':846 'hint':445 'hop':38,66,796 'http':860 'hygien':112,115,888 'id':32,606,627,701,702,712,722,732,744,751,756,938 'idea':218 'includ':252 'inlin':79,130,261 'input':1003 'insid':918 'instal':1044,1085 'integr':116,117,915 'intuit':295 'invent':363 'isol':241,998 'json':684,892 'keep':467 'key':827,842 'languag':328,446 'last':381 'latest':373 'layer':469 'leav':59 'less':557 'level':656 'like':315,324 'limit':99,103,766,797,824,847 'list':871 'lit':878 'lit-review':877 'literatur':201,551,657 'literature-review':550 'locat':672 'lookup':19,28,57,601,636,989,1083 'mandatori':234,1002 'manual':1048 'max':791 'max-nod':790 'may':1057 'mcp':653,927,984,1078 'merg':228 'metadata':816 'min':776 'min-citation-count':775 'miss':15,288 'mix':1019 'mm':267 'mode':129,406,463,1015,1040 'model':82,448,471,481,494 'month':383 'much':845 'multi':37,65,193,935 'multi-hop':36,64 'multi-sourc':934 'multi-step':192 'multipli':1026 'n':426,440,441 'need':330 'network':208,567 'neural':933 'never':289,536,1025 'node':792,814,904 'nodes/edges':963 'note':689 'novelti':214,881 'novelty-check':880 'nuser':427 'offset':767 'one':142,608,1050 'one-tim':1049 'opt':455 'option':442,968 'opus':449,475,491,495,517,541 'orchestr':178,667,982 'origin':309 'otherwis':197 'output':111,114,443,683,799,807,887,907 'output-hygien':113 'overhead':179 'overrid':489 'page':719,729 'pagin':588,714,724 'pair':972 'paper':21,27,148,154,184,213,413,571,579,595,625,651,663,699,754,922 'paperid':815,945 'paraphras':334,1011 'pass':305,493,906 'passag':614 'path':1056 'pattern':886 'per':718,728,795,872 'per-hop-limit':794 'phrase':310 'pick':403 'pipelin':119,917,1076 'pmid':708 'pool':733 'post':739 'preempt':386 'prefer':447 'prerequisit':1073 'progress':104,107,866 'progressive-disclosur':106 'prompt':235,420 'pull':269 'purpos':49 'python':639 'python3':782 'qualiti':519 'queri':874 'queries/5min':832 'question':658 'rank':233,966,1024 'rate':98,102,823 'rate-limit':101 'raw':678,704,891 'read':77,125 'reason':507 'recenc':1028 'recent':317,372,734,1017 'recent/foundational/mixed':351 'recommend':25,61,152,157,592,730 'redirect':893 'refer':22,60,110,146,151,575,720,805 'references/endpoints.md':868 'references/workflows.md':876 'relat':594 'related-pap':593 'reli':290,399 'remind':251,275 'report':967,1034 'request':303,360,429,505 'requir':227 'research':6,48,185,414,650,664,923,999 'resolut':939 'resolv':160,602 'respect':862 'restart':1070 'result':591,900 'retri':864 'retry-aft':863 'review':202,437,552,879 'right':405 'rigor':515 'rps':829 'rule':73,76,124 'run':131,239,278 'russian':522 's2':231,617 'said':172,370 'scenario':92 'schema':808 'scholar':3,10,46,56,635,840,988,1082 'score':1032 'script':93,94,134,671,812,889,993 'search':34,611,645,690,747,930,941 'section':464 'see':457 'seed':212,570,599,884,959 'seed-expans':883 'select':83,472 'semant':2,9,45,55,634,839,987,1081 'semantic-scholar-deep':1 'semantic-scholar-lookup':54,633,986 'semin':319 'session':1072 'share':830 'ship':975 'signal':545 'simpl':623 'sinc':325 'singl':1031 'skill':20,563,674,783,978,991,1084 'skill-semantic-scholar-deep' 'small':836 'snippet':33,168,174,610,758,763 'sonnet':473,484,546 'sort':1021 'sort-then-tiebreak':1020 'sourc':936 'source-codealive-ai' 'specif':143,613 'src':819 'ss_client.py':95,150,156,164,173,677,940 'state':220 'state-of-the-art':219 'stdout':686 'step':194 'studi':773 'subag':122,186,238,353,378,398,409,460,479,665,924,970,973,1067 'subcommand':681 'survey':224 'switch':693 'synthesi':961 'system':250,274 'system-remind':273 'task':190,419 'text':762 'thin':470 'thing':256 'thorough':514 'three':669 'tiebreak':1023 'time':1051 'titl':947 'today':258,263,421,1005 'token':997 'token-isol':996 'tool':499,670 'top':956 'topic':205,311,573,641 'topic-agent-safety' 'topic-agent-skills' 'topic-ai-coding' 'topic-ai-driven-development' 'topic-ai-safety' 'topic-antigravity' 'topic-bash' 'topic-claude-code' 'topic-codex-cli' 'topic-cursor' 'topic-developer-tools' 'topic-gemini-cli' 'train':293 'training-data':292 'translat':327 'travers':41,70,781 'trigger':91,335,395,508,561 'two':127,255 'type':410 'typic':118,916 'upgrad':539 'url':709 'use':44,86,90,136,187,516,560,621,632,643,659 'user':139,301,307,359,369,454,503,544 'valid':1004 'var':844 'venu':774 'verbatim':304,358 'via':281 'vs':80 'web':644,929 'when-to-us':87 'window':339,366,1012,1041 'without':374,542,825 'word':314,336,396,418 'workflow':553 'would':196 'www.semanticscholar.org':850 'www.semanticscholar.org/product/api#api-key':849 'x':149,170 'y':155 'year':299,376,769 'yyyi':266 'yyyy-mm-dd':265 'в':528 'глубже':524 'глубокий':523 'качественно':533 'классические':318 'максимально':532 'на':438 'найди':430 'опус':530 'подробно':527 'про':434 'режиме':529 'ресерч':535 'серьёзный':534 'современные':316,371,431 'статей':433 'тщательно':526 'тщательный':525","prices":[{"id":"ed7cc239-8c91-47ee-9d05-f6b418ad75a5","listingId":"ff0cc386-a3e2-4321-ae24-10a97075abe8","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"CodeAlive-AI","category":"ai-driven-development","install_from":"skills.sh"},"createdAt":"2026-05-04T06:56:23.799Z"}],"sources":[{"listingId":"ff0cc386-a3e2-4321-ae24-10a97075abe8","source":"github","sourceId":"CodeAlive-AI/ai-driven-development/semantic-scholar-deep","sourceUrl":"https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/semantic-scholar-deep","isPrimary":false,"firstSeenAt":"2026-05-04T06:56:23.799Z","lastSeenAt":"2026-05-18T18:57:07.560Z"}],"details":{"listingId":"ff0cc386-a3e2-4321-ae24-10a97075abe8","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"CodeAlive-AI","slug":"semantic-scholar-deep","github":{"repo":"CodeAlive-AI/ai-driven-development","stars":67,"topics":["agent-safety","agent-skills","ai-coding","ai-driven-development","ai-safety","antigravity","bash","claude-code","codex-cli","cursor","developer-tools","gemini-cli","hooks","mcp","multi-agent","opencode","plugins","prompt-engineering","skills","subagents"],"license":"mit","html_url":"https://github.com/CodeAlive-AI/ai-driven-development","pushed_at":"2026-05-12T20:04:46Z","description":"Practices, protocols, and skills for AI-driven software development. 18 skills + 1 Bash safety hook for Claude Code, Codex CLI, OpenCode, Cursor, Gemini CLI, Antigravity, and any agent supporting the Agent Skills standard.","skill_md_sha":"40d6f18b2ecc82b9db167af1c511b296078b3dc0","skill_md_path":"skills/semantic-scholar-deep/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/CodeAlive-AI/ai-driven-development/tree/main/skills/semantic-scholar-deep"},"layout":"multi","source":"github","category":"ai-driven-development","frontmatter":{"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)."},"skills_sh_url":"https://skills.sh/CodeAlive-AI/ai-driven-development/semantic-scholar-deep"},"updatedAt":"2026-05-18T18:57:07.560Z"}}