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
/plugin marketplace add gaasher/Agent-Loop-Skills
/plugin install agent-loops@agent-loop-skillsWhat 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-skillsThis 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-code3Manually: put the files in place
~/.claude/skills/literature-search/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/literature-search/
1Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill literature-search -a codex2Manually: put the files in place
.agents/skills/literature-search/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill literature-search -a cursor2Manually: put the files in place
.cursor/skills/literature-search/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install gaasher/Agent-Loop-Skills loops/literature-search/SKILL.md2Manually: put the files in place
.github/skills/literature-search/SKILL.md1Skills CLI (Vercel)
npx skills add gaasher/Agent-Loop-Skills --skill literature-search -a gemini-cli2Platform CLI
gemini skills install https://github.com/gaasher/Agent-Loop-Skills --path loops/literature-searchManually: put the files in place
.devin/skills/literature-search/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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.