Skip to main content
skill CX Codex

literature-search · gaasher — Claude Code skill: what it does, how to install

literature-search searches academic papers across Semantic Scholar and arXiv, walks citation trees, and extracts snippets using only the Python standard library.

MIT ★ 185 updated 2026-06-30

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add gaasher/Agent-Loop-Skills
/plugin install agent-loops@agent-loop-skills
Open on GitHub

What literature-search does

The skill exposes tools/lit_search.py, a zero-dependency CLI that loop agents query when they evaluate novelty or discover research papers. Its core handles semantic searches via Semantic Scholar and retrieves full texts from arXiv. Every call outputs JSON; if an external endpoint fails, it exits with an error status so the agent can fall back to standard web retrieval.

Subcommands cover discovery filters, direct passage lookup, two-way citation navigation, and arXiv reading across HTML or LaTeX. If configured, it also bridges OpenAlex, Perplexity Sonar for cited syntheses, and bgpt.pro for experimental metrics.

Running the tool requires Python 3.9+. The primary Semantic Scholar and arXiv workflows operate keyless, while optional service tokens are read from a local keys.env file located at the project root.

What it helps with

  • discover related academic papers with abstracts and citation counts
  • traverse citation graphs forward or backward from a given paper ID
  • pinpoint specific numbers or experimental results inside publications
  • retrieve arXiv papers directly in LaTeX or HTML formats
  • generate cited research answers using Perplexity Sonar integration

Example prompts for the agent

  • Use literature-search to find papers on speculative decoding published since 2023 with at least 15 citations
  • Walk the citation graph for paperId 204bf9f2f8486134b27cb09919cf62ea8380eb0b towards recommendations
  • Run the fulltext command on arxivId 2309.06180 to inspect its experimental section

How to install literature-search

1Plugin marketplace

/plugin marketplace add gaasher/Agent-Loop-Skills
/plugin install agent-loops@agent-loop-skills

This installs the whole agent-loops plugin with all its skills

2Skills CLI (Vercel)

npx skills add gaasher/Agent-Loop-Skills --skill literature-search -a claude-code

3Manually: put the files in place

~/.claude/skills/literature-search/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/literature-search/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about literature-search

How to install literature-search in Claude Code?

Run npx skills add gaasher/Agent-Loop-Skills --skill literature-search -a claude-code in your terminal. Alternatively, add the marketplace with /plugin marketplace add gaasher/Agent-Loop-Skills and install it via /plugin install agent-loops@agent-loop-skills.

What does literature-search do?

It provides a unified Python CLI that queries Semantic Scholar and arXiv for scholarly search, citation mapping, and full-text reading.

Does literature-search require paid API keys?

No, the main search, snippet, cite, and full-text commands operate without keys. Optional keys like OPENROUTER_API_KEY are only needed for Perplexity synthesis through the ask subcommand.

Source text

SKILL.md · MIT
---
name: literature-search
description: >
  Use when a loop needs scholarly literature — paper discovery, novelty checks, full-text snippet
  search, citation-graph traversal, single-paper reads, or experimental-result extraction. A shared,
  stdlib-only CLI (`tools/lit_search.py`) over Semantic Scholar + arXiv (plus optional OpenAlex,
  Perplexity Sonar, bgpt.pro), all JSON. Not a loop itself: install it alongside the loops and let any
  of them call it instead of vendoring their own copy. Degrades to the caller's WebSearch/WebFetch.
compatibility: Requires Python 3.9+
metadata:
  version: "0.1.0"
---

# Literature Search (shared toolchain)

This skill is **not a loop** — it is the literature-retrieval dependency several loops use for paper
discovery and novelty checks. It bundles `tools/lit_search.py` (a stdlib-only entrypoint) and the
`tools/lit/` package: Semantic Scholar (S2) for semantic search + snippets + the citation graph and
arXiv for full-text reads (the keyless core), plus optional OpenAlex, Perplexity Sonar (`ask`), and
bgpt.pro (`bgpt`) when their keys are set. Every subcommand prints JSON; on a terminal failure it
prints `{"error","fallback"}` and exits non-zero so the caller degrades to its built-in
**WebSearch/WebFetch**. No installs, Python ≥3.9.

## How a loop uses it

A consuming loop resolves these once at setup and reuses them:
- **`<lit_skill_dir>`** — where this skill is installed. After `cp -r loops/* ~/.claude/skills/` it
  sits as a **sibling** of the calling loop, e.g. `~/.claude/skills/literature-search/` (adjust per
  host). If it cannot be resolved, the caller falls back to WebSearch/WebFetch — depending on it never
  hard-breaks a loop, it only enriches it.
- **`<lit>`** — the literature CLI as a **single command token**: `<lit_skill_dir>/tools/lit_search.py`.
  The entrypoint is executable and carries a `#!/usr/bin/env python3` shebang, so it runs directly with
  no `python3` prefix. To reuse a cache across calls, append `--cache-dir <sandbox_root>/literature/.cache`
  **after the subcommand** (a per-subcommand flag, not global).
- **`<lit_py>`** — only needed for the **fallback** form on a host that doesn't honour the execute bit:
  `<lit_py> <lit_skill_dir>/tools/lit_search.py`, with `<lit_py> = python3` (any ≥3.9 interpreter).

> **Invoke `<lit>` as one command — keep it a single shell token.** In particular **zsh does not
> word-split unquoted variables**, so storing the two-word `python3 .../lit_search.py` in a variable and
> calling `$VAR` tries to exec one long (nonexistent) filename. Use the executable single-token form
> above, call the script path directly, or split explicitly (`${=VAR}` in zsh).

## Subcommands

| Subcommand | Use |
|---|---|
| `<lit> search "<q>" [--year 2020-] [--min-citations N] [--limit N] [--source s2\|openalex\|both] [--sort relevance\|citations\|recent]` | semantic discovery — related papers (titles, TLDR, abstract, citations, arxiv_id). Defaults to `--source s2` (relevance); add `openalex`/`both` to widen discovery |
| `<lit> snippet "<q>" [--limit N]` | full-text passage search — pinpoint a verbatim fact/number without reading a paper |
| `<lit> cite <paperId> --direction references\|citations\|recommend` | walk the citation graph (backward / forward / "more like this") |
| `<lit> fulltext <arxivId> [--mode auto\|latex\|pdf]` | deep-read one paper's methods/results (HTML > LaTeX > PDF) |
| `<lit> ask "<question>" [--model sonar\|sonar-pro\|sonar-reasoning]` | Perplexity Sonar synthesis — a cited high-level answer (needs `OPENROUTER_API_KEY`; else use WebSearch) |
| `<lit> bgpt "<q>" [--num N] [--days-back N]` | bgpt.pro structured experimental-result/limitations extraction (free for 50 results, then `BGPT_API_KEY`) |
| `<lit> keys [--init]` | report which API keys are present (booleans only); `--init` writes/extends `keys.env` |

The S2 + arXiv core (`search`/`snippet`/`cite`/`fulltext`) needs no keys. The optional extras
(`search --source openalex|both`, `ask`, `bgpt`) widen discovery and synthesis when their keys are set.

## API keys (the shared convention — optional, never block)

This skill is the canonical home for the project's key convention (it is the installed code that
implements it). Keys live in **one gitignored `keys.env` at the project root** (the nearest `.git`
ancestor of the working dir, else the CWD), shared by every skill in the project.

- Plain `KEY=VALUE` lines; `#` comments; blank lines ignored; `0600` perms.
- **A real OS environment variable always wins** over the file (CI/power users can just `export`).
- **All keys are optional** — a missing key degrades that one feature gracefully, down to WebSearch.
- **Secrets never enter the conversation** — the user edits `keys.env` themselves; skills read only
  presence as booleans, never values.

Onboarding flow: `<lit> keys` (report what's present) → `<lit> keys --init` (create/append slots,
append-only, never overwrites; prints the path) → user opens `keys.env` and pastes the keys they want
(in-session: `! $EDITOR ./keys.env`) → `<lit> keys` again, then proceed. Never block on keys.

- **`S2_API_KEY`** (free) — the one most worth setting; a dedicated 1 req/s for `search`/`snippet`/`cite`.
- **`OPENALEX_EMAIL`** (free, any email) — OpenAlex "polite pool" for faster `--source openalex|both`.
- **`OPENROUTER_API_KEY`** (paid) — enables `ask` (Perplexity Sonar); without it `ask` is disabled.
- **`BGPT_API_KEY`** (free for 50 results, then paid) — enables `bgpt` beyond the free tier.

## Constraints
- **Stdlib only** — never add a dependency or assume one is installed; it must run under bare `python3`.
- **Self-contained** — everything lives under this folder; no `../` escapes, no `docs/` links.
- **Fail closed to a fallback** — on any source error, emit `{"error","fallback"}` and exit non-zero
  rather than raising, so callers degrade cleanly.

© gaasher · MIT · gaasher/Agent-Loop-Skills

Similar skills

All skills for Science and research →

literature-search by other authors comes first.

literature-search lingzhi227 The literature-search skill queries Semantic Scholar, arXiv, and OpenAlex for peer-reviewed and preprint papers, returning structured results with authors, year, citation count, and BibTeX. CX Codex +1 2,700installs literature-search yorkeccak literature-search — a Claude Code skill that queries PubMed, arXiv, bioRxiv and medRxiv together using plain-language phrases. One command returns full texts, figures and relevance scores from all four databases. CX Codex +1 605installs literature-review lingzhi227 Conducts academic literature reviews by simulating multi-persona expert dialogue. Organizes retrieved papers and identifies research gaps for new survey papers. CX Codex +1 4,100installs Paper Search adamamer20 Paper Search — a remote MCP server that searches arXiv, PubMed, bioRxiv, medRxiv, Google Scholar, Semantic Scholar, IACR and CrossRef, downloads PDFs and pulls out text for literature reviews. CX Codex +1 59,106installs academic-search hongluu92 academic-search guides academic literature discovery across ArXiv, Semantic Scholar, and GitHub with structured queries. CX Codex +1 1installs systematic-literature-review bytedance The systematic-literature-review Claude Code skill synthesizes findings across academic papers on a topic. It searches arXiv and produces a cited report or annotated bibliography. CX Codex +1 2,500installs deep-research lingzhi227 deep-research runs a systematic academic literature review on a topic: finds papers, reads them, builds a database and writes a final report. Useful when you need the state of a field, not a few search hits. CX Codex +1 2,000installs academic-research-synthesizer davila7 academic-research-synthesizer — a Sonnet subagent designed to query arXiv and Semantic Scholar, inspect peer-review credentials, and compile structured literature overviews with confidence ratings. CX Codex 520installs

From the same set26

The whole set →
data-analysis The data-analysis skill explores a dataset by testing hypotheses and writes up findings backed by reproducible numbers. Use it for open-ended discovery, not to diagnose a known failure. CX Codex +1 ★ 185repo stars red-team red-team finds weaknesses in content filters, classifiers and APIs through adversarial stress-testing — generates attack inputs and builds a catalogue of failures. CX Codex +1 ★ 185repo stars prompt-optimize prompt-optimize is a Claude Code skill that iteratively refines an existing prompt against your evaluation command, keeping only edits that improve the score. CX Codex +1 ★ 185repo stars anomaly-investigation anomaly-investigation is a Claude Code skill that investigates a known spike, drop, or outlier by testing possible causes against data. CX Codex +1 ★ 185repo stars power-analysis power-analysis is a Claude Code skill for sizing a two-group study and drafting its preregistration. It runs during planning, before data collection, for A/B tests, simple RCTs, and evaluations of two models or configurations. CX Codex +1 ★ 185repo stars claim-verify claim-verify is a Claude Code skill that checks data-backed claims in draft reports against raw datasets. It recalculates metrics and stress-tests fragile conclusions. CX Codex +1 ★ 185repo stars literature-survey literature-survey is a Claude Code skill that maps research sources against claims. It runs for questions that need a cited survey of agreement, disputes, and gaps. CX Codex +1 ★ 185repo stars optimize-loop optimize-loop is a skill that runs an edit-measure-revert loop for code modules or SQL queries, keeping changes only when correctness holds and a cost metric falls. CX Codex +1 ★ 185repo stars

Project sponsors

Companies that keep this analytics open