QQnote-skill/SKILL.md

name

description

zotero-ai-notes

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.

Core script:

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:

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.

Common Workflows

Single item

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

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.

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:

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:

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 before changing behavior, adding cleanup, adding collection targeting, or improving note quality.