rh-zotero-plugin-adapter - SKILL.md Agent Skill

name: rh-zotero-plugin-adapter description: Maintain and debug the Research Harness Zotero plugin adapter. Trigger on Zotero side panel, Zotero reader, Zotero copy/clipboard, local RH API bridge, PDF attachment, RH-to-Zotero sync, seed-paper previews, plugin restart/dev-refresh, or requests to align Zotero plugin behavior with RH CLI/MCP skills without duplicating existing research workflow skills. public_suite: zotero task_type: adapter-maintenance data_access_level: local-files inputs: Zotero plugin state, bridge logs, local API URL, user action outputs: adapter diagnosis, code patch, verification result, sync guidance gates: preserve user Zotero data; do not duplicate research workflow semantics artifact_schemas: zotero_sync_report estimated_runtime: 10-60 min

RH Zotero Plugin Adapter

Use this skill when changing, debugging, or reviewing the Research Harness Zotero Desktop plugin and its local HTTP bridge.

This skill is an adapter maintenance guide, not a research workflow. Reuse the existing RH skills for research semantics:

New topic or project bootstrap: research-init
Literature discovery and seed expansion: literature-search, citation-trace
Paper pool health, PDF acquisition, metadata, sync: paper-sync, paper-verify
PDF marginalia and deep reading: paper-reading-annotation
Claims, gaps, sections, publication package: claim-extraction, gap-analysis, section-drafting, publication-pack

Operating Principle

Do not rely on a skill, prompt, or hardcoded query to make the running plugin stable. Runtime stability belongs in typed context models, capability contracts, preview/confirm/apply guardrails, traces, and tests.

Use this skill to keep future agent edits inside those boundaries.

This follows the large-lab agent design pattern: keep workflows simple and composable, expose clear tool/capability interfaces, add guardrails around high-impact actions, and verify behavior with traces/tests rather than relying on prose instructions alone.

Read First

Before changing Zotero plugin behavior, read the smallest relevant set:

docs/zotero-rh-panel.md
integrations/zotero-rh-panel/content/rh-zotero-panel.js
packages/research_harness_mcp/research_harness_mcp/http_api.py
packages/research_harness/research_harness/zotero_sync.py
packages/research_harness/research_harness/zotero_resource.py
For platform behavior, read references/zotero-platform-checklist.md.
For action routing or write behavior, read references/intent-routing-contract.md.
For agent-system design rationale, read references/agent-design-principles.md.

Architecture Boundary

Zotero plugin JavaScript captures Zotero context, renders UI, handles reader selection affordances, and executes only allowlisted local Zotero actions.
RH HTTP API resolves paper/topic context, selects typed capabilities, builds action previews, owns write semantics, and records provenance where applicable.
zotero_sync.py owns RH/Zotero sync semantics.
zotero_resource.py owns Web API vs local connector resource adapters.
Research primitives must keep using MCP/RH service paths. Do not bypass provenance by reimplementing primitive logic in the plugin.

Context Modes

Classify the Zotero state before interpreting natural language:

library: no selected collection or item; show library-level guidance.
collection: current Zotero collection/folder; supports topic bootstrap, seed-paper search, and RH-to-Zotero import previews.
item: concrete Zotero item or parent item; supports paper chat, PDF attach, item sync, note/annotation flows.
reader_selection: selected text or screenshot from Zotero Reader; supports explain, translate, append-to-composer, and copy.
service_dev: local API startup, warmup, restart, XPI/source refresh, health.

Mode gates come before keyword matching. Example: a collection-mode message that asks for a new research direction and mentions PDFs should route to seed/topic bootstrap, not item-level PDF attachment.

Capability Contract

Every plugin action should be represented as a capability with:

required context mode
required RH/Zotero state
read-only vs write
action preview schema
apply transport: http_json or zotero_local
failure message when preconditions are missing
unit/API/panel tests

Write capabilities must follow:

detect -> action_preview -> explicit confirm -> apply

Never execute a Zotero/RH write based only on model text. Never let frontend code infer write targets from streamed assistant prose.

Routing Rules

Resolve Zotero mode and matched RH paper/topic first.
Check capability preconditions second.
Use user text to choose among allowed capabilities third.
Use LLM/free text only for extraction or explanation, not authorization.
Do not hardcode a user's real topic/query in production logic. Tests may use generic fixture phrases, but production behavior must generalize.

Verification

For Zotero plugin changes, run the focused matrix:

pytest packages/research_harness_mcp/tests/test_zotero_api.py -q
pytest packages/research_harness/tests/test_zotero_sync.py -q
node --test integrations/zotero-rh-panel/tests/rh-zotero-panel.test.js
node --check integrations/zotero-rh-panel/content/rh-zotero-panel.js

When plugin packaging or source loading changed, also run:

./integrations/zotero-rh-panel/build-xpi.sh
./scripts/zotero-dev-refresh.sh --link-only

If startup behavior changed, verify GET /api/health, auto-start guardrails, and POST /api/zotero/warmup.

Anti-Patterns

Adding phrase-order fixes without a context/capability test.
Adding another research workflow inside the Zotero plugin instead of invoking existing RH skills/service behavior.
Treating collection-level initialization as item-level PDF attach because the user mentioned PDF or Zotero.
Writing Zotero data without preview and explicit confirmation.
Using arbitrary filesystem paths from chat/model output for attachments.
Relying on DOM hacks where Zotero exposes an official plugin API.