| name | read-paper |
| description | How to read and work with academic paper folders exported by ZoFiles.
Each paper folder (named like `{arxivId} - {title}`) contains structured files: paper.md (full text), paper.bib (citation), kimi.md (AI review), arxiv.id, notes/, and paper.pdf.
Use this skill whenever the user asks you to read a paper, summarize a paper, cite a paper, review a paper, compare papers, or work with any folder that contains paper.md/paper.bib/kimi.md files — even if they don't mention "ZoFiles" explicitly.
Also use when the user asks to update/refresh the paper library directory structure (e.g. "Update paper library directory structure", "refresh paper library").
|
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 paper library is at:
<FILL_IN: ask the user for their ZoFiles export root path, then update this file>
First-use setup: If the path above says <FILL_IN...> or doesn't exist, ask the user: "What's the path to your ZoFiles paper library?" Then:
- Update the path above
- Run
scan-library.sh to populate the directory snapshot (see Updating the Directory Snapshot)
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
<FILL_IN: run the scan script below to populate this snapshot>
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 .claude/skills/read-paper/scripts/scan-library.sh "<library_root>"
Then replace the content between <!-- AUTO-GENERATED --> and <!-- END AUTO-GENERATED --> markers in this file 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. |
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"
---
- 1 Introduction
- 2 Related Works
- 2.1 ...
...
Reading strategy:
- Always start with frontmatter + ToC — gives you structure, size, and lets you plan what to read
- Read selectively — use the ToC to jump to relevant sections; don't read the whole paper unless asked
- Quick overview → Introduction + Conclusion
- Methodology → Methods/Approach section
- 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. |
