# Zotero workflow skills: turning papers into a structured research vault

> This repository is a set of agent skills and small local tools for one job: moving a paper out of Zotero, through PDF conversion, into a Markdown vault of analytical notes, fulltext, and knowledge pages. The tools are Python 3.11 with nothing but the standard library, the vault layout is fixed and documented, and every script that touches your data is read-only by design.

**cheneternity/Zotero-Analytical-Workflow-Skills** — 主要是用于zotero论文导入obsidian的转换和管理，包括论文精读和精读模板

- Repository: https://github.com/cheneternity/Zotero-Analytical-Workflow-Skills
- Stars: 697 · Forks: 51
- Language: Python
- License: not declared
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/cheneternity-zotero-analytical-workflow-skills

## Five stages, and a repository that owns the whole pipeline

The project describes itself as a portable set of agent skills and local tools for one workflow, and it writes that workflow as a single line.

```text
Zotero → MinerU Fulltext → Analytical Notes → Knowledge → Literature Retrieval
```

Read left to right, that is the lifecycle of a paper in this system. It starts as a library item in Zotero, becomes a converted fulltext document, becomes a note you wrote, becomes a claim or a gap recorded in a knowledge section, and finally becomes something you can retrieve an answer from later.

The repository is described as the canonical source for the complete workflow and for the literature retrieval skill in particular, and the design goal is portability. New vault content uses one layout, with a knowledge directory, a vault directory, a fulltext directory, and a templates directory, and the documentation makes a point of it: no tool requires the author's drive letters or private scripts. That is a small sentence with a large meaning, because it is the difference between a workflow you can adopt and one that only works on the machine where it was written.

The requirements are deliberately loose. Python 3.11 or newer, and the bundled tools use only the standard library, so there is nothing to install beyond a virtual environment. Zotero Desktop is needed only if you want to read the local Zotero database or its attachments. MinerU, the PDF conversion tool, is optional and installed separately. Obsidian is optional, since the output is Markdown and can be edited in anything. The Dataview plugin is optional for people whose own index pages use it. And ripgrep is optional, because the skills can fall back on whatever project search the agent has.

The repository also states what it does not contain: no Zotero database, no PDF, no private vault content, no API package, and no credential. Everything you need is in the tree, and everything private stays on your machine.

## The vault layout, and the rule about old paths

The canonical layout is the heart of the design, because every script agrees on it.

```text
<VAULT_ROOT>/
├── 01knowledge/
│   ├── index.md
│   ├── log.md
│   ├── _index/
│   └── .meta/                 # claims and gaps; machine metadata only
├── 02vault/
│   ├── _index/                 # four literature indexes
│   └── <collection>/<paper>.md
├── 03fulltext/
│   └── <collection>/<zotero_key>.md
```

The templates directory is listed last, and the numbered prefixes are the load bearing part. They sort into the right order in a file listing, and they make the one rule easy to state: new analytical notes go only into the vault directory, and new fulltext goes only into the fulltext directory. Obsidian links use forward slashes and paths relative to the vault root, so a link looks the same on every operating system.

The knowledge directory is the part that is not a document store. It holds an index, a log, its own index directory, and a metadata directory whose comment says claims and gaps, machine metadata only. So the knowledge pages are for the things you concluded, and the metadata directory is where the machine keeps track of them.

The templates directory, whose name is written in Chinese, carries a paper close reading template and a subdirectory of six canonical knowledge templates, which is what the note writing step fills in.

And then the rule that catches people out. The historical directories, including the ones for notes, the paper library, fulltext, and knowledge, along with root level indexes, are migration inputs rather than new write destinations. The tools will read them, and the validators will even fall back to reading the old fulltext path, but nothing new is written there. That is a deliberate choice, and it is the reason the migration section tells you to back up the vault and confirm the identity and the links of each file before moving it.

## Reading Zotero without writing to it

The first tool in the chain fetches the metadata for one library item, and the design decision that matters is the read-only guarantee.

```sh
python tools/zotero_readonly_fetch.py --key ABCD1234
```

The helper opens Zotero's local SQLite database in read-only mode and emits JSON. The output carries the parent item's key, the key of the PDF attachment, the title, the authors, the year, the DOI, the collections the item is in, and the annotations, plus the path to the PDF when it can be resolved and the path to the cached fulltext when that file exists.

The annotations are the part worth pausing on, because they are the work a reader has already done inside Zotero, and they come out of the database as data rather than as something you have to re-find by eye.

The tool never edits the Zotero database, and the documentation is explicit that the read-only mode is the mechanism rather than a promise. It also discovers the usual data directories on Windows, macOS, and Linux, and takes a data directory argument for a profile somewhere else.

The failure case is handled explicitly too. A database that is locked, because Zotero is syncing or upgrading, returns a clear failure rather than a partial result, and the guidance is to retry once Zotero has finished or to use the Zotero API or an export instead. That is a well designed answer to the question that every tool reading a live database has to answer.

## Converting a PDF, and why nothing is promoted for you

The conversion step turns a PDF into Markdown, and the runner around the converter is careful in several specific ways.

```sh
python tools/run_mineru_production.py --input "E:\Papers\paper.pdf" --output "E:\ResearchVault\_staging\mineru\ABCD1234-run1"
```

The output directory must not already exist, which means a rerun cannot silently overwrite a conversion you already have. The runner preserves the source PDF and writes a hashed working copy, so the input is never touched, and it logs the exact MinerU command it ran, which is what you want when a conversion fails. A timeout is enforced, so a converter that hangs does not hang with it.

And success is reported only when MinerU exits cleanly and produces non-empty Markdown. Both conditions, not one, because a converter that exits zero and writes nothing is a common failure and it is the one that is easiest to miss.

The important part is what the runner does not do. It does not promote its output into the vault. The staged result stays in the staging directory, you look at it, and then the fulltext archiver skill creates the canonical file in the fulltext directory. That separation is the difference between a conversion step and an archiving step, and it is why a bad conversion cannot quietly become part of your research base.

There is platform detail here too. Conversion should work on Windows, macOS, and Linux as long as the selected MinerU executable supports that platform, and on Windows the executable and the staging path have to be reachable by the current account. There is also a specific warning about a MinerU build that cannot handle non-ASCII paths, with the instruction to choose an ASCII-only archive root if you hit it.

## The validators, and the read-only checker

Three tools in the repository are read-only, and they are the ones that let you trust the rest.

The environment checker verifies the setup.

```sh
python tools/check_environment.py
```

It reports on the things the workflow needs, and it distinguishes between two kinds of missing thing. Zotero, MinerU, and ripgrep are optional capabilities, so when they are not configured they show a warning. Missing Python, missing vault folders, and missing bundled tools show a failure. So a machine without a PDF converter is a machine that can still read Zotero and write notes, and the checker says so rather than refusing to start.

Then there are the two validators.

```sh
python skills/research-vault-knowledge-maintainer/scripts/validate_research_vault_knowledge.py --vault "E:\ResearchVault"
python tools/validate_research_vault_literature_links.py --vault "E:\ResearchVault"
```

Both take any vault root and change nothing. The knowledge validator checks the frozen page schema and the source links, which is the machine check that a knowledge page still has the structure the retrieval skill expects and still points at the evidence it came from. The link validator checks the Zotero keys and the PDF keys, the paths between a note and its fulltext, the canonical placement of both, and the fallback to reading the old fulltext directory.

Together they cover the two things that actually break in a workflow like this: a page that has drifted from the schema, and a link that points at a file which is not where the layout says it should be. Both are the kind of problem that a human notices months later, and a script notices immediately.

## Configuration, overrides, and the migration rules

Configuration is a TOML file with a paths section, and the example is written with forward slashes so it is portable between operating systems.

```toml
[paths]
vault_root = "E:/ResearchVault"
zotero_data_dir = "C:/Users/alex/Zotero"
mineru_executable = "C:/Tools/MinerU/mineru.exe"
archive_root = "E:/ResearchVault/_staging/mineru"
```

The initializer creates that file only if it does not already exist, and the local file is git-ignored, with the documentation saying plainly that you should not commit it. A configuration file with absolute paths to somebody's home directory is exactly the thing that should not be in version control.

Every path can be overridden per process with an environment variable, the vault root, the Zotero data directory, the MinerU executable, and the archive root, and a separate variable selects a different configuration file altogether. Command line flags override the configuration where a tool offers them, so there is a clear order of precedence: flag, then environment, then file, then default.

The migration section is the last word, and it is the part to follow carefully. The tools never reorganise an existing vault automatically. You back up the vault, and then you move or copy the old files yourself, only after confirming their identity and their links. The mapping is given explicitly: the old paper library and note directories move to the vault directory, the old fulltext files move to the fulltext directory keeping the Zotero key as the file name, the root literature indexes move into the vault index directory, and the old knowledge directory moves to the knowledge directory, after reviewing the metadata sidecars and the links that go with them.

That last step is the one with judgement in it, and the documentation asks for the review rather than automating it, which is the right call for the directory where your conclusions live.

## Conclusion

This workflow fits a researcher who keeps their library in Zotero and their writing in an Obsidian vault, and who wants the conversion, the note structure, and the retrieval to be reproducible instead of a pile of manual steps. It does not fit a researcher who wants the two tools to merge into one, since the separation is the point, and it does not fit a Windows user whose paths contain characters the PDF converter cannot handle. Verify first that the Zotero database is not locked by a running Zotero during a fetch, that the archive root is on a path the converter can write to, and that the two validators pass on your existing vault before you start writing new pages, since they are the only thing standing between a migration mistake and a broken link.

## FAQ

### What does the Zotero Analytical Workflow Skills repository do?

It provides agent skills and local tools for a five stage workflow that runs from Zotero, through PDF conversion with MinerU, into analytical notes, then knowledge pages, and finally literature retrieval. The repository is the canonical source for the whole workflow and for the retrieval skill.

### What are the requirements for the Zotero workflow?

Python 3.11 or newer, and the bundled tools use only the standard library. Zotero Desktop is needed to read the local database or attachments, and MinerU, Obsidian, the Dataview plugin, and ripgrep are all optional. The repository ships no database, no PDF, no private vault content, and no credential.

### Does the Zotero fetch tool modify my library?

No. It opens the local SQLite database in read-only mode and emits JSON with the parent key, the PDF attachment key, the title, the authors, the year, the DOI, the collections, the annotations, and the paths to the PDF and the cached fulltext when they can be resolved. A locked database fails clearly rather than returning a partial result.

### Why does the PDF conversion output not end up in the vault automatically?

The runner preserves the source PDF, writes a hashed working copy into the staging directory, logs the MinerU command, enforces a timeout, and reports success only when the converter exits cleanly and produces non-empty Markdown. It deliberately does not promote the result, so you inspect it and then use the fulltext archiver skill to create the canonical file.

### How do I migrate a vault from the old layout?

Back it up first, then move the files yourself once you have confirmed their identity and links. The old paper library and note folders move into the vault directory, the old fulltext files move into the fulltext directory keeping the Zotero key as the file name, the root indexes move into the vault index directory, and the old knowledge directory moves into the knowledge directory after reviewing the metadata sidecars.

## Sources

- [cheneternity/Zotero-Analytical-Workflow-Skills on GitHub](https://github.com/cheneternity/Zotero-Analytical-Workflow-Skills)
- [Issues](https://github.com/cheneternity/Zotero-Analytical-Workflow-Skills/issues)
- [README](https://github.com/cheneternity/Zotero-Analytical-Workflow-Skills/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cheneternity-zotero-analytical-workflow-skills