papers

---
name: papers
description: "Find, read and compare scientific papers without spending the conversation's context on them: a shortlist of identifiers for a topic, a bounded digest of one paper by a reading subagent, a comparison of several, and a note in the user's vault only when they say so. Sources: paper-search, as an MCP server or a CLI (arXiv, Semantic Scholar, OpenAlex and more). Use when the user asks to find papers on a topic, look up a DOI or arXiv id, summarise or critique a scientific article, compare papers, or write a literature note. Not for a web page, a blog post or a news article, which is a plain fetch. Triggers: papers, paper, preprint, arXiv, DOI, PubMed, literature review, systematic review, meta-analysis, related work, state of the art, what does the research say, what do my papers say, научные статьи, по моим статьям, найди статьи, препринт, обзор литературы, мета-анализ, литература по теме, найди источники, есть ли работы про, что говорят исследования, разбери статью, конспект научной статьи, сравни статьи"
license: MIT
---

# papers

Scientific papers are long and PDFs are worse: the text of one paper is a large fraction of a conversation's context, and a survey is several of them. This skill keeps the reading out of the main conversation. The master finds and decides; a subagent with its own context reads and returns a digest of bounded length; the master synthesises across digests and, only when the user says so, files one as a note

## Runtime

- **Sources** come from [paper-search-mcp](https://github.com/openags/paper-search-mcp) as an MCP server or the `paper-search` CLI. MCP clients assign their own namespace, so discover the callable names corresponding to `search_papers`, `read_SOURCE_paper` and `download_with_fallback` from the harness's tool catalog rather than spelling a client-specific prefix. Prefer MCP when available because the fallback downloader and per-source readers exist only there; otherwise `paper-search search|download|read|sources` prints JSON or text. Check availability once per session through the tool catalog or `command -v paper-search`; when neither exists, report the missing capability and stop rather than inventing a citation
- **Keys** are optional and never pass through the conversation: the server reads an env file named by `PAPER_SEARCH_MCP_ENV_FILE` or `~/.config/paper-search-mcp/.env`. Without them Semantic Scholar shares an anonymous rate limit, CORE fails often and Unpaywall is skipped, which is the legal open-access fallback; [references/sources.md](references/sources.md#keys-and-limits) names the variables
- **Downloads** go to one place, `~/.cache/papers/`, passed as `save_path` on every call; the default `./downloads` litters whatever directory the session happens to be in
- **Subagents** use an isolated context and an explicitly selected, balanced reading model unless the user names another. If the launcher exposes no model selector, state that constraint before delegating. Tell every reader not to spawn subagents of its own. Reading is delegated; judgement is not

## Modes

Say which mode you are in. A request usually chains them: `search` → `read` → `note`, or `search` → `review`

**search** — a topic, optional constraints (years, field, open access), and the user's actual question. Pick the sources by area from [references/sources.md](references/sources.md#sources-by-area); default to `search_papers` with two or three sources and `max_results_per_source` of 5. When the sweep is that narrow, run it in the master. When it is wider, or the user wants exhaustiveness, delegate to a scout subagent that runs the searches and returns at most ten candidates as `identifier, source, title, year, venue, one line why` and nothing else; the master never receives abstracts in bulk. Present the shortlist as a table with identifiers the next mode can act on, and say which sources answered and which returned nothing. Nothing found is a result, not a failure

**read** — one identifier: an arXiv id, a DOI, a PMID, a URL, a title from a previous shortlist, or a PDF the user already has. Resolve the source and id with the table in [references/sources.md](references/sources.md#identifiers), a local file needs no resolution, then spawn one reading subagent with the prompt in [references/reader.md](references/reader.md): it obtains the text, reads it, and returns a digest in the shape of [references/digest-template.md](references/digest-template.md), within the template's bound, in the language of the conversation. Show the digest as received, add your own reading of what it means for the user's question, then offer `note`. If the subagent reports that only the abstract was reachable, or that nothing was, say so before anything else

**review** — several identifiers or a shortlist. One reading subagent per paper, one at a time; up to three in parallel only when the user asks for speed, since the sources rate-limit. Then synthesise in the master from the digests alone: a comparison table on the axes the user's question implies, agreements, contradictions, and the gaps, each claim tied to an identifier. Do not re-read a paper to settle a contradiction; spawn a reading subagent with the specific question instead

**note** — after a digest or a review, ask once whether to save it; never write into a vault unasked. On yes, read `$OBSIDIAN_VAULT_PATH/.claude/papers/profile.yml` ([references/profile.md](references/profile.md)): it names the vault's style skill, the preset and the folder, and the note is written through that skill in its language, never in a shape invented here. Without a profile, ask for a path and write plain Markdown with the digest under the frontmatter [references/profile.md](references/profile.md#without-a-profile) names. Keep the PDF only when the profile names an attachments folder

**corpus** — a question across every paper in a folder at once: "what evidence do my papers hold for X", "which of them measured Y". That is retrieval, not reading, and PaperQA2 does it with a local embedding model: `pqa-evidence -s <preset> -k 8 "<query>"` returns only the retrieved passages, each under its paper and chunk, and the master writes the synthesis itself, because a local model retrieves as well as any and reasons less well than the master. It runs in the master, and `-k` is the bound on what enters the context; a query is a few keywords or a short phrase, not the whole question, and it reaches only the few papers one index search brings up, so no evidence is not yet proof of absence ([references/paperqa.md](references/paperqa.md#limits)). `pqa -s <preset> ask "<question>"` has PaperQA2's own local model write one cited paragraph instead; take it only when the user wants the conversation's context spared, and expect a minute of GPU time per question. [references/paperqa.md](references/paperqa.md) has the preset, the folder, how to add papers and when the corpus is too small for this to beat `review`. When `pqa` is not on PATH, say so and fall back to `review`

## The reading subagent

One paper, one subagent, one digest. The contract is what makes the mode cheap, so it is not softened:

- The subagent gets the identifier, the user's question, the save path, the path of the digest template, and the rules in [references/reader.md](references/reader.md); it reads the template itself
- It calls `read_<source>_paper` first; when that fails it calls `download_with_fallback` and reads the PDF with the harness's file-reading capability; when the CLI is the only path it runs `paper-search read <source> <id> -o <save_path>`
- It returns the digest and nothing else: no raw text, no quotes longer than a sentence, no table of contents. The one exception is a single sentence naming what it could not read
- It states, in the digest's last field, what it actually read: full text, or abstract only, or a truncated extraction
- It never spawns subagents, never writes outside the save path, never touches the vault

## Never

- Read a PDF, call `read_*_paper`, `download_*`, or `paper-search read` in the master; that is the whole point of the reading subagent
- Paste abstracts or full search results into the conversation; a shortlist is identifiers plus one line each
- Put an API key into a prompt, a command line, or a note
- Present a digest as the paper's claim without saying what the subagent actually read, or turn a failure line into a digest from memory
- Go to Google Scholar first: it is a scraper with a session limit, and every source it knows is covered elsewhere ([sources.md](references/sources.md#known-pitfalls))
- Invent a reference; every identifier in a report came from a tool result

## Before the report

- The mode was named, and the user's actual question shaped the search or the digest, not just the topic
- Every identifier came from a tool result and is spelled so the next mode can use it
- Each digest says what the subagent read, and a partial read is stated first
- The synthesis of a review cites identifiers per claim and names the contradictions instead of averaging them
- The note question was asked once, and the note went through the profile's style skill

## Which reference when

| Question | Read |
|---|---|
| Which source for which area, how identifiers map to tools, keys, limits and the server's known traps | [references/sources.md](references/sources.md) |
| What to tell the reading subagent, word for word | [references/reader.md](references/reader.md) |
| The digest's fields and bounds | [references/digest-template.md](references/digest-template.md) |
| The profile a vault owner writes so notes land in their style and folder | [references/profile.md](references/profile.md) |
| The corpus mode: PaperQA2's preset, folder, commands and limits | [references/paperqa.md](references/paperqa.md) |