paper-reading-management
Manage academic paper reading workflows from local PDFs, URLs, web search, Zotero, Obsidian/Dataview, or optional Feishu/Lark publishing. Use when Codex is asked to find papers, read and summarize pap
SKILL.mdskills/paper-reading-management/SKILL.md
GitHubPaper Reading Management
Overview
Use this skill to turn a paper request into a reproducible reading packet: Zotero-first source resolution, mandatory independent paper reading, local note organization, a one-sentence summary for retrieval and Zotero Style 简记, manual figure/table placeholders without image extraction, optional Zotero tagging/import, and optional cloud publishing.
Default to one management workflow. Split work into a separate Zotero-focused skill only if the user mainly asks for long-running library curation, duplicate cleanup, collection restructuring, or tag taxonomy maintenance without reading papers.
Workflow
Resolve the paper source.
- Prefer Zotero when available. Search Zotero first for known papers and use Zotero as the primary library of record.
- If a Zotero item has a PDF attachment, read the attachment in place instead of copying it into the local note folder. Use
scripts/zotero_pdf_path.py <item-key> --firstto get the local PDF path. - If the paper is not in Zotero, use user-provided PDF/URL/DOI/arXiv/OpenReview/publisher page or web search to find the official source. Prefer arXiv, OpenReview, publisher, DOI, project, or author pages.
- When a reliable BibTeX/RIS/connector route exists, import the paper into Zotero before organizing notes. If import or PDF attachment is blocked, keep the official source URL in metadata and report the blocker.
- If working in a project with local paper-index instructions, follow that local index before web search.
- Use web search when the paper is not local or metadata needs verification; prefer official sources such as arXiv, OpenReview, publisher pages, project pages, or DOI landing pages.
- Do not use unauthorized PDF sources.
Capture metadata before reading.
- Record title, authors, date, venue/source, URL/DOI/arXiv id, local PDF path, Zotero item key, BibTeX key when available, and retrieval date. Use
datefor the paper's first public release date when available, preferably the arXiv v1 submission date for preprints. - Verify the latest formal publication/version online before finalizing
publication, folder name, and index label. Prefer OpenReview/conference/publisher records over arXiv when a paper has since been accepted. - Verify official project and GitHub/code links online. Leave
github_urlblank if no official repository is found; do not use unrelated repos. - Do not invent missing metadata. Mark unknown fields explicitly.
- Record title, authors, date, venue/source, URL/DOI/arXiv id, local PDF path, Zotero item key, BibTeX key when available, and retrieval date. Use
Read and summarize with a subagent.
- Always spawn a fresh subagent for paper reading tasks with no inherited conversation context; do not reuse the main conversation as the reading context.
- This is a hard gate. If a fresh isolated subagent is unavailable, do not create or update
note.md; report the blocker and stop before producing a reading note. - For batches, spawn one independent subagent per paper. A subagent must not read or summarize multiple papers unless the user explicitly asks for a cross-paper comparison.
- Pass only the paper source, verified metadata, and the exact reading prompt. Do not pass unrelated project chat history, previous notes, earlier summaries, or the main thread's conclusions.
- Explicitly instruct the subagent not to read existing
note.md,retrieval.md,metadata.json, prior generated reports, or any previous conversation context. The subagent should read the PDF/source itself. - After receiving the subagent's final result and integrating it into
note.md, close the subagent. - Use
references/reading-report-prompt.mdas the single source of truth for the reading report prompt. Do not paraphrase, translate, restructure, or duplicate this prompt in another reference file. - Use
references/blank-agent-prompt.mdonly as the mandatory subagent handoff scaffold. - Require claims to be grounded in the paper text. Separate paper claims from the reader's interpretation.
- The subagent reading report is the source of truth for
note.md. Do not prepend YAML frontmatter, metadata blocks, prompt text, tags, index entries, or extra sections tonote.md. - Preserve the reading report's section order and heading structure from
references/reading-report-prompt.md; the body may be Chinese because the prompt requests Chinese output. - Ensure
## 0. Concise SummaryincludesTopic,Problem,Method,Innovation,Significance, and exactly one**One-sentence summary**:line. The entire reading report must be written in Chinese. - Record the isolated reading provenance in
metadata.jsonwhen possible:reading_agent_isolated: true,reading_agent_fork_context: false, and the subagent id/name if available.
Organize files locally.
- Use
scripts/organize_paper.pyto create a stable folder withmetadata.json,note.md, and optionalretrieval.md. Do not create or populate afigures/directory. - Keep machine-readable fields only in
metadata.json. Do not duplicate them as Markdown frontmatter innote.mdorretrieval.md. - Put exactly four front-link fields before
## 0. Concise Summaryinnote.md, separated from the report by---:Title,Paper link,Web/project link, andGitHub link. - Put exactly the same four fields before
## Core Contentinretrieval.md:Title,Paper link,Web/project link, andGitHub link. - Build
## Core Contentby extractingTopic,Problem,Method,Innovation, andSignificancefrom section0. Concise Summaryof the generated report. Do not independently rewrite these fields unless extraction fails. - Extract the five concise-summary fields and the one-sentence summary into
metadata.json. Never add a missingOne-sentence summaryline tonote.md; the isolated reading report must supply it. - Put other useful bibliographic/management fields after
## Core Content, under a secondary metadata section. This can include authors, publication, date, identifiers, PDF path, Zotero key, BibTeX key, and note path. Do not put tags or index-entry prose inretrieval.md. - Do not copy PDFs by default. Record the Zotero PDF path or source URL in metadata. Copy a PDF only when the user asks or when
--copy-pdfis explicitly used. - Default local note root is
${PAPER_LIBRARY_ROOT:-$HOME/paper}. The user may override it withPAPER_LIBRARY_ROOTor--library-root. - Use a project-specific root only when the user explicitly specifies one or project instructions explicitly require one. For example, use a SpaceVLN folder only when the user asks to store the note under SpaceVLN or the project task says to do so.
- Mirror the primary Zotero collection path physically under the configured paper-library root.
- Keep one paper per folder using
<short-title>--<publication-year>/, e.g.vision-language-navigation--cvpr2018. - Maintain a single root
INDEX.mdtree directory. Keep it minimal: classification path plus paper short title/version linking tonote.md. - For classification fields, read
references/classification-taxonomy.md. Use layered tags:domain_tags,method_tags,project_tags, and a separate lightweightzotero_tagslist for tags that should be mirrored into Zotero.zotero_tagsmust contain only the two Zotero-facing hashtag labels described in the Zotero update step. - For Obsidian and Dataview conventions, read
references/obsidian-dataview.md.
- Use
Update Zotero.
- Reads/search/export are safe.
- For this skill, a user request to read and organize a paper implies permission to add the paper to Zotero when missing and to apply reading-management tags generated from the note, unless the user asks for dry-run/no-write behavior.
- When a paper has a verified formal publication newer than its imported arXiv/preprint record, prefer updating Zotero's bibliographic metadata to the formal record. For conference papers, use Zotero item type
conferencePaper, setconferenceNameto the compact venue label such asICLR 2026, setproceedingsTitleto the full venue name when known, and keep arXiv information in DOI/archive/extra fields when useful. - Keep Zotero tags lightweight and user-facing. Unless the user explicitly asks for a different tag taxonomy, replace all existing Zotero tags so each item has exactly two Zotero-facing hashtag tags:
- one kind tag:
#会议论文,#期刊论文,#预印本, or#网页资料; - one venue/source/version tag: for example
#NeurIPS 2025,#ICLR 2026,#arXiv 2026,#TMLR 2024, or a compact web/source label such as#Anthropic. Remove legacy and unrelated Zotero tags during confirmed sync. Do not mirror collection/project tags such as#Embodied Agent, and do not mirror detaileddomain_tags,method_tags,project_tags, or free-form topic/search tags into Zotero. Keep those detailed tags only in localmetadata.json.
- one kind tag:
- Zotero's local
/api/routes are read-only. For writes, prefer a Zotero MCP/write bridge or connector import. Change item type only through Zotero-supported write tools or an explicitly requested, backed-up local database migration. - For broad library cleanup, duplicate removal, collection restructuring, or destructive changes, show the planned item keys and changes first.
- Use the Zotero helper for search, export, import-bibtex/import-ris, children, fulltext, and file-url.
- Use
scripts/zotero_sync_note.pyto syncmetadata.one_sentence_summaryinto Zotero Style 简记, stored as aremark:line in ZoteroExtra. Preserve all existing non-remark:lines inExtra; do not write the overview intoabstractNote. The script is dry-run by default; pass--yesonly after confirming the target item. With--sync-tags, require exactly twometadata.zotero_tagsand replace all existing Zotero tags with them. - Use
scripts/zotero_tag_items.py --setto replace all tags, or its add/remove/replace modes for explicitly requested ad hoc edits.
Return a concise handoff.
- Include local folder path, paper source, Zotero item key if any, tags added/planned, and the
note.mdpath. - Mention any metadata gaps, missing PDF, paywall, failed import, or unverified claims.
- If the user asks to publish or mirror to Feishu/Lark, read
references/feishu-sync.mdand preferscripts/feishu_sync.pyfor search/create/update/write-back orchestration; use the appropriate Lark document skill for manual follow-up edits.
- Include local folder path, paper source, Zotero item key if any, tags added/planned, and the
Local Organization
Create reading packets with:
python3 <skill-dir>/scripts/organize_paper.py \
--library-root "${PAPER_LIBRARY_ROOT:-$HOME/paper}" \
--title "<paper title>" \
--date "<first-public-release-date>" \
--pdf "<zotero-or-local-paper.pdf>" \
--url "<source-url>" \
--zotero-key "<item-key>" \
--bibtex-key "<bibtex-key>" \
--publication "CVPR 2026" \
--paper-url "<official-paper-url>" \
--web-url "<project-page-if-any>" \
--github-url "<github-repo-if-any>" \
--collection-path "VLN/Classic" \
--short-title "Vision-and-Language Navigation" \
--tag "vln" --tag "spatial-memory" \
--domain-tag "embodied-ai" \
--method-tag "spatial-memory" \
--project-tag "SpaceVLN-related" \
--zotero-tag "#会议论文" \
--zotero-tag "#CVPR 2026" \
--topic "vision-language navigation" \
--index-summary "Use this paper when comparing zero-shot VLN methods with explicit spatial memory." \
--problem "continuous navigation with sparse spatial grounding" \
--method "structured VLM reasoning with spatial memory" \
--innovation "explicit spatial topology for zero-shot navigation" \
--significance "improves retrieval and comparison for SpaceVLN related work" \
--one-sentence-summary "本文聚焦视觉语言导航,针对连续环境中的稀疏空间 grounding 问题,提出带空间记忆的结构化 VLM 推理方法,创新在于显式空间拓扑建模,意义在于支持 SpaceVLN 相关工作检索和对比。" \
--summary "<summary.md>"
If the PDF is not local yet, omit --pdf and store the verified source URL in metadata. If the PDF is in Zotero, pass the Zotero attachment path as --pdf; it will be recorded but not copied. Use --copy-pdf only when a standalone archive copy is desired. Add --dry-run before making folders when planning a large batch.
Get a Zotero PDF path:
python3 <skill-dir>/scripts/zotero_pdf_path.py <zotero-item-key> --first
Figure/Table Placeholders
Never extract, render, crop, save, or embed paper figures/tables/screenshots in note.md. Immediately after the paragraph that discusses a significant original figure/table, keep one placeholder for the user to replace manually later.
Use exactly:
<!-- figure: Figure 2 -->
<!-- table: Table 1 -->
Omit minor figures/tables and do not add a separate screenshot appendix.
Mandatory Figure/Table and Isolation Audit
Before returning a paper-reading task as complete, run a local audit for every paper folder. Treat failures as blockers and fix them before final handoff.
Use the bundled audit helper when possible:
python3 <skill-dir>/scripts/audit_reading_packet.py \
--require-isolated \
"<paper-folder-1>" "<paper-folder-2>"
- Isolation:
- Confirm the reading report came from a fresh subagent with
fork_context=false. - Confirm one subagent handled exactly one paper.
- Confirm
note.mdwas integrated from that subagent report, not synthesized from previous notes or main-thread history.
- Confirm the reading report came from a fresh subagent with
- Note structure:
- Exactly one
**One-sentence summary**:line under## 0. Concise Summary. - Required headings exist in the exact order from
references/reading-output-template.md.
- Exactly one
- Figure/table completeness:
- Every Figure/Table that the note explicitly discusses must have a matching nearby
<!-- figure: Figure X -->or<!-- table: Table X -->marker. - Keep the markers in
note.mdfor the user's later manual image insertion. note.mdmust not contain Markdown image embeds or local screenshots.- Do not mention a Figure/Table in prose and omit its marker. If it is not important enough to mark, do not highlight it.
- Every Figure/Table that the note explicitly discusses must have a matching nearby
- Batch integrity:
- Run the audit across all target folders, not just one example.
- Update
INDEX.mdonly after the per-paper audits pass.
Zotero Tag Editing
Dry-run first. Replace all Zotero tags with exactly the two Zotero-facing hashtag tags; keep detailed technical tags in local metadata fields:
python3 <skill-dir>/scripts/zotero_tag_items.py \
--item-key UKRJFRVC \
--set "#会议论文" \
--set "#CVPR 2026" \
--dry-run
Write only after confirmation:
python3 <skill-dir>/scripts/zotero_tag_items.py \
--item-key UKRJFRVC \
--set "#会议论文" \
--set "#CVPR 2026" \
--yes
For normal reading packets, use --set so no legacy tags remain. For explicitly requested ad hoc edits, use --replace "old tag=new tag" or --remove "<tag>". Avoid library-wide cleanup unless the affected item keys have been shown.
Sync the one-sentence summary to Zotero Style 简记 (remark: in Extra):
python3 <skill-dir>/scripts/zotero_sync_note.py \
--paper-folder "<paper-folder>" \
--sync-tags \
--yes
Mirror the reading packet to Feishu/Lark after confirming the target:
python3 <skill-dir>/scripts/feishu_sync.py \
--paper-folder "<paper-folder>" \
--yes
Run a non-mutating readiness check:
python3 <skill-dir>/scripts/diagnose.py
Output Shape
Use references/reading-report-prompt.md for the exact subagent reading prompt, references/reading-output-template.md for the local note.md shape, retrieval.md for per-paper quick search cards, and root INDEX.md for the tree directory. note.md is the reading report with exactly one one-sentence summary supplied by the subagent; retrieval.md is a concise search card; metadata.json is the only machine-readable metadata store. For paper batches, keep final chat output compact and point to created files instead of pasting every summary.
Safety Rules
- Do not invent results, citations, datasets, or ablation outcomes.
- Keep metadata provenance clear: local PDF, Zotero, official web source, or user-provided text.
- Never expose API keys or secrets found in Zotero preferences or exported files.
- Do not mutate Zotero without explicit write confirmation for the concrete items and changes.
- If a web source and Zotero/local metadata conflict, report the conflict and keep both values in metadata until resolved.