SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillszot-skills

zot-skills

Agents & models

View repository

Updated 10-15 17:24

About this skill

zot-skills

The goal of this skill is not to display the command surface, but to reliably land the user's natural-language Zotero tasks on the correct runtime path, and then bring back the truly useful results.

First grasp these principles

  • As long as the task's real goal is to operate onan existing local Zotero libraryoran existing/to-be-created reading workspace, use this skill, even if the user did not say zot。
  • In Claude Code or Codex, users should state their needs directly, not memorize commands first. The skill is responsible for translating needs into runtime actions.
  • zot is the only execution surface.ref/ The old Python reference implementation in zot mcp serve are not the current primary path.
  • In the answer, give the conclusion, evidence, changes, or reason for failure first. Do not dump raw JSON to the user first.

First bucket by intent

1. Look up items

Users usually say:

  • "Find papers related to reward hacking in my library"
  • "Find that paper by Smith2024"
  • "Show me the 10 most recent items just added to the library"
  • "See what items are in this collection"
  • "List the feeds in the current library"

Priority routing:

  • General in-library search:library search
  • Direct citation key lookup:library citekey
  • Recently added items:library recent --count
  • Fine-grained collection reading:collection get / subcollections / items / item-count / tags
  • Library-level organizational information:library tags / libraries / feeds / feed-items

2. Retrieve evidence

Users usually say:

  • "Pull out this reference's details, children, and citations"
  • "Pull out all PDF annotations, outline, and notes"
  • "Download the attachment to local"

Priority routing:

  • Single-item main entry point:item get / related / children / cite / export
  • PDF evidence:item pdf / fulltext / outline
  • annotation：item annotation list / search
  • Attachment download:item download <attachment-key>

3. Create a workspace

Users usually say:

  • "Create an llm-safety workspace for me"
  • "Organize papers related to mechanistic interpretability into a long-term workspace"
  • "Later I want to do question-answering retrieval within this topic"

Priority routing:

  • Create and maintain:workspace new / add / import / remove / delete
  • Index and query:workspace index / search / query

Note:

  • The workspace name must be kebab-case, for example llm-safety
  • workspace search is keyword search
  • workspace query is question-answering retrieval

4. Save queries

Users usually say:

  • "Save this filter condition as a Zotero saved search"
  • "List what saved searches I currently have"
  • "Delete this expired saved search"

Priority routing:

  • library saved-search list
  • library saved-search create
  • library saved-search delete

Boundary:

  • The Zotero Web API currently only provides saved search metadata and conditions, and does not directly return search results
  • It should be explained that what is saved is the "query condition", not a "dynamic result set snapshot"

5. Download attachments

Users usually say:

  • "Download the attachment ATCH005"
  • "Pull the PDF of this item into the current directory"

Preferred routing:

  • Known attachment key:item download
  • When only the parent item is known: first item children, then determine the attachment key

Things not to do:

  • Do not disguise attachment downloads as item attach
  • Do not mix upload and download into a single action

6. Safe writes

Users typically say:

  • "Add a note to this reference"
  • "Tag it with priority"
  • "Add this item to a collection"
  • "Preview first, then merge these two references"
  • "Merge duplicate items"
  • "Write the formal publication info back to the preprint"

Preferred routing:

  • Items and tags:item note ... / item tag ... / item update
  • Import:item add-doi / add-url / add-file
  • Manual merge:item merge
  • collection relationships:collection add-item / remove-item / create / rename / delete
  • duplicates：library duplicates / duplicates-merge
  • Status sync:sync update-status

7. Configuration troubleshooting

Users typically say:

  • "Why can't this environment write to Zotero"
  • "First help me check whether the configuration is correct"
  • "Switch the current profile to work"
  • "Initialize a new config profile"

Preferred routing:

  • Diagnostics:doctor
  • Configuration:config show / init / set / profiles list / profiles use

Invocation order

  1. If the system already has zotinstalled, prefer zot --json ...
  2. Only in a development repository environment and when zot is not in PATH should you fall back to:
cargo run -q -p zot-cli -- ...
  1. Keep the same invocation method throughout a task; do not switch back and forth.

Diagnostic gate

For the following scenarios, run doctor：

  • First contact with this environment
  • Any write operation
  • PDF / outline / annotation / attachment related tasks
  • semantic index / semantic search / workspace query
  • citation key lookup
  • saved search / configuration troubleshooting / profile switching
  • When the user says "why doesn't it work"

First choice:

zot --json doctor

Development environment fallback:

cargo run -q -p zot-cli -- --json doctor

Focus on these fields:

  • db_exists
  • write_credentials.configured
  • pdf_backend.available
  • better_bibtex.available
  • libraries.feeds_available
  • semantic_index
  • annotation_support
  • embedding.configured
  • config_file

Hard constraints

  • --library only accepts user or group:<id>
  • workspace names must be kebab-case
  • zot mcp serve is currently unavailable
  • item add-file does not support --attach-mode
  • item annotation create / create-area only applies to PDF attachments
  • library saved-search handles the conditions of a saved query, not the result items
  • Never directly modify zotero.sqlite

Safety gate

By default, treat as actions with side effects:

  • item create
  • item add-doi
  • item add-url
  • item add-file
  • item update
  • item trash
  • item restore
  • item attach
  • item merge --confirm
  • item note add
  • item note update
  • item note delete
  • item tag add
  • item tag remove
  • item tag batch
  • item annotation create
  • item annotation create-area
  • collection create
  • collection rename
  • collection delete
  • collection add-item
  • collection remove-item
  • library saved-search create
  • library saved-search delete
  • library duplicates-merge --confirm
  • sync update-status --apply
  • config init
  • config set
  • config profiles use

Execution rules:

  1. When the user is only "looking", "analyzing", or "evaluating", do not secretly write to the library.
  2. Ordinary, single-item, reversible write operations may be performed after the user explicitly requests them.
  3. For these high-risk actions, first summarize the changes that are about to happen, then execute:
    • item trash
    • item note delete
    • item merge --confirm
    • collection delete
    • library saved-search delete
    • library duplicates-merge --confirm
    • sync update-status --apply
  4. When write permission is missing, stop at read-only analysis; do not pretend to succeed.

Common semantic differences

  • workspace search is keyword search,workspace query is question-answering retrieval
  • library recent --count 10 is the most recent N items,library recent 2026-04-01 --limit 20 filters by time boundary
  • library semantic-search is library-level semantic retrieval, not equivalent to workspace query
  • item add-doi / item add-url / item create --doi|--url|--pdf supports --attach-mode
  • item add-file can include --doi to fill in metadata, but does not accept --attach-mode
  • feeds are not accessed through --library group:<id> , but instead use library feeds / feed-items
  • item download Download the local attachment file,item attach upload a new attachment
  • item merge is the general merge with manually selected keeper/source,library duplicates-merge is to first find duplicates, then merge by keeper
  • config show is to view the effective configuration,config profiles use is to switch the default profile

Typical mappings from natural language to actions

  • "Find papers related to reward hacking in my library, then pick the most relevant one for me to cite"
    First library search, then item get / item cite

  • "Show me the 10 most recent items that just entered the library"
    Use library recent --count 10

  • "Pull out the PDF annotations and notes for this paper"
    First doctor, then item get / item children / item annotation list

  • "Create an llm-safety workspace for me; I'll be doing Q&A in it later"
    First workspace new / import, then index / query

  • "Save this filter condition as a saved query"
    Use library saved-search create

  • "Download attachment ATCH005"
    Use item download

  • "Preview first, then merge KEEP001 and DUPE001; after confirmation, actually merge"
    First item merge KEEP001 DUPE001, after confirmation then item merge ... --confirm

  • "Why can't I write to Zotero in my current environment?"
    First doctor, if necessary config show

How to understand it when migrating from ref\zotero-cli

  • search -> library search
  • get -> item get
  • annotations -> item annotation list or item pdf --annotations
  • notes -> item note list
  • collections -> collection list
  • collection <id> -> collection items <id>
  • add doi / add url -> item add-doi / item add-url
  • tags -> library tags
  • recent [n] -> library recent --count <n>
  • merge -> item merge; if you first find duplicates and then merge, use library duplicates / duplicates-merge

Old mental model not to migrate back:

  • Do not add a flat top-level alias
  • Do not add --api-base
  • Do not add compact JSON as the default output
  • Do not turn the connector-style search / fetch back into another set of main commands

How to understand it when migrating from ref\zotagent

Remember two things first:

  • Currently zot does not copy zotagent 's flat command surface
  • Currently sync only handles preprint publication status; it has the same name but is not an attachment indexer

Parts already covered or replaceable:

  • DOI / URL / file import:item add-doi / item add-url / item add-file / item create
  • Library-level semantic retrieval:library semantic-index / library semantic-search
  • Single-PDF extraction:item pdf / item fulltext / item outline
  • citation key entry point: first library citekey, then switch to item get / item cite

Not yet completed currently; do not pretend it exists:

  • s2
  • add --s2-paper-id
  • search-in
  • metadata
  • read
  • expand
  • zotagent-style status
  • zotagent-style sync full attachment indexing
  • By title / author / year / publication manually create items in one go

How to handle these requests:

  • search-in / expand: Clearly say there is currently no equivalent command; you can only first item fulltext / item pdf pull the text, then do a second-pass location on the agent side
  • metadata: Explain that there is currently no field-scoped metadata search; at most fall back to library search plus existing filters
  • status: Use doctor + library semantic-status combined to answer; do not treat sync update-status as indexing status
  • s2 / --s2-paper-id: Directly explain that it is not currently implemented; do not fabricate a substitute command
  • zotagent sync: Explain that currently you can only use library semantic-index --fulltext or workspace index as a partial substitute, and the scope is mainly metadata + PDF

Fallback when it fails

  • No zot: in the development repository, fall back to cargo run -q -p zot-cli -- ...
  • No write permission: clearly tell the user it is missing ZOT_API_KEY / ZOT_LIBRARY_ID
  • Without Better BibTeX:library citekey Only the Extra fallback is used
  • Without Pdfium: don't promise fulltext / outline / annotation / text processing after PDF download
  • Without embedding: semantic retrieval descriptions will be degraded; workspace Q&A switches to --mode bm25
  • attach-mode auto No OA PDF found: the item may still be created successfully

Output contract

The final answer should:

  • First answer the user's actual question, rather than pasting commands first
  • Then give key evidence, actions taken, or the reason for failure
  • If it fails, clearly tell the user what is missing and what the next step is
  • By default, do not dump raw JSON; read the envelope first, then relay the useful information

The goal of this skill is not to explain the CLI more completely, but to let agents such as Claude Code and Codex reliably complete Zotero workflows using natural language.