semantic-scholar

semantic-scholar-skills

S2-first discovery engine for AI research workflows.

Three research workflows built on the Semantic Scholar API — available as a Python library, Claude Code skills, or a 16-tool MCP server.

Installation

As Claude Code Plugin

claude plugin install github:zongmin-yu/semantic-scholar-skills

Manual

cp -r skills/* ~/.claude/skills/

Workflows

/expand-references — Discover related work from seed papers

Feed 1–3 seed papers. Get back curated buckets: foundational, methodological, recent, survey, bridge papers, and closest neighbors. Powered by S2's Recommendations API with positive/negative seeds.

/trace-citations — Map a paper's citation neighborhood

Pick a focal paper. Trace its citations and references with context snippets, intent labels, and influence flags. Returns foundations, descendants, bridge connections, and optional second-hop expansion.

/paper-triage — Triage an ambiguous query into a shortlist

Type a vague query. The engine runs autocomplete, relevance search, bulk search, and snippet extraction in parallel, then scores and ranks into a shortlist with explanations.

Quick Start

As Claude Code skills (copy & use)

# Copy any skill to your personal skills directory
cp -r skills/expand-references ~/.claude/skills/

# Then in Claude Code:
/expand-references Attention Is All You Need

Each skill is fully self-contained — no pip install required. The bundled standalone runtime uses only Python stdlib.

As a Python library

pip install semantic-scholar-skills

core library only: installs core/, engine/, and the stdlib-backed standalone/ runtime.

import asyncio
from semantic_scholar_skills.core import get_default_client, cleanup_client
from semantic_scholar_skills.engine import paper_triage

async def main():
    client = get_default_client()
    try:
        result = await paper_triage(client, "retrieval augmented generation")
        for paper in result.shortlist[:5]:
            print(f"{paper.score:.2f}  {paper.paper.title}")
    finally:
        await cleanup_client()

asyncio.run(main())

As an MCP server

pip install "semantic-scholar-skills[mcp]"
semantic-scholar-skills-mcp

full MCP stack: installs fastmcp, fastapi, and uvicorn in addition to the core library.

16 tools covering papers, authors, citations, recommendations, and snippets. Works with Claude Desktop, Cursor, and any MCP client.

Architecture

              Claude Code Skills          MCP Server (16 tools)
                    │                           │
                    ▼                           ▼
            ┌─────────────┐             ┌─────────────┐
            │  skills-src/ │             │    mcp/     │
            │  (SKILL.md)  │             │  (FastMCP)  │
            └──────┬───────┘             └──────┬──────┘
                   │                            │
                   ▼                            ▼
            ┌──────────────────────────────────────┐
            │         engine/ — Workflow Logic      │
            │  expand_references · trace_citations  │
            │  paper_triage · resolve · scoring     │
            └──────────────────┬───────────────────┘
                               │
                   ┌───────────┴───────────┐
                   ▼                       ▼
            ┌─────────────┐         ┌─────────────┐
            │   core/     │         │ standalone/  │
            │  (httpx)    │         │  (urllib)    │
            └─────────────┘         └─────────────┘
                   │                       │
                   └───────────┬───────────┘
                               ▼
                    Semantic Scholar API

Source is shared, artifacts are self-contained. The engine/ and standalone/ layers are vendored into each skill bundle by bundle_skills.py, so users can copy a single folder and it just works.

API Key (Optional)

export SEMANTIC_SCHOLAR_API_KEY=your-key-here

Without a key: 100 requests per 5 minutes. With a key: up to 10 req/s. Get one free at semanticscholar.org/product/api.

Skill Bundles

The skills/ directory contains pre-built, self-contained bundles for Claude Code: