---
slug: "semanticscholar-skill"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/Agents365-ai/semanticscholar-skill@main/README.md"
repo: "https://github.com/Agents365-ai/semanticscholar-skill"
source_file: "README.md"
branch: "main"
---
# semanticscholar-skill — the easiest way to search the scientific literature 📚

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![GitHub stars](https://img.shields.io/github/stars/Agents365-ai/semanticscholar-skill?style=flat&logo=github)](https://github.com/Agents365-ai/semanticscholar-skill/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/Agents365-ai/semanticscholar-skill?style=flat&logo=github)](https://github.com/Agents365-ai/semanticscholar-skill/network/members)
[![Latest Release](https://img.shields.io/github/v/release/Agents365-ai/semanticscholar-skill?logo=github)](https://github.com/Agents365-ai/semanticscholar-skill/releases/latest)
[![Last Commit](https://img.shields.io/github/last-commit/Agents365-ai/semanticscholar-skill?logo=github)](https://github.com/Agents365-ai/semanticscholar-skill/commits/main)

[![SkillsMP](https://img.shields.io/badge/SkillsMP-listed-1f6feb)](https://skillsmp.com/skills/agents365-ai-semanticscholar-skill-skills-semanticscholar-skill-skill-md)
[![ClawHub](https://img.shields.io/badge/ClawHub-listed-ff6b35)](https://clawhub.ai/agents365-ai/semanticscholar-pro-skill)
[![Claude Code Plugin](https://img.shields.io/badge/Claude%20Code-plugin-8a2be2)](https://github.com/Agents365-ai/365-skills)
[![Agent Skills](https://img.shields.io/badge/Agent%20Skills-compatible-2ea44f)](https://agentskills.io)
**English** · [中文](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/README_CN.md)

External references: [Semantic Scholar API Tutorial](https://www.semanticscholar.org/product/api/tutorial) · [API Docs](https://api.semanticscholar.org/api-docs/) · [Request API Key](https://www.semanticscholar.org/product/api#api-key)

A skill that turns the Semantic Scholar academic graph (200M+ papers across arXiv + bioRxiv + PubMed + journals + conferences) into a single-script, rate-limited, agent-friendly toolkit.

- **Search** by keyword, boolean expression, full-text snippet, exact title, or author
- **Traverse** forward / backward citations and find similar or recommended papers
- **Filter** by year, venue, fields of study, min citations, open access, pub types
- **Export** to BibTeX, Markdown, or JSON
- **Built-in correctness** — automatic rate limiting, exponential backoff, single-script execution

Works with Claude Code, Codex, Hermes, OpenClaw, ClawHub, and SkillsMP — any agent that supports the [Agent Skills](https://agentskills.io) format.

## 🔄 How it works

<p align="center">
  <img src="assets/skill-workflow.png" width="700" alt="semanticscholar-skill internal workflow">
</p>

The skill picks the right endpoint for the user's intent (keyword search, citation traversal, recommendations, author lookup), runs the call through the rate-limited `s2.py` helper with exponential backoff, applies filters (year / venue / fields of study / min citations / open access), and returns results ready to export to BibTeX, Markdown, or JSON.

## Documentation

| Doc | What's inside |
| --- | --- |
| [docs/features.md](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/docs/features.md) | Why Semantic Scholar, full feature list, comparison vs. arXiv / bioRxiv / asta-skill / native agents |
| [docs/api-reference.md](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/docs/api-reference.md) | `s2.py` helper module API, usage examples |
| [docs/limitations.md](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/docs/limitations.md) | Prerequisites, API key setup, known limitations |
| [docs/tutorial.md](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/docs/tutorial.md) | End-to-end tutorial |
| [skills/semanticscholar-skill/SKILL.md](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/skills/semanticscholar-skill/SKILL.md) | Workflow guide loaded by the agent |

## Quick Start

```bash
# Recommended — set an API key for a dedicated quota
export S2_API_KEY=xxxxxxxxxxxxxxxx

# Install dependencies
pip install requests
```

Install the skill:

```bash
# Any agent (Claude Code, Cursor, Copilot, etc.)
npx skills add Agents365-ai/365-skills -g

# Claude Code only
> /plugin marketplace add Agents365-ai/365-skills
> /plugin install semanticscholar
```

Also published on [SkillsMP](https://skillsmp.com/) and [ClawHub](https://clawhub.ai/) — each handles updates through its own marketplace.

## Usage

Just describe what you want:

```
> Use semanticscholar-skill to search for recent mixture-of-experts papers at NeurIPS since 2023

> Find papers citing "Attention Is All You Need" and rank by citation count

> Recommend papers similar to DOI:10.1038/nature14539, excluding NLP

> Export the top 10 results to BibTeX
```

See [docs/api-reference.md](https://github.com/Agents365-ai/semanticscholar-skill/blob/HEAD/docs/api-reference.md) for more examples and the helper module reference.

## 🔗 Related Skills

Part of the [Agents365-ai research-skill family](https://github.com/Agents365-ai) — pick the right tool for the job:

| Skill | Niche | When to use |
| --- | --- | --- |
| [asta-skill](https://github.com/Agents365-ai/asta-skill) | Same corpus via Ai2 Asta MCP | When your host supports MCP and you have an Asta API key |
| [paper-fetch](https://github.com/Agents365-ai/paper-fetch) | DOI → PDF, 7-source fallback | When you already have IDs and need the actual full text |
| [scholar-deep-research](https://github.com/Agents365-ai/scholar-deep-research) | 8-phase literature review pipeline | When the user wants a structured cited report, not just search results |
| [zotero-research-assistant](https://github.com/Agents365-ai/zotero-research-assistant) | Zotero library workflows | When the user manages references in Zotero |

## ❤️ Support

If this skill helps you, consider supporting the author:

<table>
  <tr>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/wechat-pay.png" width="180" alt="WeChat Pay">
      <br>
      <b>WeChat Pay</b>
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/alipay.png" width="180" alt="Alipay">
      <br>
      <b>Alipay</b>
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/qrcode/buymeacoffee.png" width="180" alt="Buy Me a Coffee">
      <br>
      <b>Buy Me a Coffee</b>
    </td>
    <td align="center">
      <img src="https://raw.githubusercontent.com/Agents365-ai/images_payment/main/awarding/award.gif" width="180" alt="Give a Reward">
      <br>
      <b>Give a Reward</b>
    </td>
  </tr>
</table>

## 👤 Author

**Agents365-ai**

- GitHub: <https://github.com/Agents365-ai>
- Bilibili: <https://space.bilibili.com/441831884>

## 📄 License

[MIT](https://github.com/Agents365-ai/semanticscholar-skill/tree/HEAD/LICENSE)