| 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.
