zotero-library-curator

name: zotero-library-curator description: Audit and curate a Zotero library — find duplicate DOIs, orphan items missing required tags, propose collection rebinds, identify bloated or under-used collections, generate tag hygiene reports, emit preview-only cleanup plans. Use when the user asks to "audit Zotero", "find duplicates", "tag hygiene report", "which collections are bloated or under-used", or "propose a Zotero cleanup plan". Defers all CRUD operations to the standalone `zotero-skills` skill or `research-hub zotero` CLI. Includes a backup-first reminder before any apply/CRUD handoff suggestion. compatibility: Portable `SKILL.md` instructions for agentskills.io-style hosts. Depends on the standalone `zotero-skills` skill OR the `research-hub` CLI for actual Zotero connectivity. On Claude Code the sibling skill usually lives at ~/.claude/skills/zotero-skills/; on other hosts substitute the host's skills directory or rules path.

Sit one layer above the standalone zotero-skills skill. This skill reads the Zotero library, runs audit + hygiene checks, and emits preview plans. It does NOT perform the changes itself.

For any actual create / update / delete operation, defer to:

The standalone zotero-skills skill (full CRUD, dual local/web API routing); or
The research-hub zotero CLI (backfill --tags --notes [--apply], etc., which is preview-first by default).

Prerequisite check (do this first)

Reading the Zotero library requires a connection. The skill works in two modes:

Read-only audit / preview — needs either zotero-skills (Zotero local API) or the research-hub zotero CLI to inspect items.
Apply cleanup — must defer to zotero-skills or research-hub zotero ... --apply.

Before running, verify at least one is present. The zotero-skills check is host-dependent — adapt to your agent's skills directory:

research-hub doctor 2>/dev/null  # if research-hub CLI installed
# Check whether the zotero-skills sibling skill is installed.
# Claude Code:  ls ~/.claude/skills/zotero-skills/SKILL.md
# Hermes:       ls ~/.hermes/skills/research/zotero-skills/SKILL.md
# Other hosts:  ls <host-skills-dir>/zotero-skills/SKILL.md

If neither is available, the host has loaded these instructions but has no Zotero-capable runtime (research-hub CLI or standalone zotero-skills). Stop and tell them:

This skill audits a Zotero library, which needs Zotero connectivity via one of:

The standalone zotero-skills skill (handles Zotero local API). Install via your host's skill installer (e.g. on Claude Code, git clone https://github.com/WenyuChiou/zotero-skills ~/.claude/skills/zotero-skills; on Hermes, hermes skills install https://raw.githubusercontent.com/WenyuChiou/zotero-skills/master/SKILL.md).

Or the research-hub CLI: pip install research-hub-pipeline

Either path needs Zotero configured (local API on port 23119, or Zotero Web API key). Once one is set up, re-run your audit request.

When to use

Trigger phrases:

"Audit my Zotero library."
"Find duplicate DOIs in Zotero."
"Find Zotero items missing required tags."
"Propose a tag hygiene cleanup plan."
"Generate a Zotero cleanup preview before I apply anything."
"Which Zotero collections are bloated / under-used?"

Not for:

Adding, editing, or deleting items — defer to zotero-skills skill.
Backfilling tags/notes on items already in research-hub clusters — use research-hub zotero backfill (already preview-first).
Cluster-level operations — use research-hub clusters commands.
Searching the library for a specific paper — use zotero-skills search, not the curator.

Inputs

In priority order:

research-hub cluster registry (.research_hub/clusters.yaml) — to know which Zotero collections belong to which research clusters.
Zotero library state via local API (fast, read-only) — list items, list collections, list tags. Use zotero-skills READ Operations patterns directly; don't reinvent.
research-hub dedup index (.research_hub/dedup_index.json) — precomputed DOI/title hash table; far cheaper than a fresh scan.
Optional: backfill report from research-hub zotero backfill (saved to .research_hub/backfill-*.md) — historical state of prior cleanups.

Audit checks

Five checks: duplicate DOI scan, orphan-tag scan, cross-collection cluster mismatch, tag hygiene report, collection bloat / sparsity. Pick the relevant subset for each user request.

Full check details + suggested fixes for each: references/audit-checks.md.

Output discipline

Always emit a preview plan, never apply. The report has 5 sections that map 1:1 onto the audit checks (skip a section if its check returned no findings) plus a "Suggested follow-ups" section listing concrete CLI commands for the user to run.

The "Suggested follow-ups" section MUST open with a one-line backup reminder before any apply/CRUD handoff suggestion:

Back up first. In Zotero desktop: File → Export Library → Zotero RDF. Any modifications via zotero-skills or research-hub zotero ... --apply are irreversible without this snapshot.

This is required because this skill is read-only but its output typically feeds an apply step run by zotero-skills. Surfacing the backup step at handoff prevents the most common data-loss class (accidental tag mass-rename or collection move with no undo).

Full report template: references/report-template.md.

If the report has 0 issues, emit a single OK line and stop.

Token-saving behavior

Read the dedup index first; only hit the Zotero local API for items not in the index.
Cap full-library scans at 100 items per audit run unless the user explicitly says "full library".
Don't quote item titles back if a DOI / Zotero key is enough.
Cache the report in .research_hub/curator-<timestamp>.md if the user asks "save this report".

What NOT to do

Do NOT call any Zotero create / update / delete endpoint. That's zotero-skills' or research-hub's job, with explicit user --apply.
Do NOT rename tags directly — propose, then defer to manual review or zotero-skills batch update.
Do NOT trash duplicate items automatically — propose, then defer to research-hub zotero backfill --apply or manual delete.
Do NOT redocument the zotero-skills CRUD primitives — link to them. The whole point of this skill is to be the layer above.

zotero-library-curator