agentleFS
Agents4Academia-AIAgents4Academia-AI/UReKA/.claude/skills/zotero/SKILL.md

zotero

Skill9 starsChanged 5 months agoMITView on GitHub

Ingest a Zotero PDF (with annotations) into a clean source file + a consolidated annotation note

5 other projects use a version of this.

Adopted by

Most recently taken up by

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. 0 are common, 6 are distinctive, and 20 are very specific to this project.

  • 0

    Common

    Most of the 4 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 20

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If $ARGUMENTS is empty, use AskUserQuestion to ask:

    line 16
  2. Distinctive:

    Do not proceed until the user answers.

    line 19
  3. Distinctive:

    If no match: stop and report.

    line 74
  4. Very specific:

    If item_key is known: call zotero_get_item_children(item_key) to get the PDF attachment.

    line 87
  5. Very specific:

    Use the filename field from the children response.

    line 103
  6. Very specific:

    Read .mcp.json — check ZOTERO_BASE_ATTACHMENT_PATH in the zotero env block.

    line 111
  7. Distinctive:

    If present, use immediately.

    line 112
  8. Very specific:

    If absent — use AskUserQuestion:

    line 113
  9. Distinctive:

    Do not call any further tools until the user answers.

    line 116
  10. Very specific:

    Do not call extract_ink_annotations on abs_path before zotero_path is known — all ink extraction happens after both paths are resolved.

    line 151
  11. Very specific:

    When item_key is known, call:

    line 154
  12. Very specific:

    each path that is accessible on disk: If zotero_path == abs_path, run once only:

    line 163
  13. Very specific:

    Run extract_pdf_text on every PDF path that is accessible on disk.

    line 175
  14. Distinctive:

    Never combine multiple entries into one record.

    line 252
  15. Very specific:

    If label non-empty: append — label: "label" inside the brackets.

    line 257
  16. Very specific:

    Use bbox/page_width/page_height only for margin vs inline and coarse vertical zone — never report raw numbers.

    line 261
  17. Very specific:

    If annotationComment non-empty: [Highlight: "annotationText" — Note: "annotationComment"]

    line 267
  18. Very specific:

    Sources differ: write each version under its own ### <source_path> subheading, verbatim.

    line 293
  19. Very specific:

    If the file already exists, use AskUserQuestion:

    line 296
  20. Distinctive:

    Do not write or call any further tools until the user answers.

    line 299
  21. Very specific:

    Create notes/zotero_<paper_slug>/ if it doesn't exist:

    line 307
  22. Very specific:

    Read .claude/Templates/note.md for the frontmatter shape:

    line 327
  23. Very specific:

    If annotations.md already exists, use AskUserQuestion:

    line 337
  24. Very specific:

    Delete the temporary files: after annotations.md is written:

    line 342
  25. Very specific:

    Run /retrieve <topic> to find related sources and existing pages.

    line 364
  26. Very specific:

    Run /collate <topic> to synthesise a paper or concept page from this note together with other sources on the same topic.

    line 365

“Common” is measured: kept by at least 6 in 10 of the 4 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Do not read existing files in notes/ or sources/ to infer style. Follow only the instructions in this skill. Existing files may use a different format.

Ingest a Zotero-annotated PDF given by $ARGUMENTS and write two kinds of output:

  • sources/zotero_<slug>.md — objective paper text, clean and impersonal (type: zotero_source)
  • notes/zotero_<paper_slug>/annotations.md — all annotations consolidated in reading order, each with a location description and verbatim content; ink crops alongside (type: zotero_annotation)

If $ARGUMENTS is empty, use AskUserQuestion to ask:

  • Question: "What PDF or paper do you want to ingest?"
  • Options: "A file path (e.g. /path/to/react.pdf)", "A search query (e.g. ReAct reasoning acting)" Do not proceed until the user answers.

Root

  • Sources: sources/. Template: .claude/Templates/source.md.
  • Notes: notes/zotero_<paper_slug>/. Template: .claude/Templates/note.md.
  • Ink crops: saved directly into notes/zotero_<paper_slug>/ by extract_ink_annotations.

Step 1 — Route input and resolve all paths

This step produces three variables that must ALL be settled before Step 2 begins: abs_path, item_key, and zotero_path. Execute the phases below in strict order. Do not call any Step 2 tools until Phase 1-C is complete.


Phase 1-A — Establish abs_path

Determine whether $ARGUMENTS is a path or a search query.

It is a path if any of these are true:

  • ends with .pdf
  • starts with /, ./, ..\, a Windows drive letter (C:\), or ~
  • contains / or \

If PATH: expand to absolute path:

python3 -c "import os,sys; print(os.path.abspath('$ARGUMENTS'))"

→ abs_path. Check whether it exists on disk.

If QUERY: abs_path is absent. Proceed to Phase 1-B.


Phase 1-B — Find item_key

If PATH and on disk: extract the title from the first page, then search Zotero using both the basename (without extension) and the extracted title:

sh .claude/src/pyrun --need fitz -c "
import fitz, sys
doc = fitz.open(sys.argv[1])
text = doc[0].get_text()[:500]
doc.close()
sys.stdout.buffer.write(text.encode('utf-8'))
sys.stdout.buffer.write(b'\n')
" "<abs_path>"

zotero_search_items(query="<basename>") and zotero_search_items(query="<pdf_title>"). Pick the best candidate → item_key. If no match: item_key is absent.

If PATH and not on disk: zotero_search_items(query="<basename>") → item_key. If no match: stop and report.

If QUERY: zotero_search_items(query="$ARGUMENTS") → item_key. If no match: stop and report.

Do not proceed to Phase 1-C until item_key is settled (found or confirmed absent).


Phase 1-C — Resolve zotero_path

If item_key is absent: zotero_path is absent. Go to Phase 1-D.

If item_key is known: call zotero_get_item_children(item_key) to get the PDF attachment. Then call zotero_get_attachment_path(attachment_key).

Three outcomes — handle each, never skip:

A — Path returned and exists on disk: zotero_path = that path. Done.

B — Path returned but does not exist on disk (e.g. attachments: prefix): Strip the placeholder prefix. Get zotero_base_dir (see below), then:

python3 -c "import os,sys; print(os.path.abspath(os.path.join(sys.argv[1], sys.argv[2])))" "<zotero_base_dir>" "<stripped_path>"

→ zotero_path.

C — No path returned at all: Use the filename field from the children response. Get zotero_base_dir (see below), then:

python3 -c "import os,sys; print(os.path.abspath(os.path.join(sys.argv[1], sys.argv[2])))" "<zotero_base_dir>" "<filename>"

→ zotero_path.

Getting zotero_base_dir (cases B and C):

  1. Read .mcp.json — check ZOTERO_BASE_ATTACHMENT_PATH in the zotero env block. If present, use immediately.
  2. If absent — use AskUserQuestion:
    • Question: "Zotero could not resolve the local path for <filename>. What is your Zotero linked-file base directory?"
    • Options: one example per platform + "Other" Do not call any further tools until the user answers.
  3. Persist to .mcp.json: "env": { "ZOTERO_LOCAL": "true", "ZOTERO_BASE_ATTACHMENT_PATH": "<zotero_base_dir>" } Skip if already set to the same value.

Do not proceed to Phase 1-D until zotero_path is settled (resolved or confirmed absent).


Phase 1-D — Compare paths and decide ingestion mode

With abs_path and zotero_path both settled, determine what to ingest:

abs_pathitem_keyzotero_path on disk?Mode
PresentPresentSame as abs_pathSingle file — use Zotero metadata + annotations
PresentPresentDifferent from abs_pathTwo distinct files — merge both
PresentAbsent—Local file only; no Zotero entry
AbsentPresentYesZotero file only
AbsentPresentNoZotero read-only (no ink extraction)

Step 1 is now complete. Proceed to Step 2.


Step 2 — Gather metadata and annotations (when Zotero entry exists)

Do not begin this step until Step 1 is fully complete — all of the following must be settled before any tool call here:

  • abs_path — expanded absolute input path (or absent if no local file)
  • item_key — Zotero entry key (or confirmed absent)
  • zotero_path — resolved local path of the Zotero attachment (or confirmed absent; the "Resolving a Zotero attachment path" procedure must have run to completion, including any user prompt for the base directory)

Do not call extract_ink_annotations on abs_path before zotero_path is known — all ink extraction happens after both paths are resolved.

When item_key is known, call:

  • zotero_get_item_metadata(item_key) → title, authors, year, abstract
  • zotero_get_annotations(item_key) → highlights + typed notes + area annotations

Derive the paper slug from the title now (snake_case, e.g. attention_is_all_you_need) — you need it for the note folder path and for extract_ink_annotations.

With both abs_path and zotero_path now known, run extract_ink_annotations on each path that is accessible on disk. If zotero_path == abs_path, run once only:

extract_ink_annotations("<path>", output_dir="notes/zotero_<paper_slug>")

Crops are saved as notes/zotero_<paper_slug>/crop_<stem>_p<N>_c<M>.png.


Step 3 — Read body text from all sources

Run extract_pdf_text on every PDF path that is accessible on disk. Never use zotero_read_pdf_pages for body text.

ConditionAction
zotero_path on diskextract_pdf_text("<zotero_path>")
abs_path on disk AND distinct from zotero_pathextract_pdf_text("<abs_path>")
No item_key, abs_path on diskextract_pdf_text("<abs_path>") only

Label each result by its source path. Carry all labelled texts forward to Step 5a.


Step 4 — Describe annotations by location

For every annotation, produce a record. Each record has three fields:

  1. topic — a 3–5 word snake_case slug.
  2. concepts — concepts touched (short list).
  3. description — two parts, written as plain prose:

    Part 1 — Location. Describe WHERE the annotation is using content landmarks, not coordinates or percentages. Use natural language:

    • Page number and PDF source (if multiple)
    • Margin position: "left margin", "right margin", or "inline with text"
    • Vertical position: "top of page", "upper section", "mid-page", "lower section", "bottom of page" — use these terms only; never use percentages or pixel values
    • Content anchor: the nearest section heading, figure number, formula, or key phrase (e.g. "alongside §3.2.2", "next to Figure 2", "above the attention formula")

    Part 2 — What was marked. Describe exactly what the annotation consists of:

    • For underlines: which specific words or phrases are underlined
    • For circles/boxes: which specific element is enclosed (a word, a diagram block, a formula, a figure label)
    • For arrows: what the arrow points from and to
    • For handwriting: the transcribed text verbatim
    • For whole-page crops: enumerate each distinct mark visible — do not collapse multiple marks into "various annotations"; describe each one separately

    End with the verbatim content in [brackets].

    Examples:

    "Page 4, right margin, mid-page, alongside §3.2.2 Multi-Head Attention. A handwritten question in the margin next to the sentence describing learned linear projections of queries, keys, and values. [Handwritten: "learned linear projection?"]"

    "Page 3, inline, lower section, alongside §3.1 Decoder. An ink underline under the phrase describing causal masking. [Handwritten: ink underline under "prevent positions from attending to subsequent positions"]"

Ink annotations (from extract_ink_annotations):

For every ink crop (whether whole_page: false or true), the mandatory first action is to Read the image and produce a raw mark inventory in your internal reasoning — before writing any description. The inventory is a numbered list of every ink mark visible in the image, top-to-bottom, left-to-right. Do not skip any mark. This inventory is a working step only — never write it to any output file.

Inventory format (internal only):

1. [type] on/under/around "[exact text or element]" — [location on page]
2. [type] on/under/around "[exact text or element]" — [location on page]
...

Types: underline / circle / box / bracket / arc or curve / arrow / freehand stroke / handwriting.

Do not use surrounding_ctx to infer what is marked. The inventory must come entirely from visual observation of the image. surrounding_ctx may only be used afterwards to identify which section/figure/formula a mark is adjacent to.

Once the inventory is complete:

  • For whole_page: false: the inventory typically has one entry → one record.
  • For whole_page: true: each inventory entry (or tight cluster) → one record. Never combine multiple entries into one record. A page with 5 marks → 5 records.

For each record:

  • Verbatim: [Handwritten: "transcribed text"] for handwriting, or [Handwritten: <type> under/around "<exact text>"] for marks.
  • If label non-empty: append — label: "label" inside the brackets.
  • Embed the crop: ![](./crop_<stem>_p<N>_c<M>.png) (single crop) or ![](./page_<stem>_p<N>.png) (first record for a whole-page only; omit in subsequent records for the same page) — immediately before the verbatim.
  • Use bbox/page_width/page_height only for margin vs inline and coarse vertical zone — never report raw numbers.

Highlights (annotationType: "highlight"):

  • Describe exactly which phrase is highlighted.
  • Verbatim: [Highlight: "annotationText"]
  • If annotationComment non-empty: [Highlight: "annotationText" — Note: "annotationComment"]

Typed notes / area annotations (other annotationType values):

  • Verbatim: [Note: "annotationComment"]

Collect all records in reading order (by page and position).


Step 5a — Write the source file

  1. Read .claude/Templates/source.md.
  2. Fill in:
    • type: zotero_source
    • title: from metadata, or inferred from the first page of body text
    • concepts_mentioned: key concepts as a YAML inline list
    • source_links: one entry per ingested file. Each entry is a structured object:
      • Plain local file (no Zotero match): - path: <abs_path>
      • Zotero-linked file: - zotero: {item_key: <item_key>, linked_path: <zotero_path>}
      • Both (distinct files merged): - path: <abs_path> - zotero: {item_key: <item_key>, linked_path: <zotero_path>}
    • ## Content: write the extracted body text verbatim, with no rewriting, no summarisation, and no omissions:
      • Single source, or all sources identical (compare after stripping leading/trailing whitespace): paste the text once.
      • Sources differ: write each version under its own ### <source_path> subheading, verbatim.
  3. Get today's date: date +%F
  4. Slugify the title → snake_case. Target: sources/zotero_<slug>.md. If the file already exists, use AskUserQuestion:
    • Question: "sources/zotero_<slug>.md already exists. Overwrite?"
    • Options: "Yes, overwrite", "No, keep existing" Do not write or call any further tools until the user answers.

Step 5b — Write annotation files and merge

Skip this step entirely (and report) if the PDF had no annotations.

  1. Create notes/zotero_<paper_slug>/ if it doesn't exist:
    python3 -c "import os; os.makedirs('notes/zotero_<paper_slug>', exist_ok=True)"
  2. Write one temporary file per record from Step 4, in reading order. For each record, write notes/zotero_<paper_slug>/_note_<NN>_<topic>.md (underscore prefix marks it as temporary) containing:
    ### <topic>
    
    <description from Step 4>
    
    ![](./crop_or_page_filename.png)   ← ink annotations only
    
    [verbatim content]
    Complete each file fully before moving to the next. Do not batch or summarise.
  3. Merge all temporary files into notes/zotero_<paper_slug>/annotations.md. Read .claude/Templates/note.md for the frontmatter shape:

    • type: zotero_annotation
    • title: <paper title> — Annotations
    • concepts_mentioned: union of all concept lists from Step 4 records
    • source_links: list of all PDF paths ingested (raw source paths, not the derived source file) — one entry per PDF used

    ## Content = concatenation of all _note_*.md files in reading order, separated by ---.

    If annotations.md already exists, use AskUserQuestion:

    • Question: "notes/zotero_<paper_slug>/annotations.md already exists. Overwrite?"
    • Options: "Yes, overwrite", "No, keep existing" Do not write or call any further tools until the user answers.
  4. Delete the temporary files after annotations.md is written:
    python3 -c "
    import os, glob
    for f in glob.glob('notes/zotero_<paper_slug>/_note_*.md'):
        os.remove(f)
    "

Wrap up

Report:

  • Source file written: sources/zotero_<slug>.md
  • Annotation note written: notes/zotero_<paper_slug>/annotations.md (N annotations)
  • Ink crops written: list any notes/zotero_<paper_slug>/crop_*.png and page_*.png
  • Zotero match status (item_key or "no match")
  • Annotation counts: N highlights, N typed notes, N ink annotations
  • Anything skipped (one-line reason each)

Then ask the user:

  • Run /retrieve <topic> to find related sources and existing pages.
  • Run /collate <topic> to synthesise a paper or concept page from this note together with other sources on the same topic.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.