pyzotero

pyzotero skill 개요

pyzotero가 하는 일

pyzotero는 Zotero Web API v3를 위한 Python 클라이언트입니다. pyzotero skill을 사용하면 API 호출을 직접 손으로 조립하지 않아도 Zotero의 항목, 컬렉션, 태그, 첨부 파일, 인용 내보내기를 읽고, 생성하고, 업데이트하고, 삭제할 수 있습니다.

누가 사용하면 좋은가

자동화된 참고문헌 관리, 문헌 워크플로, 또는 Zoterosync 스타일의 라이브러리 유지보수를 하는 사람에게 가장 잘 맞습니다. 특히 학술 연구용 pyzotero, 스크립트 기반 서지 정리, 그리고 신뢰할 수 있는 Zotero 연동이 필요한 연구 파이프라인에 적합합니다.

이 skill을 설치할 가치가 있는 이유

pyzotero skill의 핵심 가치는 Zotero를 프로그래밍 가능한 라이브러리 백엔드로 바꿔준다는 점입니다. 일회성 프롬프트 대신, 메타데이터 조회, 그룹/개인 라이브러리 관리, 첨부 파일 가져오기, 인용 형식 내보내기를 더 적은 API 실수로 반복 실행할 수 있는 방식이 생깁니다.

pyzotero skill 사용 방법

pyzotero 설치하기

Python 패키지를 직접 설치하고, 로컬 Zotero 데스크톱 검색이 필요할 때만 CLI extra를 추가하세요.

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를 사용해 내 group library의 항목을 나열하고, reviewed 태그가 붙은 journal article만 필터링한 뒤, 결과를 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와 indexing은 references/files-attachments.md와 references/full-text.md
• BibTeX, CSL-JSON, citation 출력은 references/exports.md
• rate limits, conflicts, invalid fields는 references/error-handling.md

pyzotero를 더 잘 쓰기 위한 실전 워크플로

1. 원격 API 접근이 필요한지, 아니면 로컬 전용 검색이면 충분한지 먼저 확인하세요.
2. 메서드를 호출하기 전에 올바른 library에 맞는 credentials를 설정하세요.
3. 먼저 read 호출 하나로 시험한 뒤, 그다음 batch 작업으로 넓히세요.
4. update와 delete에는 title이 아니라 key를 사용하세요.
5. 결과가 실제로 다룰 수 있는 크기가 되도록 pagination이나 output limits를 초반에 넣으세요.

pyzotero skill FAQ

pyzotero는 프로그래머만 쓰는 tool인가요?

아닙니다. Python 워크플로에서 특히 유용하지만, 짧은 설치 과정을 따라가고 구조화된 입력을 줄 수 있다면 비전문가도 충분히 사용할 수 있습니다. 가끔 수동으로 citation export만 필요하다면 일반 Zotero 프롬프트가 더 단순할 수 있습니다.

pyzotero는 개인 라이브러리와 그룹 라이브러리 모두 지원하나요?

네. pyzotero skill은 둘 다 지원하지만, 하나의 Zotero 인스턴스는 하나의 라이브러리에만 묶입니다. 개인 라이브러리와 공유 lab 또는 team library 사이를 오가야 할 때 이 점이 중요합니다.

언제 pyzotero를 쓰지 않는 편이 좋나요?

Zotero 안에서 한 번만 빠르게 citation formatting을 하면 되는 경우, 또는 local Zotero desktop app 없이 full-text search가 꼭 필요할 때는 pyzotero를 쓰지 마세요. CLI는 local Zotero에 의존하고, API는 같은 수준의 local full-text search 동작을 제공하지 않습니다.

pyzotero는 Academic Research에 좋은가요?

네, 특히 대량 문헌 관리, 참고문헌 정리, 첨부 파일 처리, 재현 가능한 export에 강합니다. 반대로 작업의 중심이 논문을 읽는 일이고 Zotero 데이터를 정리하거나 변환하는 일이 아니라면 효용이 떨어집니다.

pyzotero skill 개선 방법

부족한 라이브러리 정보를 skill에 명확히 주기

가장 큰 품질 향상은 처음부터 library context를 분명히 적는 데서 나옵니다. pyzotero에서는 library ID, user인지 group인지, 그리고 local mode인지 remote API인지까지 포함하세요. 이 정보가 없으면 출력이 지나치게 일반적이 되거나 잘못된 접근 경로를 고를 수 있습니다.

원하는 데이터 형태를 분명히 말하기

단일 item인지, item 목록인지, collection tree인지, attachment metadata인지, export 파일인지 구체적으로 말하세요. 좋은 pyzotero 입력 예시는 다음과 같습니다.

• “keys와 titles만 반환해 주세요”
• “이 item keys들의 abstractNote를 업데이트해 주세요”
• “상위 50개 결과를 BibTeX로 export해 주세요”
• “full text에 gene editing이 들어간 PDF를 찾아 주세요”

자주 생기는 실패 모드에 주의하기

가장 흔한 pyzotero 오류는 title을 key 대신 쓰는 것, authentication setup을 건너뛰는 것, batch write를 한 번에 너무 많이 보내는 것입니다. 또 하나 흔한 문제는 API만으로 local full-text search가 된다고 기대하는 경우입니다. 결과가 어긋나면 쿼리가 item metadata, full text, collection filter 중 무엇을 써야 하는지 다시 확인하세요.

첫 결과를 바탕으로 반복 개선하기

첫 출력이 너무 넓다면 item type, tag 조건, collection key, date range를 추가해 좁히세요. 첫 write/update가 위험하다면, pyzotero에게 payload를 dry-run으로 보여 달라고 하거나 변경 적용 전에 정확한 item fields를 먼저 보여 달라고 요청하세요. 실제 연구 워크플로에서 pyzotero 사용성을 가장 빠르게 높이는 방법입니다.