agentleFS
a-attiaa-attia/scicomp-research-skills/skills/literature-survey/SKILL.md

literature-survey

Skill13 starsChanged 33 days agoMITView on GitHub

Find, verify and maintain a literature-survey corpus for a research paper -- searching arXiv / OpenAlex / Crossref / zbMATH / OSTI / Semantic Scholar for candidates, then BibTeX entries, published-manuscript PDFs, text extractions for AI consumption, per-paper survey notes (~30-50 lines each), and a collection log tracking verification status, corrections and searches. Use when starting a new paper that needs a literature review, when searching for related work or prior art, when adding new references to an existing paper, or when migrating an unverified bib file to a verified one.

  • Installs packages

8 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 6 are distinctive, and 5 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Add a verified BibTeX entry to references/bibliography.bib.

    line 39
  2. Very specific:

    Write a survey note notes/survey_<citekey>.md.

    line 42
  3. Very specific:

    Add the entry to references/bibliography.bib.

    line 89
  4. Distinctive:

    When a verified entry corrects an earlier unverified entry, document the correction in the collection log (Step 5).

    line 107
  5. Distinctive:

    If the published PDF is paywalled and only an arXiv preprint is available, use the preprint and explicitly document this in the collection …

    line 122
  6. Very specific:

    Read the .txt extraction, then write notes/survey_<citekey>.md to ~30-50 lines covering the structure in references/survey-note-template.md …

    line 160
  7. Distinctive:

    Test cases + parameters used in the paper.

    line 174
  8. Distinctive:

    Re-read the source: When writing the paper's related-work section, re-open the survey note (and if needed the .txt extraction) rather than …

    line 211
  9. Very specific:

    Track corrections: If you discover a mis-attribution (wrong author list, wrong year, wrong arXiv ID), log it explicitly in …

    line 214
  10. Distinctive:

    When the user invokes this skill, the agent should:

    line 234
  11. Distinctive:

    After processing, summarise in a single message:

    line 240

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Literature Survey

When to load this skill

Load this skill when the user is:

  • looking for related work, prior art, or papers on a topic (Step 0)
  • starting a new research paper that needs a literature review
  • adding new references to an existing paper
  • migrating an unverified BibTeX file to a verified one
  • doing a deep-read pass on a set of references and producing per-paper notes
  • needing a reproducible record of which references have been verified vs which are still placeholders

Overview

A research paper's bibliography drives credibility. Stale, mis-attributed, or unverified entries embarrass the author at submission time. This skill defines a workflow of five steps plus an optional Step 0 (finding candidates) for building a verified literature corpus and a deliverables structure that future-you (or a collaborator) can audit and extend.

The steps:

  1. (When candidates are not yet in hand) Find them: see "Step 0" below.
  2. Add a verified BibTeX entry to references/bibliography.bib.
  3. Drop the published-manuscript PDF into references/pdf/<citekey>.pdf.
  4. Generate a text extraction for AI consumption.
  5. Write a survey note notes/survey_<citekey>.md.
  6. Append a row to references/_collection_log.md.

Each step is described in detail below, plus the directory layout, the survey-note template, and the collection-log template.

Directory layout

<paper-repo>/
  references/
    bibliography.bib          -- BibTeX (tracked); every entry verified
    _collection_log.md        -- per-paper verification status + corrections + notes
    pdf/                      -- published-manuscript PDFs (gitignored)
      <citekey>.pdf
      <citekey>-supp.pdf      -- supplementary material where applicable
      .txt/                   -- pdftotext -layout extractions (gitignored)
        <citekey>.txt
  notes/
    survey_<citekey>.md       -- per-paper survey note (~30-50 lines)
    README.md                 -- index of survey notes (by section, by affinity)

The references/pdf/ directory and its .txt/ cache should be gitignored; the bibtex + collection log + survey notes are tracked.

Step 0: Finding candidate papers

Skip this step when the user hands you the papers. Otherwise, before Step 1, load references/literature-search.md from this skill. It covers:

  • choosing a strategy (snowball / systematic / exploratory), and when a "no prior work does X" claim needs the systematic one;
  • where to search for scientific computing (arXiv math.NA and friends, OpenAlex, Crossref, zbMATH, SIAM, OSTI, Semantic Scholar, Google Scholar);
  • programmatic lookups (arXiv, OpenAlex, Crossref, OSTI APIs) and DOI-to-BibTeX as the hand-off to Step 1;
  • triage (must read / should read / cite only / drop) and the search-log table that goes in references/_collection_log.md.

Each kept candidate enters Step 1 with a DOI or arXiv ID. A DOI-resolved BibTeX record is a starting point, not a verified entry.

Step 1: Verified BibTeX entry

Add the entry to references/bibliography.bib. Required fields: must include venue + page numbers + DOI or arXiv ID. Reject placeholder entries (e.g. "Author, A. (year). Title. Some Venue. [VERIFY]"); these go in a separate "pending" section of the bib file or are tagged with note = {pending verification}.

Verification criteria for an entry to be considered "verified":

  • author list matches the published manuscript (not arXiv preprint if the two differ)
  • year is the published year (not arXiv submission year), unless the entry is genuinely arXiv-only
  • venue + volume + issue + pages all match the published version
  • DOI or arXiv ID is correct (verify by webfetch of the publisher page or the arXiv abstract page)
  • citekey follows project convention (typically lastname + year + short-tag, e.g. foster2021dad)

When a verified entry corrects an earlier unverified entry, document the correction in the collection log (Step 5). Do NOT silently overwrite.

Step 2: PDF acquisition

Drop the published-manuscript PDF into references/pdf/<citekey>.pdf, where <citekey> matches the BibTeX citekey exactly. Supplementary material goes as <citekey>-supp.pdf.

The PDFs are gitignored (they're typically large; copyright varies; not appropriate for tracked content). The references/pdf/ directory itself should also be gitignored (or the directory tracked but the *.pdf glob ignored, depending on your project's convention -- see the .gitignore template in templates/paper-skeleton/).

If the published PDF is paywalled and only an arXiv preprint is available, use the preprint and explicitly document this in the collection log so a future reader knows to upgrade when access becomes available.

Step 3: Text extraction

Most AI agents cannot consume PDF binaries directly. Generate a layout-preserving text extraction once, then read it whenever a deep dive is needed:

mkdir -p references/pdf/.txt
pdftotext -layout references/pdf/<citekey>.pdf references/pdf/.txt/<citekey>.txt

pdftotext ships with poppler-utils (Linux: apt install poppler-utils; macOS: brew install poppler). The -layout flag preserves the two-column structure of typical academic papers, which makes the output much more readable than the default flow-mode extraction.

For supplementary material, repeat with <citekey>-supp.pdf -> .txt/<citekey>-supp.txt.

The .txt/ directory is gitignored; it is a regenerable cache.

Batch conversion of all PDFs in one go:

mkdir -p references/pdf/.txt
for pdf in references/pdf/*.pdf; do
  base=$(basename "$pdf" .pdf)
  pdftotext -layout "$pdf" "references/pdf/.txt/${base}.txt"
done

Step 4: Per-paper survey note

Read the .txt extraction, then write notes/survey_<citekey>.md to ~30-50 lines covering the structure in references/survey-note-template.md (loaded on demand from this skill's references/ subfolder when needed).

The survey note is the primary artefact of this workflow: it is what future-you reads when drafting the paper's related-work section, and it is what a collaborator reads to get up to speed without re-reading every PDF.

Briefly, a good survey note has these sections:

  1. Header: citekey, full citation, PDF path.
  2. Headline claim (one sentence).
  3. Method (full detail with key equations in MathJax).
  4. Test cases + parameters used in the paper.
  5. Headline numerical results.
  6. Relevance to our paper (why we cite this; in which sections).
  7. Critical observations (insights NOT in the abstract).
  8. Action items for our paper draft.

Load references/survey-note-template.md from this skill for the full template + a worked example.

Step 5: Collection log

Append a row to references/_collection_log.md documenting:

  • citekey
  • verification status (verified / arXiv-only / placeholder)
  • date verified
  • any corrections made vs an earlier entry
  • any quirks worth noting (e.g. "supplementary material is essential", "v3 of the arXiv preprint is significantly different from v1")

The collection log serves as the audit trail. When a reviewer asks "how did you decide on this citation?" or when you discover a mis-attribution months later, the log is where you check.

Load references/collection-log-template.md from this skill for the template.

Workflow rules

  1. Never cite a paper you have not verified. Placeholder entries are acceptable in references/bibliography.bib only if they are tagged explicitly (e.g. note = {pending verification}) and marked in the collection log as such.
  2. Survey-note quality matters more than count. A short paper with 5 well-written survey notes is more useful than a long one with 25 superficial ones. If a note would just restate the abstract, skip it and link the abstract instead.
  3. Re-read the source. When writing the paper's related-work section, re-open the survey note (and if needed the .txt extraction) rather than relying on memory or your initial summary.
  4. Track corrections. If you discover a mis-attribution (wrong author list, wrong year, wrong arXiv ID), log it explicitly in _collection_log.md. Do NOT silently fix it -- the audit trail is what makes the corpus trustworthy.
  5. MathJax for equations. Survey notes use MathJax ($...$ inline, $$...$$ display) for any equations transcribed from the source. ASCII-art math is forbidden in survey notes.
  6. Survey notes and the collection log are HUMAN-FACING documents. Both are read by the user when drafting the paper, by co-authors when re-orienting, and (sometimes) by reviewers. They follow the conventions in the human-facing-doc-authoring skill (audience split, narrative prose over telegraphic fragments, tables where they aid scanning, date-stamps, no personal-path leaks). When producing or substantially revising either artefact, also load ~/.scicomp-research-skills/skills/human-facing-doc-authoring/SKILL.md for the universal conventions and the per-doc-type self-review checklist.

Output contract

When the user invokes this skill, the agent should:

  1. Confirm or create the directory layout (Section "Directory layout") if it does not exist.
  2. Walk through the 5 steps for each paper the user provides (interactively or in batch).
  3. After processing, summarise in a single message:
    • Citekeys added.
    • Verification status of each.
    • Any corrections discovered vs prior entries.
    • PDFs missing (if any).
    • Survey notes written.
    • Suggested next step (typically: read the survey notes, then update the paper's plan-of-record / Section 1 reading list).

See also

  • references/literature-search.md -- Step 0: search strategies, sources, programmatic lookups, triage, and the search log. Adapted from genesis-skills literature-search (Apache-2.0).
  • references/survey-note-template.md -- the canonical survey-note template + worked example.
  • references/collection-log-template.md -- the canonical collection-log template + worked example.
  • templates/paper-skeleton/ (in this repository, sibling of skills/) -- a starter paper-repo skeleton that pre-creates the references/ and notes/ directory structure.
  • ~/.scicomp-research-skills/skills/human-facing-doc-authoring/SKILL.md -- universal conventions for human-facing docs. The survey-note + collection-log templates above embody these conventions; load the human-facing-doc-authoring skill when authoring or revising either artefact and you want the cross-cutting checklist.
  • ~/.scicomp-research-skills/skills/agent-resource-discipline/SKILL.md -- a literature-survey pass typically processes many PDFs and iterates across sessions, so it is one of the heaviest token consumers in this ecosystem. Load this skill (and in particular its agent-resource-discipline/references/pdf-lifecycle.md and agent-resource-discipline/references/persistent-memory.md) at the start of any non-trivial literature pass: it codifies the one-shot pdftotext + survey-note-first lookup pattern, the context-window budget for handling many references, and the first-/ last-action index-update protocol that makes a multi-session pass cheap.

Created 2026-05-13 by A. Attia. Distilled from the literature-survey workflow developed for a research paper (14 references verified across 3 sections of the paper's plan-of-record). Revised 2026-05-13 (added Workflow rule #6 + See-also pointer to human-facing-doc-authoring skill, since survey notes and the collection log are human-facing artefacts). Revised 2026-05-13 (added See-also pointer to agent-resource-discipline skill, since a literature-survey pass is PDF-heavy + multi-session and therefore benefits explicitly from the PDF-lifecycle + persistent-memory + context-window-budget protocols that skill codifies). Revised 2026-10-14 (added Step 0 "Finding candidate papers" + references/literature-search.md, adapted from the Apache-2.0 genesis-skills literature-search skill by I. Foster; description extended to cover finding papers).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.