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
- 2743959925-netizen/claude-skillstheir own version, first seen Nov 16, 2026
- charlesmsiegel/coding-skillstheir own version, first seen Nov 15, 2026
- DanieleMosh/almagest-surveytheir own version, first seen Oct 15, 2026
- JihaoXin/paper-machinetheir own version, first seen Oct 15, 2026
- yqi96/warrantedtheir own version, first seen Aug 13, 2026
- haozhou-wong/haozhou-skillstheir own version, first seen Jul 27, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- stc980309-pixel/In-depth-research★ 17same name
- yqi96/warranted★ 3same name
- charlesmsiegel/coding-skills★ 2same name
- DanieleMosh/almagest-survey★ 1same name
- haozhou-wong/haozhou-skills★ 1same name
- yicheng-fu/skills★ 1same name
- 2743959925-netizen/claude-skills★ 0same name
- JihaoXin/paper-machine★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository7 other files it gives its agents.
- AGENTS.mdAGENTS.md
- agent-resource-disciplineSkill
- human-facing-doc-authoringSkill
- project-onboardingSkill
- research-paper-writingSkill
- research-slides-authoringSkill
- research-software-engineeringSkill
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
- Very specific: line 39
Add a verified BibTeX entry to references/bibliography.bib.
- Very specific: line 42
Write a survey note notes/survey_<citekey>.md.
- Very specific: line 89
Add the entry to references/bibliography.bib.
- Distinctive: line 107
When a verified entry corrects an earlier unverified entry, document the correction in the collection log (Step 5).
- Distinctive: line 122
If the published PDF is paywalled and only an arXiv preprint is available, use the preprint and explicitly document this in the collection …
- Very specific: line 160
Read the .txt extraction, then write notes/survey_<citekey>.md to ~30-50 lines covering the structure in references/survey-note-template.md …
- Distinctive: line 174
Test cases + parameters used in the paper.
- Distinctive: line 211
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 …
- Very specific: line 214
Track corrections: If you discover a mis-attribution (wrong author list, wrong year, wrong arXiv ID), log it explicitly in …
- Distinctive: line 234
When the user invokes this skill, the agent should:
- Distinctive: line 240
After processing, summarise in a single message:
“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.
Files
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:
- (When candidates are not yet in hand) Find them: see "Step 0" below.
- Add a verified BibTeX entry to
references/bibliography.bib. - Drop the published-manuscript PDF into
references/pdf/<citekey>.pdf. - Generate a text extraction for AI consumption.
- Write a survey note
notes/survey_<citekey>.md. - 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>.txtpdftotext 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"
doneStep 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:
- Header: citekey, full citation, PDF path.
- Headline claim (one sentence).
- Method (full detail with key equations in MathJax).
- Test cases + parameters used in the paper.
- Headline numerical results.
- Relevance to our paper (why we cite this; in which sections).
- Critical observations (insights NOT in the abstract).
- 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
- Never cite a paper you have not verified. Placeholder entries are
acceptable in
references/bibliography.bibonly if they are tagged explicitly (e.g.note = {pending verification}) and marked in the collection log as such. - 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.
- 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.
- 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. - MathJax for equations. Survey notes use MathJax (
$...$inline,$$...$$display) for any equations transcribed from the source. ASCII-art math is forbidden in survey notes. - 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-authoringskill (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.mdfor the universal conventions and the per-doc-type self-review checklist.
Output contract
When the user invokes this skill, the agent should:
- Confirm or create the directory layout (Section "Directory layout") if it does not exist.
- Walk through the 5 steps for each paper the user provides (interactively or in batch).
- 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-skillsliterature-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 ofskills/) -- a starter paper-repo skeleton that pre-creates thereferences/andnotes/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 itsagent-resource-discipline/references/pdf-lifecycle.mdandagent-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).
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
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.

