108 lines
5.9 KiB
Markdown
108 lines
5.9 KiB
Markdown
---
|
|
name: zotero-ai-notes
|
|
description: Generate, resume, audit, and maintain AI-generated Zotero child-note literature notes using Zotero Local API metadata, Zotero Web API writes, and AwesomeGPT/DeepSeek-compatible chat settings. Use when the user asks to batch-generate Zotero literature notes, fill Zotero notes from Obsidian templates, use AwesomeGPT or DeepSeek for Zotero papers, skip existing AI notes, resume interrupted Zotero note generation, audit duplicate Zotero AI notes, or package/upgrade this Zotero note workflow.
|
|
---
|
|
|
|
# Zotero AI Notes
|
|
|
|
Use this skill to create Zotero child notes from local Zotero items with the user's literature-note templates.
|
|
|
|
This skill is also Obsidian-aware: templates, prompts, and the local audit cache live in the user's Obsidian vault, so preserve Obsidian Flavored Markdown conventions when reading or adapting those materials. Read [references/obsidian-integration.md](references/obsidian-integration.md) before changing template handling, adding vault-facing files, or generating Markdown meant to round-trip through Obsidian. Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before pulling in more ideas from `kepano/obsidian-skills`.
|
|
|
|
Core script:
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
|
|
```
|
|
|
|
Fast audit script:
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
|
|
```
|
|
|
|
## Requirements
|
|
|
|
- Zotero Desktop must be open and Local API enabled at `http://127.0.0.1:23119`.
|
|
- The vault must contain `00 Templater` with:
|
|
- `01 ...md` research-article template
|
|
- `02 ...md` review-article template
|
|
- `03 ...md` AI prompt
|
|
- `ZOTERO_API_KEY` must be available in the process environment for write access.
|
|
- LLM settings come from either:
|
|
- `AWESOMEGPT_API_KEY`, `AWESOMEGPT_BASE_URL`, `AWESOMEGPT_MODEL`, or
|
|
- AwesomeGPT preferences in the default Zotero profile.
|
|
|
|
Never store API keys in the skill. If keys appear in chat or logs, tell the user to rotate them.
|
|
|
|
## Obsidian-Aware Template Rules
|
|
|
|
- Treat `00 Templater` as the source of truth for note structure. Do not rewrite the user's templates unless asked.
|
|
- Preserve Obsidian syntax from templates, including wikilinks, callouts, tags, math, highlights, comments, and YAML frontmatter.
|
|
- Zotero child notes should remain clean Markdown/HTML note content; do not insert visible AI banners such as `AI Literature Note` or `AI文献笔记`.
|
|
- If generating any auxiliary `.md` file in the vault, use valid Obsidian properties and internal links as described in [references/obsidian-integration.md](references/obsidian-integration.md).
|
|
- Keep operational artifacts hidden or clearly tool-scoped: cache/index files should stay under `00 Templater` and begin with a dot when practical.
|
|
|
|
## Common Workflows
|
|
|
|
### Single item
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-key SXAIQUJT --skip-existing
|
|
```
|
|
|
|
Set `ZOTERO_API_KEY` in the current shell before running live writes, but do not print or paste the value into logs or chat.
|
|
|
|
### Multiple item keys
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --item-keys "SXAIQUJT X7GJZ627 ZCZXGRAM" --limit 0 --skip-existing --fulltext-chars 4000
|
|
```
|
|
|
|
### Whole library
|
|
|
|
Use only after the user explicitly approves library-wide writes.
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\generate_zotero_ai_note.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --all --limit 0 --skip-existing --fulltext-chars 4000
|
|
```
|
|
|
|
For long runs, prefer 20-30 item batches. If a run times out, rerun with `--skip-existing`; the script resumes by checking child notes for the source Zotero item link.
|
|
|
|
### Find items missing generated notes
|
|
|
|
Do this deterministically; do not ask DeepSeek or another LLM to compare library state.
|
|
|
|
First build or refresh the cache:
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --rebuild
|
|
```
|
|
|
|
Later fast checks:
|
|
|
|
```powershell
|
|
py "$env:USERPROFILE\.codex\skills\zotero-ai-notes\scripts\audit_zotero_ai_notes.py" --vault "C:\Users\qyh15\Documents\Obsidian Vault" --keys-only
|
|
```
|
|
|
|
The cache lives at `<vault>\00 Templater\.zotero-ai-notes-index.json`. Use `--refresh` or `--rebuild` when notes were edited outside this workflow.
|
|
|
|
## Operating Rules
|
|
|
|
- For live writes, state that Zotero child notes will be created.
|
|
- Use `--dry-run` for first-time validation or template changes.
|
|
- Use `--fulltext-chars 4000` for cheap, lightweight notes; increase only when the user asks for deeper notes.
|
|
- Do not add visible machine markers to note bodies. Use the Zotero item link for duplicate detection.
|
|
- Do not delete duplicate notes unless the user explicitly requests cleanup.
|
|
- Use `audit_zotero_ai_notes.py` for missing-note checks. Reserve DeepSeek for generating or improving note content.
|
|
- If PowerShell/cmd output has Unicode issues, set `PYTHONIOENCODING=utf-8` or rely on script UTF-8 reconfiguration.
|
|
- If PDF full text is unavailable, allow the script to fall back to metadata, abstract, BibTeX, and optional local PDF extraction if a Python PDF library exists.
|
|
|
|
## Upgrade Points
|
|
|
|
Read [references/upgrade-plan.md](references/upgrade-plan.md) before changing behavior, adding cleanup, adding collection targeting, or improving note quality.
|
|
|
|
Read [references/obsidian-integration.md](references/obsidian-integration.md) before adding Obsidian vault exports, Bases views, markdown normalization, or Obsidian CLI integration.
|
|
|
|
Read [references/upstream-obsidian-skills.md](references/upstream-obsidian-skills.md) before doing another merge from `kepano/obsidian-skills`.
|