Zotero Analytical Workflow Skills

A privacy-first Zotero-to-Obsidian literature workflow powered by three installable Codex Skills.

Comment

Inspiration

Researchers often build large literature libraries in Zotero, but the actual reading workflow remains fragmented. Metadata, annotations, cached full text, analytical notes, and an Obsidian knowledge base are usually handled through separate tools and repeated manual steps.

I built this project from my own daily research workflow. I wanted a repeatable way to move from Zotero to structured literature notes without uploading a private research library to a new hosted service. The workflow also needed to distinguish source evidence from model-generated interpretation, prevent accidental overwrites, and remain useful across long-running research projects.

The result is Zotero Analytical Workflow Skills: a privacy-conscious bundle of three installable Codex Skills for literature reading, evidence labeling, and safe collection-scale processing.

What it does

The project connects a user-controlled workflow:

Zotero → Codex / GPT-5.6 → Obsidian

It is organized into three cooperating Skills:

  • zotero-data-fetcher retrieves source material by Zotero item key or title and organizes metadata, annotations, cached text, and evidence-quality information.
  • zotero-analytical-writer instructs Codex to transform the supplied source material into structured, evidence-aware analytical notes.
  • zotero-collection-manager coordinates collection queues, resumable processing, first-pass imports, deep-reading upgrades, safe writes, and evidence-schema audits.

Deterministic Python modules handle extraction, queueing, template parsing, metadata interoperability, dry-run plans, and write gates. Semantic interpretation is performed by Codex while executing the Skills.

The workflow is designed to fail safely:

  • file-changing operations default to dry-run;
  • writes require an explicit --write flag;
  • replacing an existing Markdown note requires --overwrite;
  • the note renderer fails closed when its authorized template is missing or malformed;
  • generated notes retain evidence labels and still require human review before citation.

The public repository contains no private Zotero database, PDF, annotation, Obsidian vault, research note, credential, processing log, or machine-specific private path.

How we built it

The three core Skills and the daily Zotero-to-Obsidian workflow existed before OpenAI Build Week 2026. During Build Week, the project was meaningfully extended and prepared as a safe public release.

Codex with GPT-5.6 was used to:

  1. inspect the real installed Skill bundle and compare it with the public repository;
  2. define bounded implementation and verification gates;
  3. integrate upstream permission, attribution, and mixed-licensing boundaries;
  4. audit the repository for credentials, private paths, research data, and prohibited artifacts;
  5. reconstruct block-level provenance across possible GitHub sources;
  6. independently rewrite code blocks whose origin or licensing could not be resolved;
  7. build deterministic offline safety tests;
  8. synchronize the accepted rewrite back into the real local Skill installation;
  9. validate public/local identity, privacy, licensing, and judge readiness;
  10. prepare the final release, documentation, and demonstration package.

The final implementation uses Python 3.11 and standard-library-first modules. It interoperates with Zotero and optional public scholarly metadata services such as Crossref, OpenAlex, and Unpaywall. Normal use does not require a separate OpenAI API key: GPT-5.6 is used through Codex when the Skills are executed.

Challenges we ran into

The hardest challenge was not simply adding features. It was making a real personal research workflow safe and defensible as a public project.

First, the installed daily-use scripts contained machine-specific paths and configuration differences. We needed to preserve actual behavior without exposing private local information.

Second, the project had a mixed provenance history. Some fixed Skill and template files were adapted from an upstream repository, while other code had evolved through Codex-assisted development and references to public GitHub projects. A public repository is not automatically reusable merely because it is visible, so every material block had to be classified by source and license.

Several blocks could not be assigned to a sufficiently documented source. Instead of hiding that uncertainty or adding attribution without permission, we isolated their required behavior, created synthetic tests, and independently rewrote them under separated analysis and implementation contexts.

Another challenge was keeping the project testable without exposing a real Zotero library or Obsidian vault. We solved this with mocked scholarly metadata responses, synthetic templates, fail-closed tests, safe CLI checks, and 24 offline unit tests.

Accomplishments that we're proud of

  • Released a real daily-use bundle of three installable Codex Skills rather than a disconnected prototype.
  • Preserved a local-first architecture in which research materials remain under the user's control.
  • Added explicit dry-run, write, overwrite, template-validation, and evidence-labeling safety boundaries.
  • Completed block-level provenance, licensing, privacy, and reachable-history audits.
  • Independently rewrote all unresolved functional blocks instead of retaining uncertain third-party expression.
  • Added agent metadata so the three Skills are easier to discover and invoke.
  • Created 24 deterministic offline tests that judges can run without Zotero, Obsidian, private data, or an API key.
  • Verified the final public release and the real installed Skill implementation at the file-hash level.
  • Preserved transparent upstream attribution and a documented mixed-licensing boundary.

What we learned

We learned that a reliable AI-assisted research workflow is not defined only by the quality of generated text.

It also needs:

  • clear separation between source evidence and interpretation;
  • deterministic safety checks around model-driven work;
  • explicit human-review boundaries;
  • privacy-aware local execution;
  • reproducible tests;
  • careful provenance and licensing records;
  • fail-closed behavior when required inputs are missing.

Codex and GPT-5.6 were most valuable not as a one-shot code generator, but as collaborators across planning, auditing, refactoring, testing, documentation, and controlled synchronization. The project became stronger when uncertain claims were treated as blockers rather than being silently ignored.

What's next for Zotero Analytical Workflow Skills

The next priorities are:

  • improve cross-platform path and Zotero-profile support beyond the current Windows-oriented setup;
  • add more synthetic test fixtures for different literature and metadata conditions;
  • simplify installation and configuration while preserving local privacy;
  • expand documentation for students and researchers who are new to Codex Skills;
  • improve evidence-aware review and migration tools without weakening human verification;
  • continue maintaining transparent provenance and license boundaries as the bundle evolves.

The long-term goal is not to replace researchers' judgment. It is to make literature reading more repeatable, traceable, private, and easier to review.

Built With

Share this project:

Updates