Skip to content
Skills Library
Science & research · Learning & explanation

annotate-paper

/annotate-paper

Read the open paper and write study annotations into its PDF with zotero-cli - a context box on the title, a four-part summary on the abstract, role-coded abstract highlights, one box per figure panel with a teaching comment, colour-coded body highlights, and a reading note. Use when asked to "annotate", "read and annotate", or "help me understand" a paper.

Repository
zotero-mcp ↗
Licence
MIT
Last repository change
16.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 16.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Read the open paper and write study annotations into its PDF with zotero-cli - a context box on the title, a four-part summary on the abstract, role-coded abstract highlights, one box per figure panel with a teaching comment, colour-coded body highlights, and a reading note. Use when asked to "annotate", "read and annotate", or "help me understand" a paper.

Triggers from the description

annotateread and annotatehelp me understand
Original author description

Read the open paper and write study annotations into its PDF with zotero-cli - a context box on the title, a four-part summary on the abstract, role-coded abstract highlights, one box per figure panel with a teaching comment, colour-coded body highlights, and a reading note. Use when asked to "annotate", "read and annotate", or "help me understand" a paper.

How it works

  1. Colour scheme (change it here)
  2. 1. Find the paper and its PDF
  3. 2. Read the whole paper, then look at every figure
  4. 3. What to write
  5. 4. Plan, check, then write in one batch
  6. Gotchas
Original SKILL.md headings · 115 lines, 947 words
SKILL.md preview
---
name: annotate-paper
description: Read the open paper and write study annotations into its PDF with zotero-cli - a context box on the title, a four-part summary on the abstract, role-coded abstract highlights, one box per figure panel with a teaching comment, colour-coded body highlights, and a reading note. Use when asked to "annotate", "read and annotate", or "help me understand" a paper.
---

# Annotate a paper for understanding

The goal is a PDF someone can study from cold: the background, the argument and every figure explained in place.

## Colour scheme (change it here)

Use exactly these colours so every paper reads the same way. Edit the table to make the scheme your own; the rest
of the skill refers to the roles, not the colours.

| Annotation | Where | Colour | Content |
|---|---|---|---|
| Context box | around the title and authors, page 1 | orange | What a newcomer needs first: the field, key terms defined plainly, the problem's history, why this approach. Start with `CONTEXT`. |
| Four-part summary | around the abstract | magenta | `THE WHOLE PAPER IN FOUR PARTS.` then `// PROBLEM:`, `// METHOD:` (with the real numbers), `// RESULTS:` (numbered), `// TAKEAWAY:` and the limits. |
| Abstract highlights | sentences in the abstract | by role | Prefix each comment with its role: `PROBLEM.` / `GOAL.` / `CONCLUSION.` (yellow), `METHOD.` (blue), `DISCOVERY.` (green). |
| Figure boxes | one per sub-panel | purple | See "Figure boxes" below. |
| Body highlights | key sentences throughout | yellow / blue / green / red | yellow = claim or big idea; blue = method, data or design choice; green = finding or evidence; red = limitation, caveat or critique. |

This skill sits on top of the `zotero-cli` skill. Run `zotero-cli config` once first; writing annotations needs local
write access.

## 1. Find the paper and its PDF

Use the paper that is open in the reader, or the one the user names:

```bash
zotero-cli --json search "title words" --limit 5
zotero-cli --json get children ITEM_KEY          # the PDF attachment's key; supplementary PDFs are attachments too
```

Annotate the main PDF, not the supplement, unless asked.

## 2. Read the whole paper, then look at every figure

```bash
zotero-cli read ITEM_KEY --start-page 1 --end-page 99
```

Read all of it, including Methods and figure captions. Extracted text is unreliable for figures, tables and math, so
render every figure page and look at it yourself:

```bash
zotero-cli read ITEM_KEY --start-page 4 --end-page 4 --format image --out pages/
zotero-cli read ITEM_KEY --start-page 4 --format image --rect 0.2,0.3,0.35,0.2 --out zoom/   # zoom into one panel
```

Zoom into any panel before describing it: read the axis values, thresholds, which curve is which colour, and every
arrow and repression bar in a network diagram. Do not describe what you have not seen.

`rect` is `x,y,width,height`, normalised 0 to 1 to the page as displayed, from the top-left corner.

## 3. What to write

### Figure boxes: one per sub-panel, never one per figure

- Every lettered panel (1A, 1B, ...) gets its own box.
- Unlettered figures are split into their natural parts: a network diagram into its regions and legend, a grid of
  small plots into one box per plot, a text box into one box per paragraph.
- Do not bury the figure. For large regions of a dense diagram, box just the region's label and put the explanation in
  the comment.
- Tables: usually one box over the table, with the column guide and row notes in its comment.
- Comment format: start with `FIG 2B |` (or `TABLE 1 |`), then what is plotted (axes, units, colours, what one point
  is); what to notice, with the actual numbers; why the panel matters and which panel it pairs with; for diagrams,
  every edge; caveats such as weak statistics, small n, or text that disagrees with the figure.
- Use capitals sparingly, for the one phrase that is the point (`THE KEY CONTROL`).

### Body highlights

About 25 to 50 per paper: the central claim, the key design choices, each main finding, every limitation the authors
admit, and places where the text overreaches. Comments explain rather than paraphrase: why it matters, what it
connects to, what to question.

### Reading note

Add one note to the item: a first line `Author Year, Journal vol:pages. Title.`, then `QUESTION`, `APPROACH`,
`MAIN FINDINGS` (bullets), `DISCUSSION POINTS` (numbered) and an `ANNOTATION KEY` paragraph stating the colour scheme.

```bash
zotero-cli notes create --item-key ITEM_KEY --text - < note.md
```

### Writing style

Plain words, defined terms, no filler, no superlatives. Give numbers as the paper states them. Mention follow-up work
only when you are sure of the reference.

## 4. Plan, check, then write in one batch

Write the plan as a JSON Lines file, one annotation per line:

```json
{"page": 1, "rect": "0.10,0.07,0.80,0.145", "comment": "CONTEXT ...", "color": "orange"}
{"page": 1, "text": "exact words from the page", "comment": "PROBLEM. ...", "color": "yellow"}
```

1. Dry run, and read every `matched_text`. Fix misses and overshoots (shorten a phrase until it matches cleanly):
   ```bash
   zotero-cli --json annotations batch --attachment-key ATTACH_KEY --file plan.jsonl --dry-run
   ```
2. Check every box against the page images: each one covers exactly its panel, label included, and does not swallow
   its neighbour. On a rotated (landscape) page, open it in Zotero after writing and look.
3. Write for real (the same command without `--dry-run`) and confirm `failed: 0`. Then count what was written:
   ```bash
   zotero-cli --json annotations list --item-key ITEM_KEY --limit 500
   ```

## Gotchas

- Do not re-run a batch that succeeded: it creates duplicates. To redo, delete the old annotations permanently first
  (trashed annotations still show in Zotero's reader).
- `annotations list` fields are `type`, `color_category`, `page`, `text` and `comment`.
- Highlight text is searched on the given page and two either side, and tolerates hyphenation and curly quotes; copy
  it from `read`.
- Page numbers in a plan are PDF page indices starting at 1, not the printed journal page numbers.

Versions

The database has no other skills named annotate-paper.

Database snapshot: 13.11.2026 · package version ba6d51336557 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 98sounding
    收到一篇研究论文后,直接按完整 sounding 流程拆成结构化笔记,并为用户主导的批量观潮回顾准备可核对的定位素材。按论文结构(不看发表处)在 algorithm、science、review、other 四种骨架里选一种;不做扫读、摘要式降级或“是否值得精读”的前置判断。单篇默认不由 agent 判定 wave;回顾时由 agent 对齐多篇证据,用户确认后再回写。笔记必须发布到云端(Notion 或飞书二选一,由配置决定),按稳定 citekey 幂等并回写 Zotero;发布后端未就绪时先完成配置与读写探针,不能以本地稿结束。Use when…
  • 100zotero-paper-note
    Read a paper from Zotero, generate a structured reading note, attach it back to the Zotero item, and append one structured JSON line to literature.jsonl for later batch analysis. Use when the user provides a paper title/authors/DOI/Zotero item and asks to "read this paper",…
  • 100traceable-paper-review
    Use when asked to read or review a paper, create evidence-linked paper notes, or highlight and annotate a PDF or Markdown paper. 适用于精读论文、整理论文笔记、标注 PDF 或 Markdown、追溯原文证据。
  • 95zotero-paper-reader
    Deep-read or quick-read a given paper, arXiv link or existing Zotero item, reading the local PDF (including Attanger attachments), and save the research note as a Zotero child note. Use for "read this", "deep read", "take a quick look"; hand save-only requests to zotero-paper-save.
  • 90zotero-paper-deep-read
    在 Zotero 中定位指定或当前打开的论文,阅读正文与补充材料,按四部分十项结构进行固态电池文献深度解析,并新建子笔记保存结果。适用于“解读这篇文献并写入 Zotero 笔记”等请求。
  • 100paper-reader
    Read academic papers from a bare arXiv abs/pdf/html URL, a PDF, a paper title, or Zotero. Use for "read this paper", "analyze this paper", "读一下 XXX", "读一下这篇", "帮我读", "看一下这篇论文", "论文笔记", quick summaries, critiques, and Zotero collection reading. A standalone arXiv link or ordinary…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.