agentleFS
arthur-plautzarthur-plautz/research-toolkit/.claude/skills/references/SKILL.md

references

Skill0 starsChanged 4 months agoMITView on GitHub

Triggered automatically whenever Claude introduces, cites, or uses any new reference — from web search, deep research, or any external source. Governs how references are saved and cited.

10 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, 8 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 8

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    All new information or synthesis must be grounded in scientific evidence:

    line 18
  2. Distinctive:

    Every claim that is not common knowledge must be backed by a cited paper or book

    line 20
  3. Distinctive:

    Only peer-reviewed publications, conference proceedings, or established academic books are valid sources

    line 21
  4. Distinctive:

    Do not cite blog posts, documentation, or informal sources as evidence

    line 22
  5. Distinctive:

    Before including any reference, assess:

    line 26
  6. Distinctive:

    Do not let the citing context bias the summary: If the paper was cited because of one method, still describe the full paper, not just that …

    line 42
  7. Distinctive:

    Do not synthesize or extrapolate: Every claim in Introduction, Method, Results, Discussion, and Conclusion must be attributable to the …

    line 44
  8. Very specific:

    If Step 1 returns NOT_FOUND, write a skeleton reference doc with all content sections set to {Not available — paper not read} and stop.

    line 73
  9. Very specific:

    Write docs/references/{slug}.md with the full template structure — header metadata and one placeholder per section — before any extraction …

    line 79
  10. Distinctive:

    Do not pass any information about why the paper is being cited, the current task, or how the paper relates to this project.

    line 150
  11. Very specific:

    All PDF papers stored in docs/papers/ must follow:

    line 175

“Common” is measured: kept by at least 6 in 10 of the 8 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

Trigger

This skill activates automatically whenever Claude:

  • Cites a paper or book not already in docs/references/
  • Uses a result from web search or deep research that involves a paper, book, or academic source
  • Introduces a new method, concept, or claim backed by an external reference

It is not a user-invoked command. It fires on Claude's own citation behavior.

Grounding policy

All new information or synthesis must be grounded in scientific evidence:

  • Every claim that is not common knowledge must be backed by a cited paper or book
  • Only peer-reviewed publications, conference proceedings, or established academic books are valid sources
  • Do not cite blog posts, documentation, or informal sources as evidence

Relevance criteria

Before including any reference, assess:

  1. Direct relevance — does this paper address the same problem, method, or domain being discussed?
  2. Strength of connection — is the relationship between the reference and the topic clear and specific, not just superficially related?
  3. Academic standing — is it published in a recognized venue or widely cited in the field?

If a reference does not pass all three criteria, do not include it. Prefer fewer, highly relevant references over a broad list of loosely related ones.

Reviews as light references

A docs/reviews/{id}.md document (produced by /literature-review) may be cited as a light reference — a shorthand for "see this review's synthesis of the topic" — in places where a quick pointer is more useful than restating the underlying sources. This does not replace the grounding rule in CLAUDE.md: a review is an internal project doc, so citing it alone does not ground a scientific or mechanistic claim. Any claim that needs grounding must still trace to a specific paper in the review's own References table — cite that paper directly, not the review, for the actual claim. Light references to a review are appropriate for scoping/orientation statements ("see docs/reviews/{id}.md for the broader landscape on this topic"), not for backing a directional or mechanistic claim.

Objectivity guardrails

Reference documents must reflect the paper as the authors wrote it — not as this project uses it.

  • Do not let the citing context bias the summary. If the paper was cited because of one method, still describe the full paper, not just that method.
  • Do not frame the paper in terms of this project. Sentences like "this is the basis for X in this project" belong only in the Relevance column of the References table in the citing document, not in the reference summary itself.
  • Do not synthesize or extrapolate. Every claim in Introduction, Method, Results, Discussion, and Conclusion must be attributable to the authors. Do not add interpretation or implications that the authors did not state.
  • If the paper is not available, fill each section with {Not available — paper not read} rather than inferring content from citations, project code, or secondary sources. A placeholder is always preferable to plausible-sounding fabrication.
  • Reference docs are strictly paper-only. No sentence in any section of a reference doc may mention this project, the citing context, or how the paper is used here. This prohibition applies to all agents and to the main agent — no post-pipeline edits may add context information to a reference doc. Project relevance belongs exclusively in the Relevance column of the References table in the citing document.

Index

docs/references/INDEX.md lists every reference doc in one table: title, authors, year, a one-line topic, and a link to the doc. With the number of references in this project, it is the fastest way to check whether a paper is already covered or to find one by subject — check it before spawning reference-fetcher for a paper that might already be saved.

Saving a reference

Whenever a new reference is used, run the following pipeline. Do not write the reference doc yourself.

Step 1 (fetch)       →  PDF saved to docs/papers/{slug}.pdf
Step 2 (initialize)  →  skeleton .md written by main agent, row added to INDEX.md
Steps 3–10 (extract) →  one subagent call per section, sequentially

Step 1 — Fetch PDF

Spawn subagent_type: "reference-fetcher" (defined in .claude/agents/reference-fetcher.md). Pass a prompt containing:

  • Paper metadata: title, authors, year, DOI/URL, arXiv ID if known
  • The target slug and path: docs/papers/{slug}.pdf

The agent returns SAVED: docs/papers/{slug}.pdf on success or NOT_FOUND: {reason} if no open-access PDF was found.

If Step 1 returns NOT_FOUND, write a skeleton reference doc with all content sections set to {Not available — paper not read} and stop.


Step 2 — Initialize skeleton

Write docs/references/{slug}.md with the full template structure — header metadata and one placeholder per section — before any extraction agent runs. Use this template exactly:

Immediately after, append one row to docs/references/INDEX.md's table: title, authors, year, a one-line topic (your own judgment of the paper's subject area, matching the granularity of existing rows), and a relative link to the new doc. Keep the table sorted by year, oldest first, and renumber the # column if the insertion isn't at the end.

# {Title}

**Authors:** {Full author names}
**Year:** {Year}
**Venue:** {Journal / Conference / Book}
**DOI / URL:** {DOI or URL}

---

## Abstract

{Not yet extracted}

---

## Summary

{Not yet extracted}

---

## Introduction

{Not yet extracted}

---

## Method

{Not yet extracted}

---

## Results

{Not yet extracted}

---

## Discussion

{Not yet extracted}

---

## Conclusion

{Not yet extracted}

---

## References

{Not yet extracted}

Steps 3–10 — Extract sections

Spawn subagent_type: "reference-extractor" once per section, sequentially (all calls edit the same file). For each call, pass only:

  • PDF path: docs/papers/{slug}.pdf
  • Output path: docs/references/{slug}.md
  • Target section name

Do not pass any information about why the paper is being cited, the current task, or how the paper relates to this project.

Override the model per section using the Agent tool's model parameter:

SectionModel
Abstracthaiku
Summaryhaiku
Introductionhaiku
Methodsonnet
Resultssonnet
Discussionhaiku
Conclusionhaiku
Referenceshaiku

Each agent reads the existing .md to locate its placeholder, reads the relevant PDF pages, and uses Edit to replace the placeholder with extracted content.


Slug format

{authors}-{year}-{short-title} in kebab-case. See the Paper filename pattern section below for examples and edge cases.

Paper filename pattern

All PDF papers stored in docs/papers/ must follow:

{authors}-{year}-{short-title}.pdf
  • authors — all co-authors' last names, hyphen-separated, lowercase
  • year — 4-digit publication year
  • short-title — 3–5 word kebab-case slug of the title

Examples:

  • milano-nolfi-2021-automated-curriculum-neuroevolution.pdf
  • salimans-2017-es-scalable-alternative-rl.pdf
  • breiman-2001-random-forests.pdf

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.