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:

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

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:

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.

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:

{"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):

   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:

   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.