Zotero Paper Coach

---
name: zotero-paper-coach
description: Annotate academic papers and Zotero-managed PDF attachments with structured, high-value highlights and mentor-style notes. Use when a user wants paper pre-highlighting, reading guidance, layered annotation styles, note density control, color-coded importance, Zotero/PDF write-back, or a reusable workflow for studying, literature review, exam prep, or paper comprehension. Also triggers on 论文标注、读论文、画重点、高亮、边注、精读、文献综述、Zotero.
---

# Zotero Paper Coach

Provide paper annotation as a reading-coach workflow, not as raw highlighting.

All file paths in this skill (`references/…`, `scripts/…`, `DESIGN.md`) are relative to the directory that contains this `SKILL.md`. Resolve them against that directory before reading a file or running a script; the skill works the same in any agent that loads Agent Skills (for example Claude Code or Codex).

## Quick start

When invoked, do this in order:

1. Identify the target document and whether the write target is:
   - a Zotero local PDF attachment, or
   - a standalone PDF.
2. Ask for the minimum annotation configuration if the user did not specify it.
3. Produce an internal annotation plan before writing anything.
4. Back up the PDF.
5. Remove only prior annotations created by this skill unless the user explicitly asks to wipe all annotations.
6. Write highlights and notes back to the PDF.
7. Optionally generate a sidecar reading guide markdown file.

## Minimum configuration to collect

Ask only for missing items. Default aggressively when the user is vague.

Collect these knobs:

- **goal**: `beginner-learning` | `quick-read` | `exam-prep` | `literature-review` | `replication` | `citation-harvest`
- **style**: `mentor` | `top-student` | `critical-researcher` | `executive-brief`
- **density**: `light` | `medium` | `heavy` | `teaching`
- **note depth**: `brief` | `explain` | `teach`
- **color scheme**: `standard` | `minimal` | `research`
- **rewrite mode**: `clean-coach-only` | `append` | `wipe-all`

Recommended defaults:

- goal: `beginner-learning`
- style: `mentor`
- density: `medium`
- note depth: `explain`
- color scheme: `standard`
- rewrite mode: `clean-coach-only`

## Annotation semantics

Use stable color meaning. Do not improvise colors per run.

Read `references/annotation-styles.md` when deciding style, density, and color policy.
Read `references/user-modes.md` when mapping the user's actual job to annotation behavior.

### Standard color scheme

- **Yellow**: core claim, must-read result, takeaway sentence
- **Blue**: evidence, method, metric, experimental setup
- **Pink**: limitation, caveat, failure mode, uncertainty
- **Green**: definition, orientation sentence, beginner-friendly framing
- **Orange**: quotable sentence, reusable summary, literature-review worthy line

## Workflow

### Step 1: Locate the source

For Zotero use cases:

- Prefer local attachment write-back to the Zotero-managed PDF file.
- Confirm the exact paper before editing if multiple candidates exist.
- If direct Zotero UI automation is unavailable, edit the underlying PDF attachment.
- When a generated or modified PDF needs to be inspected inside Zotero desktop, read `references/zotero-import-workflow.md` and prefer the helper script instead of `open -a Zotero file.pdf`.

For standalone PDFs:

- Work directly on the file path the user provided.

### Step 2: Inspect the document

Extract enough text to identify:

- title and abstract
- research question / gap
- contribution or key points
- methods and dataset choices
- central results
- limitations / caveats
- conclusion

When the PDF is scanned or text extraction is poor, say so and switch to a reduced-confidence workflow.
Read `references/backend-modes.md` and `references/failure-and-fallbacks.md` when choosing whether to write back or downgrade.

### Step 3: Build an annotation plan

Do not highlight as you read blindly.

Create an internal plan with:

- target pages
- target sentences or paragraph anchors
- highlight color
- note label
- note content
- rationale for inclusion
- item confidence
- whether the item should be promoted into the reading guide

Read `references/annotation-plan-schema.md` for the recommended plan shape.

The plan should optimize for learning value, not raw coverage.

### Step 4: Map the plan to the user goal

#### beginner-learning
Prioritize:
- research question
- why the paper matters
- main findings
- limitations
- plain-language explanations
- suggested reading order

#### quick-read
Prioritize:
- abstract core lines
- contribution list
- 3 to 8 strongest result sentences
- main caveat
- conclusion

#### exam-prep
Prioritize:
- definitions
- framework and variables
- key findings
- compare/contrast points
- memorable sentences suitable for recall

#### literature-review
Prioritize:
- gap statement
- novelty claim
- strongest evidence sentences
- explicit limitations
- quotable synthesis lines
- relation to prior work

#### replication
Prioritize:
- data sources
- model/config choices
- metrics
- evaluation protocol
- implementation caveats
- anything likely to cause reproduction errors

#### citation-harvest
Prioritize:
- precise claims
- scoped findings
- definitions worth quoting
- limitation statements that prevent overclaiming

### Step 5: Write mentor-style notes

Notes must add value. Avoid empty comments like “important”.

Use short labels like:

- `[先看]`
- `[主张]`
- `[证据]`
- `[限制]`
- `[人话]`
- `[复述]`
- `[方法]`
- `[为什么重要]`

Write notes in one of these patterns:

- **segment function**: explain what role the passage plays in the paper
- **plain-language translation**: rewrite dense academic prose into simple language
- **reading instruction**: tell the user whether to skim, study, compare, or memorize
- **critical warning**: point out a limitation, assumption, or overclaim risk
- **reuse hint**: say whether the line is good for review writing or oral explanation

## Density policy

Read `references/density-profiles.md` when choosing how much to mark. Compute density dynamically from body pages, body words, and paragraph density rather than relying on a fixed total count.

Rules:

- `light`: mark only backbone sentences; minimal notes
- `medium`: mark backbone + key evidence + 1-2 limitations per section
- `heavy`: include method anchors, evidence chain, caveats, and reuse lines
- `teaching`: include reading prompts, plain-language notes, and section-level guidance

Avoid the “yellow wallpaper” failure mode. If many adjacent sentences are important, prefer one anchor highlight plus a note explaining the paragraph’s role.

## Output options

Primary output is the annotated PDF.

Optional sidecar outputs:

- `paper.reading-guide.md`
- `paper.annotation-plan.md`
- `paper.annotation-plan.json`

Treat the reading guide as a first-class teaching artifact, not a debug byproduct.

If the user asks for teaching support, generate a reading guide using `references/reading-goals.md`.

## Dependency policy

This skill may rely on local PDF tooling.

Preferred stack:

- Python 3
- `pymupdf` for annotation creation, update, and deletion

Optional helpers when needed:

- OCR/text extraction tooling for scanned PDFs
- SQLite inspection for local Zotero attachment lookup

Before first write on a machine, mention missing required dependencies and ask before installing them. Install with the same interpreter that runs the scripts: `<python> -m pip install pymupdf`; check with `<python> -c "import fitz"`.
Do not claim Zotero-native support unless it is actually implemented.

## Running the scripts

- `<skill-dir>` is the directory that contains this `SKILL.md`.
- `<python>` is `python3` on macOS and Linux, and `python` (or `py -3`) on Windows, where `python3` is often a Microsoft Store stub that fails.
- Quote paths that contain spaces.

Steps for the default rewrite mode (`clean-coach-only`):

1. Extract page text: `<python> <skill-dir>/scripts/extract_pdf_outline.py paper.pdf -o outline.json`. Use `-o` instead of shell redirection; Windows PowerShell 5.1 re-encodes redirected output and corrupts non-ASCII text.
2. Remove this skill's earlier annotations, backing up first: `<python> <skill-dir>/scripts/remove_coach_annots.py paper.pdf --backup`. This also removes annotations written by versions before 2026-10, whose author name starts with `OpenClaw`.
3. Write highlights and notes: `<python> <skill-dir>/scripts/annotate_pdf.py paper.pdf highlights.json --backup`

Other rewrite modes: `append` skips step 2. `wipe-all` runs step 2 with `--all` instead, which deletes every annotation in the file including the user's own; run it only after the user confirms in this conversation.

Backups: `--backup` copies the original to `paper.pdf.bak-paper-coach` only if that file does not exist yet, so the backup always holds the state before the first run of this skill.

`annotate_pdf.py` takes a flat JSON list, not the plan object from `references/annotation-plan-schema.md`. Convert each plan item:

| Plan item field | Script input field |
|---|---|
| `page` | `page` |
| `anchor_text` | `phrase` |
| `color` | `color` |
| `note_label` + space + `note_content` | `note` |
| (one occurrence) | `limit`: 1 |

```json
[
  {"page": 1, "phrase": "exact sentence copied from the extracted text", "color": "yellow", "note": "[主张] 这是全文要你接受的核心判断。", "limit": 1}
]
```

- Copy `phrase` from the extracted text of that page. The script normalizes whitespace, so wrapped lines still match. It also compares ligatures as plain letters (a typeset `fi` matches `fi`) and treats a hyphen as optional, so a phrase may keep its natural spelling `prompt-based` even when the PDF breaks the line after `prompt-`, and `gener- alization` still matches `generalization`.
- Phrases that still do not match are reported on stderr as `[warn] no match …` and skipped. Check stderr and retry those items with a shorter phrase from the same sentence.
- The script prints the number of annotation objects written: one highlight plus one note for each item that has a note.
- Every annotation is stamped with the author name `Zotero Paper Coach`; that author name is what `remove_coach_annots.py` matches.
- If the PDF is open in a reader that locks it (common on Windows), the scripts stop with a message asking the user to close the file; retry after they do.

## Safety and write discipline

Always:

- create a backup before mutation
- preserve user annotations unless explicitly told otherwise
- support dry-run planning when asked
- say when extraction confidence is low
- avoid claiming Zotero-native annotation support if only PDF attachment write-back is available

## Bundled resources

Use these references as needed:

- `DESIGN.md`
- `references/annotation-styles.md`
- `references/density-profiles.md`
- `references/reading-goals.md`
- `references/user-modes.md`
- `references/annotation-plan-schema.md`
- `references/backend-modes.md`
- `references/failure-and-fallbacks.md`
- `references/zotero-import-workflow.md`

Use scripts from:

- `scripts/annotate_pdf.py`
- `scripts/remove_coach_annots.py`
- `scripts/extract_pdf_outline.py`
- `scripts/import_pdf_to_zotero.py`