# Paper Notes

> Create complete, easy-to-understand Markdown literature notes from academic papers and, when the paper came from Zotero or has a known Zotero item, attach the generated note back to the corresponding Zotero item. Use when the user invokes paper_notes, paper-notes, $paper-notes, or asks Codex to read a paper, Zotero item, PDF, arXiv paper, journal/conference article, or newly added library item and generate a structured literature note with metadata, publication venue, method explanation, key figure/table analysis, experiments, limitations, plain-language summaries, reusable research takeaways, and Zotero attachment write-back.

- Skill: `jialing25y/paper-notes` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jialing25y/paper-notes`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jialing25y/paper-notes/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Jialing25y (https://skillmd.com/u/jialing25y)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/jialing25y/paper-notes

---


# Paper Notes

## Purpose

Produce one high-quality Markdown literature note for one academic paper. Prioritize correctness, clarity, and learning value over speed. The note should help a reader who may be new to the field understand the paper's problem, method, evidence, figures, and significance. When a matching Zotero item is known, attach the final `.md` note to that Zotero item after generation.

## Default Output

Create exactly one `.md` file unless the user requests otherwise. Do not create workflow folders, matrices, templates, HTML exports, or Zotero-import helper files by default.

Use a clear filename derived from the paper title, for example:

```text
ClipGStream_文献笔记.md
FirstAuthorYear_ShortTitle_文献笔记.md
```

If a file already exists, update it in place when the user asks for improvements; otherwise create a new note in the current workspace. When the paper is associated with Zotero, also attach or update the same Markdown file as a Zotero attachment unless the user explicitly says not to.

## Workflow

### 1. Locate The Paper

Accept any of these inputs:

- A local PDF path.
- A Zotero item, collection, folder, key, or "latest added" instruction.
- An arXiv URL, DOI, title, or project page.
- A PDF already present in the workspace.

For Zotero:

- Prefer official/local APIs if available.
- If APIs are unavailable, read Zotero's local database only from a copied snapshot; do not write directly to `zotero.sqlite`.
- It is acceptable to inspect Zotero storage PDFs and `.zotero-ft-cache` files.
- Only modify Zotero itself when the user explicitly asks and a safe API/tool path is available.

### 2. Verify Metadata

Collect and record:

- Title.
- Authors.
- Year/date.
- Venue: conference, journal, workshop, preprint, thesis, or report.
- Version status, such as arXiv v1, accepted version, camera-ready, or project-page claim.
- DOI, arXiv ID, URL/project page.
- Zotero key or local PDF path when relevant.

If venue/publication status may have changed or is not explicit in the PDF, verify from current primary sources such as arXiv, project page, conference page, DOI/Crossref, publisher page, or official proceedings. Clearly distinguish:

- "Publication/venue"
- "Current PDF version read"
- "Unverified or inferred status"

### 3. Read The Paper

Use PDF tooling when available:

- Extract text with `pypdf`, `pdfplumber`, Zotero full-text cache, or `pdftotext`.
- Render pages containing key diagrams, tables, or qualitative figures when visual understanding matters.
- Cross-check text extraction against page images for diagrams, tables, and captions.

Read at least:

- Abstract and introduction.
- Related work/problem framing.
- Method section.
- Experiment setup and metrics.
- Main results tables.
- Ablation studies.
- Qualitative figures.
- Limitations and conclusion.

Do not rely only on the abstract unless the user explicitly asks for a quick summary.

### 4. Analyze Key Figures And Tables

Do not insert images unless the user asks. Instead, explain important figures/tables in words.

Include figure analysis when the paper uses figures to carry the core argument:

- What the figure is showing.
- Which parts are important.
- What conclusion the reader should draw.
- How the figure supports or weakens the paper's claim.

For experimental tables:

- Explain what the metrics mean at a high level.
- Compare against the strongest relevant baselines.
- Identify whether gains are large, small, consistent, or limited to a specific setting.
- Avoid overclaiming when differences are marginal.

### 5. Add Plain-Language Summaries

At natural logical stopping points, add short summaries titled or prefixed:

```text
通俗小结:
```

Use these after sections such as:

- Problem/background.
- Core idea.
- Method overview.
- Key module explanation.
- Experiment results.
- Ablation analysis.
- Final contribution.

Plain-language summaries should translate technical content into intuitive language without becoming childish or inaccurate.

### 6. Write The Note

Use this structure unless another structure is clearly better:

```markdown
# {Paper Short Title} 文献笔记

## 1. 文献信息
## 2. 一句话总结
## 3. 这篇论文要解决什么问题
## 4. 背景与相关工作脉络
## 5. 核心思想
## 6. 方法详解
## 7. 关键图表解读
## 8. 实验设置
## 9. 主要实验结果
## 10. 消融实验
## 11. 本文真正的新意
## 12. 优点
## 13. 局限性
## 14. 和用户研究主题的关系
## 15. 可延伸的研究问题
## 16. 适合引用的观点
## 17. 我的理解总结
## 18. 阅读结论
```

Adapt headings to the paper. For theory papers, replace experiment sections with theorem/proof/assumption analysis. For survey papers, emphasize taxonomy, coverage, and missing areas.

### 7. Attach The Note To Zotero

When the source paper is a Zotero item, or a Zotero item key/collection/latest-added instruction was used, add the generated `.md` note as an attachment under the corresponding Zotero parent item.

Preferred order:

1. Use a safe Zotero API/tool if available.
2. If the local Zotero API is unavailable, use Zotero's local database only after closing Zotero and making a backup.
3. If neither route is safe, leave the Markdown file in the workspace and clearly tell the user that Zotero attachment write-back was not completed.

Safety requirements for local database write-back:

- Never write to `zotero.sqlite` while Zotero is running or the database is locked.
- Before any direct database write, create a backup such as `zotero.sqlite.before-paper-note-attachment.bak`.
- Prefer updating an existing note attachment for the same generated filename if it already exists under the same parent item.
- If adding a new stored-file attachment, create a unique 8-character Zotero key, copy the `.md` file into `Zotero/storage/{key}/`, then insert the required `items`, `itemAttachments`, `itemData`, and sync queue metadata.
- Use `contentType` `text/plain`, `charset` `utf-8`, `linkMode` `1` for stored files, and a title matching the Markdown filename without extension.
- Verify after write-back by querying the parent item's attachments and comparing the attached file hash with the workspace note hash.
- Reopen Zotero when finished if it was closed.

Do not create duplicate Markdown attachments under the same item. If the user deleted an earlier attachment, re-check the current Zotero state before deciding whether to update or re-add.

## Quality Bar

The note must:

- Be complete enough to support future review without reopening the paper immediately.
- Explain jargon when it first appears.
- Include the paper's venue/publication status.
- Explain key figures/tables in text.
- Include plain-language summaries at appropriate points.
- Distinguish author claims from your own interpretation.
- Mention limitations and open questions.
- Attach the final `.md` note to the matching Zotero item when applicable and safe.
- Avoid fabricating results, venues, code availability, or claims.
- Preserve formulas only when they help understanding; otherwise explain them in words.

## Final Response

Return a concise completion message with:

- The path to the created or updated Markdown file.
- The Zotero attachment key/path if the note was attached.
- The most important additions or sections included.
- Any uncertainty, such as an unverified venue or missing PDF text extraction.

Tell the user if browser verification, PDF rendering, or Zotero attachment write-back was unavailable.