pyzotero

pyzotero スキルの概要

pyzotero でできること

pyzotero は Zotero Web API v3 向けの Python クライアントです。pyzotero スキルを使うと、API 呼び出しを手で組み立てなくても、Zotero のアイテム、コレクション、タグ、添付ファイル、引用エクスポートの読み取り・作成・更新・削除を扱えます。

どんな人に向いているか

自動化された文献管理、文献ワークフロー、Zotero sync 風のライブラリ保守を行う人に特に向いています。とくに pyzotero for Academic Research、スクリプト化した文献整理、信頼性の高い Zotero 連携が必要な研究パイプラインに適しています。

このスキルを入れる価値

pyzotero スキルの最大の価値は、Zotero をプログラム可能なライブラリ基盤に変えることです。単発のプロンプトではなく、メタデータの検索、グループライブラリや個人ライブラリの管理、添付ファイルの取得、引用形式の出力を、API ミスを減らしながら繰り返し実行できるようになります。

pyzotero スキルの使い方

pyzotero をインストールする

Python パッケージをそのまま追加し、ローカルの Zotero デスクトップ検索が必要な場合だけ CLI の追加オプションを入れてください。

uv add pyzotero
uv add "pyzotero[cli]"

pyzotero の導入を検討しているなら、CLI が役立つのは「起動中のローカル Zotero アプリを検索したい」ときだけです。リモート API の作業には不要です。

適切な入力から始める

pyzotero をうまく使うには、リクエストに次の情報を入れるのが重要です。

• ライブラリ種別: user または group
• 操作: read, create, update, delete, export, search
• 対象オブジェクト: item key、collection key、tag、attachment、saved search
• 出力形式: Python objects、JSON、BibTeX、CSL-JSON、HTML citations

プロンプトの形の例:

pyzotero を使ってグループライブラリ内のアイテムを一覧化し、reviewed タグ付きの journal articles に絞り込んで、結果を CSL-JSON で書き出してください。

この順番でファイルを読む

実際のセットアップでは、まず SKILL.md を読み、そのあと作業内容に合う参照ファイルを確認します。

• API keys、user IDs、local mode は references/authentication.md
• 取得と絞り込みは references/read-api.md と references/search-params.md
• 作成・更新・削除の流れは references/write-api.md
• PDF とインデックスは references/files-attachments.md と references/full-text.md
• BibTeX、CSL-JSON、引用出力は references/exports.md
• rate limits、conflicts、無効なフィールドは references/error-handling.md

pyzotero を実務でうまく使う流れ

1. リモート API アクセスが必要か、ローカル限定検索で足りるかを確認する。
2. メソッドを呼ぶ前に、正しいライブラリ用の認証情報を設定する。
3. まずは 1 回だけ read を試し、そのあと batch 操作に広げる。
4. update や delete には title ではなく key を使う。
5. 結果が扱える量になるよう、早めに pagination や出力上限を入れる。

pyzotero スキル FAQ

pyzotero はプログラマー専用ですか？

いいえ。Python ワークフローでは特に便利ですが、短いインストール手順に従い、構造化された入力を渡せる人なら、非エンジニアでも十分使えます。たまに手動で引用を書き出すだけなら、通常の Zotero プロンプトのほうが簡単な場合もあります。

pyzotero は個人ライブラリとグループライブラリの両方に対応していますか？

はい。pyzotero スキルは両方をサポートしますが、1 つの Zotero インスタンスは 1 つのライブラリに紐づきます。個人ライブラリと共有の研究室・チームライブラリを行き来する場合は、この点が重要です。

どんなときに pyzotero を使わないほうがいいですか？

Zotero 本体の中で、ちょっとした引用フォーマットだけを一度だけ作りたい場合や、ローカルの Zotero デスクトップアプリなしで全文検索をしたい場合は、pyzotero は向きません。CLI はローカルの Zotero に依存しますし、API だけでは同じローカル全文検索の挙動は得られません。

pyzotero は Academic Research に向いていますか？

はい。とくに大量の文献管理、参考文献の整理、添付ファイルの扱い、再現可能なエクスポートに向いています。いっぽうで、Zotero データを整理・変換するより、論文を読むこと自体が中心なら、恩恵は小さくなります。

pyzotero スキルの改善方法

足りないライブラリ情報を先に渡す

品質を大きく上げるコツは、最初にライブラリの文脈をはっきり指定することです。pyzotero では、library ID、user か group か、local mode か remote API かを入れてください。これがないと、出力が曖昧になったり、間違ったアクセス経路が選ばれたりしやすくなります。

ほしいデータ形を明確にする

単一アイテムがほしいのか、アイテム一覧なのか、collection tree なのか、attachment metadata なのか、export file なのかを明示します。良い pyzotero 入力の例は次の通りです。

• 「keys と titles だけ返してください」
• 「これらの item keys の abstractNote を更新してください」
• 「上位 50 件を BibTeX で export してください」
• 「full text に gene editing を含む PDF を探してください」

よくある失敗パターンに注意する

pyzotero で多いエラーは、title を key の代わりに使うこと、認証設定を飛ばすこと、write を一度に batch で詰め込みすぎることです。もう 1 つよくあるのは、API だけでローカル全文検索ができると思い込むケースです。結果がずれているなら、検索対象が item metadata なのか full text なのか、collection filters を使うべきなのかを見直してください。

まずは 1 回出してから詰める

最初の出力が広すぎるなら、item type、tag の条件、collection key、日付範囲を足して絞り込みます。最初の write/update が危険そうなら、変更前に payload を dry-run させるか、適用される item fields を正確に表示させてください。これが、実際の研究ワークフローで pyzotero を速く改善する最短ルートです。