agentleFS
JihaoXinJihaoXin/paper-machine/skills/literature-survey/SKILL.md

literature-survey

Skill0 starsChanged 3 months agoMITView on GitHub

Ground a paper in real prior work, and handle the case where the research tool fails. Use at the start of a paper, when writing related work, or when a deep-research call returns nothing. Prevents shipping a confident paper with no literature behind it.

7 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

3 rules. 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Search, then read what came back: Use Semantic Scholar, arXiv, DBLP or CrossRef.

    line 17
  2. Distinctive:

    Note what would make your idea unnecessary: If a paper already does what you propose, the honest move is to say so and narrow the …

    line 30
  3. Distinctive:

    Fall back, do not skip: If deep research stays unavailable, build a smaller survey from direct academic search.

    line 49

“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

What this phase owes the paper

Two things: a set of real papers you have actually seen, and an honest account of where your idea sits among them. Everything downstream depends on it. A related-work section written from the model's memory of a field is where invented citations come from.

Doing the survey

Search, then read what came back. Use Semantic Scholar, arXiv, DBLP or CrossRef. Collect titles, authors, years, venues and abstracts from the API response, not from recall.

Record the bibliography as you go, through the API, following citation-discipline. Do not plan to reconstruct citations later from the prose. Reconstruction is where fabrication enters.

Look for the limitation, not just the topic. The useful sentence in a related-work section is "X does A but assumes B, which does not hold here". That requires reading abstracts, and often the limitations paragraph of the papers themselves.

Note what would make your idea unnecessary. If a paper already does what you propose, the honest move is to say so and narrow the contribution. Finding this out at writing time is cheap. Finding it out in review is not.

When the research tool fails

Deep-research APIs fail in ways that do not look like failures. A real case: the provider returned HTTP 200 with a body containing nothing but keep-alive padding, because the upstream model died mid-generation. The naive client raised a JSON parse error, the pipeline logged a warning, and then wrote an entire paper with zero literature behind it. Nobody was told.

Handle it explicitly:

  1. Recognise the shapes. An empty body, a whitespace-only body, or a stream of comment lines are all "the provider produced nothing". Say that, rather than surfacing a parser traceback.
  2. Retry. These are usually transient. Two retries with backoff.
  3. Fall back, do not skip. If deep research stays unavailable, build a smaller survey from direct academic search. It is thinner, but it is real, and the paper still has ground under it.
  4. Mark the degradation in the paper and in your report. "Related work was assembled from direct database search rather than a full survey; coverage is partial" is an acceptable sentence. Silence is not.

The principle generalises: a thinner foundation is acceptable, an invisible one is not.

Before moving on

  • Every reference came from an API response you read
  • You can state, in one sentence, what is new here relative to the closest prior work
  • You have noted anything that weakens the novelty claim
  • If the survey degraded, the paper says so

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.