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 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 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; 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, a local file needs no resolution, then spawn one reading subagent with the prompt in references/reader.md: it obtains the text, reads it, and returns a digest in the shape of 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): 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 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). 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 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; it reads the template itself
• For a biomedical paper it runs tools/pmc_text.py first, which saves PMC's open-access text; otherwise, or when PMC has none, it calls read_<source>_paper; when that fails it calls download_with_fallback and reads the file only if it is a real PDF; 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_*, paper-search read or tools/pmc_text.py 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)
• 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