The Problem

Reading a research paper deeply is one thing; turning that reading into structured, reusable notes is another. The mechanical work—collecting metadata, extracting figures, organizing evidence, and formatting output—consumes hours that could go to actual understanding. DeepPaperNote targets that gap: it automates the gathering and structuring so the reader can focus on the mechanism and results.

What This Does

DeepPaperNote is an agent skill, not a standalone application. It defines a workflow that Claude Code, Codex, or similar agents execute to produce an Obsidian-ready markdown note from a single paper. The SKILL.md file at the root defines the skill contract, while scripts/run_pipeline.py orchestrates the actual work.

The pipeline is decomposed into focused steps: scripts/resolve_paper.py finds the source, scripts/fetch_pdf.py downloads it, scripts/extract_source_text.py pulls the text, scripts/extract_evidence.py and scripts/collect_metadata.py gather content, and scripts/write_obsidian_note.py produces the final note. A references/ directory holds domain rules—evidence-first.md, figure-placement.md, model-synthesis.md—that constrain how the note is structured. The site/ directory is a separate Astro-based documentation homepage (7,052 files, mostly node_modules).

How It Is Wired

Execution starts at scripts/run_pipeline.py, which sequences the other scripts. The pipeline is linear: resolve → fetch → extract → collect → synthesize → write. Each script is a standalone Python module with no internal imports between them (the import graph shows 40 modules, 0 edges—all isolated). The pipeline calls scripts/locate_zotero_attachment.py to prefer local Zotero records when available, and scripts/extract_pdf_assets.py to pull figures into a local images/ directory. Outbound calls exist in scripts/common.py (2 requests with no timeout). The system touches the filesystem heavily—PDFs, extracted text, images, and the final note—but has no database. The widest blast radius is scripts/common.py (2,156 lines), which everything shares.

How To Use It

Setup: The repo uses pyproject.toml for Python dependencies. Install with pip install -e . or uv sync. The site/ directory uses npm (lockfile present), but that's for the documentation site, not the skill itself.

Configuration: No environment variables are documented. The workflow relies on the agent reading SKILL.md and the references/*.md files for behavior rules. Zotero integration is optional and detected at runtime.

Running it: This is an agent skill, so you don't invoke a CLI directly. You load SKILL.md into your agent (Claude Code, Codex, etc.) and instruct it to process a paper. The agent then executes the pipeline scripts.

# Clone and install
git clone https://github.com/moses-y/DeepPaperNote
cd DeepPaperNote
pip install -e .

# Then instruct your agent: "Use the DeepPaperNote skill to read this paper: <path or DOI>"

Real-World Use

A researcher with a Zotero library and Obsidian vault wants to study a foundational paper. They point their agent at the DOI. The agent runs resolve_paper.py → locate_zotero_attachment.py (finds the local PDF) → extract_source_text.py → collect_metadata.py → extract_evidence.py → write_obsidian_note.py. The output: a folder in the Obsidian vault with a markdown note, local figures, and structured metadata—mechanism breakdown, key equations, figure context, limitations.

Code Health & Issues

Static analysis (not opinion) found 36 issues: 3 high, 33 medium.

  • High - Duplicated code blocks - 93 repeated 6-line blocks across 15 files (scripts/contracts.py, scripts/extract_evidence.py, tests/). Extract shared helpers.
  • High - Oversized files - scripts/common.py at 2,156 lines, plus scripts/lint_note.py and scripts/extract_evidence.py. Split by responsibility.
  • High - Committed node_modules - 7,046 files under site/node_modules are in git. The running code was never resolved from a manifest. Gitignore and reinstall from lockfile.
  • High - Missing lockfile for pyproject.toml - unlocked ranges mean shipped code can differ from tested code. Commit a lockfile.
  • Medium - File opens without context manager (10 instances), broad exception handling (6), deep nesting (11), high branching density in scripts/locate_zotero_attachment.py (27 branches/89 lines), no outbound request timeouts, no dependency scan in CI, no Dependabot config, large binaries committed (15.3MB dylib), no persist-credentials: false on checkout.
  • Low - No job timeouts in CI, missing .editorconfig/.gitattributes.

Tests exist (175 files) and Travis CI is configured. No secrets committed.

The Bottom Line

The skill concept is sound—automating the mechanical layer of paper reading is genuinely useful, and the references/ rules show careful thought about note quality. The Python scripts are the real product; the site/ directory is incidental documentation. The maintenance burden is real: oversized files, duplicated logic, and no lockfile make changes risky. Worth using if you already live in Obsidian and want structured notes without the manual labor, but expect to clean up the scripts before extending them.