# Read Paper > 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"). - Skill: `x1aox1a/read-paper` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add x1aox1a/read-paper` - Raw SKILL.md: https://api.skillmd.com/api/skills/x1aox1a/read-paper/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: x1aox1a (https://skillmd.com/u/x1aox1a) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/x1aox1a/read-paper --- # 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: ``` ``` > **First-use setup:** If the path above says `` or doesn't exist, ask the user: "What's the path to your ZoFiles paper library?" Then: > > 1. Update the path above > 2. Run `scan-library.sh` to populate the directory snapshot (see [Updating the Directory Snapshot](#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 ``` ``` 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 bash .claude/skills/read-paper/scripts/scan-library.sh "" ``` Then replace the content between `` and `` markers in this file with the new output (wrapped in a ```code block), and update the`` 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: ```yaml --- 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. |