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.

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 before changing template handling, adding vault-facing files, or generating Markdown meant to round-trip through Obsidian. Read references/upstream-obsidian-skills.md before pulling in more ideas from kepano/obsidian-skills.

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.

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.
• 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

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.

Read references/obsidian-integration.md before adding Obsidian vault exports, Bases views, markdown normalization, or Obsidian CLI integration.

Read references/upstream-obsidian-skills.md before doing another merge from kepano/obsidian-skills.