read-paper-local

name

read-paper-local

description

Read and work with local academic paper folders exported by ZoFiles from Zotero. TRIGGER when: user asks to read/summarize/cite/review/compare a paper that is already downloaded locally, references a local paper folder or path, works with paper.md/paper.bib/kimi.md files, browses the local paper library by topic, or asks to update/refresh the paper library directory structure. DO NOT TRIGGER when: user asks to search for papers online, find new papers, look up papers on a topic online, browse HuggingFace daily papers, or read a paper by arXiv ID without a local copy (use read-paper-online skill).

Reading Paper Folders

Paper folders are exported by ZoFiles from Zotero. Each folder is named {arxivId} - {title} and contains structured files about one academic paper.

Paper Library Location

The default paper library is at:

/Users/x1a/Local/ZoFiles/By Topic/

If this path doesn't exist (e.g. first-time setup or different machine), ask the user for their ZoFiles export root path.

Directory Structure

The library mirrors Zotero's collection hierarchy. Collections become directories, sub-collections become subdirectories, and paper folders sit at the leaves.

Key patterns:

• Allin/ directories appear when a collection has subcollections — contains all papers from that collection and every descendant (flat view of the entire subtree).
• Paper folders are named {arxivId} - {title} (e.g. 2512.18832 - From Word to World...).
• Find by arXiv ID: glob **/2512.18832* from the library root.
• Browse a topic: list the corresponding collection directory.
• See all papers: glob **/paper.md or **/arxiv.id recursively.

Current Library Snapshot

By Topic/
├── Agent/
│   ├── Agent/ (96 papers)
│   ├── Co-Evol/ (3 papers)
│   ├── CodeAgent/ (22 papers)
│   ├── WorldModel/
│   │   ├── Env Synthesis/ (14 papers)
│   │   ├── Forecaster/ (6 papers)
│   │   ├── Model-base RL/ (8 papers)
│   │   ├── Others/ (1 papers)
│   │   ├── UserSimulator/ (12 papers)
│   │   ├── WM Evaluation/ (11 papers)
│   │   ├── WM Survey/ (16 papers)
│   │   ├── WM Training-Free/ (4 papers)
│   │   ├── WM Training/ (9 papers)
│   │   └── Allin/ (100 papers, flat view)
│   └── Allin/ (169 papers, flat view)
├── Downstream/
│   ├── Code LLM/
│   │   ├── Text2SQL/ (40 papers)
│   │   └── Allin/ (43 papers, flat view)
│   └── Allin/ (43 papers, flat view)
├── Post Train/
│   ├── Analysis/ (38 papers)
│   ├── Efficient Resoning/ (45 papers)
│   ├── RL/
│   │   ├── LabelFree/ (21 papers)
│   │   ├── RLAIF/ (7 papers)
│   │   └── Allin/ (103 papers, flat view)
│   ├── RM/ (32 papers)
│   ├── TestTimeScaling/ (20 papers)
│   └── Allin/ (270 papers, flat view)
└── Allin/ (516 papers, flat view)

Use this snapshot to quickly orient yourself when the user asks about topics, collections, or paper counts — no need to scan the filesystem each time.

Updating the Directory Snapshot

When the user asks to update the directory structure (e.g. "更新目录", "update directory", "refresh library"):

bash scripts/scan-library.sh "/Users/x1a/Local/ZoFiles/By Topic/"

Then replace the content between <!-- AUTO-GENERATED --> and <!-- END AUTO-GENERATED --> markers in this file (~/.claude/skills/read-paper-local/SKILL.md) with the new output (wrapped in a ``` code block), and update the <!-- Last updated: ... --> date.

Files in a Paper Folder

File	What it is	When to read
paper.md	Full-text Markdown of the paper	Primary source. Read this for any paper-related task.
paper.bib	BibTeX citation entry	When citing. Always copy verbatim — never generate BibTeX yourself.
kimi.md	AI-generated review in Chinese (structured Q&A)	Quick overview without reading the full paper. Verify claims against paper.md.
arxiv.id	Plain text arXiv ID (e.g. 2505.17746)	When you need the identifier or arXiv URL.
notes/	User's personal notes (Markdown files)	When the user asks about their notes or annotations.
paper.pdf	Original PDF (or symlink)	Only if specifically asked — prefer paper.md.
figures/	Extracted figures from the paper	Use the /arxiv-figures skill to download figures into this directory if needed and not already present.

Not all files may be present. If a file is missing (e.g. no kimi.md or paper.md), skip it gracefully and work with what's available. Never tell the user a file "should" exist — just use alternative sources. For example, if paper.md is missing, fall back to paper.pdf; if kimi.md is missing, just read paper.md directly.

How to Read paper.md

paper.md starts with YAML frontmatter, then a table of contents, then the full text:

---
title: "Paper Title"
authors: ["Author 1", "Author 2"]
url: "https://arxiv.org/abs/XXXX.XXXXX"
sections: 27
estimated_tokens: "12.9k"
---
## Contents
- 1 Introduction
- 2 Related Works
  - 2.1 ...
...

Reading strategy:

1. Always start with frontmatter + ToC — gives you structure, size, and lets you plan what to read
2. Read selectively — use the ToC to jump to relevant sections; don't read the whole paper unless asked
3. Quick overview → Introduction + Conclusion
4. Methodology → Methods/Approach section
5. Results → Experiments/Results/Evaluation sections

For large papers (>15k tokens), use offset/limit on the Read tool. Ask yourself which sections actually answer the user's question.

Citations

Always read paper.bib and copy the BibTeX entry exactly as-is. Never modify, reformat, or regenerate BibTeX — hand-generated citations often contain errors. The exported BibTeX is sourced from arXiv and is authoritative.

Common Tasks

User request	What to do
"Summarize this paper"	Read paper.md: Introduction + Conclusion. Optionally skim kimi.md for a second perspective.
"What's the main contribution?"	Read the Introduction section of paper.md.
"Give me the BibTeX"	Read paper.bib, copy verbatim.
"Compare these papers"	Read paper.md from each folder (Introduction + Methods + Results).
"What did I note about this?"	Read files in the notes/ directory.
"What's the arXiv ID?"	Read arxiv.id.
"更新目录" / "Update directory"	Run scan-library.sh, update the snapshot in this file.