Do you often run into this situation: you want to study a classic paper carefully, but the hardest part is no longer reading it — it is turning that reading into usable notes? The real time sink usually looks like this:

• jumping back and forth between PDFs, Zotero, web pages, and your note app
• manually organizing metadata, abstracts, figures, and the method backbone
• understanding part of the paper, but still spending a long time turning that understanding into structured notes
• ending up with a note that looks complete but is not something you actually want to revisit later

DeepPaperNote is built for exactly that layer of repetitive, mechanical, but very expensive work. It takes over the gathering, structuring, figure placement, and note production work so you can keep your attention on actual thinking.

DeepPaperNote is a skill for deep paper reading. The same core skill can be used from Claude Code and Codex. It cares about a harder set of questions:

• What problem is this paper actually solving?
• How does the mechanism really work?
• Are the key equations, experiments, and figure context preserved?
• Does the final note become something worth keeping in your long-term knowledge base?

[!tip]
If you already have an Obsidian or Zotero workflow, DeepPaperNote automates the most tedious parts of evidence gathering, structuring, and note production.

🎯 What problems does it solve?

In one sentence:

DeepPaperNote is a paper-reading-note workflow, not a paper-summary generator.

✨ How does it do that?

DeepPaperNote does not achieve higher note quality by simply rewriting the abstract in smoother prose. It raises note quality through a few workflow rules:

👀 Who It Is For

🚀 Quick Start

1) Install DeepPaperNote into your agent skill directory

DeepPaperNote supports both Claude Code and Codex.

npx Skills (Recommended)

For most users, install directly with npx:

npx skills add 917Dhj/DeepPaperNote

This command installs to the shared .agents/skills directory by default. Skills in that directory can be recognized and used by Codex and most other agents. If you also want to use DeepPaperNote in Claude Code, choose Claude Code in the Additional agents prompt.

You can also install for a specific agent directly:

npx skills add 917Dhj/DeepPaperNote -a codex
npx skills add 917Dhj/DeepPaperNote -a claude-code

Manual install

If you prefer the manual path, download the latest release zip and extract it.

For Codex, place the extracted DeepPaperNote folder into:

~/.codex/skills/DeepPaperNote

For Claude Code, place the extracted DeepPaperNote folder into:

~/.claude/skills/DeepPaperNote

You can also clone the source repository directly:

git clone https://github.com/917Dhj/DeepPaperNote.git ~/.codex/skills/DeepPaperNote
git clone https://github.com/917Dhj/DeepPaperNote.git ~/.claude/skills/DeepPaperNote

After installation, restart your agent so the skill is loaded.

2) Install the core Python dependency

Before your first real paper run, install the most important Python dependency:

python3 -m pip install PyMuPDF

Why this step matters:

• DeepPaperNote reads PDFs through PyMuPDF
• if PyMuPDF is missing, the core PDF extraction pipeline will not work

3) Start using it immediately

After that, just hand a paper to the agent. A title, DOI, URL, arXiv ID, or local PDF all work. Prompts like these are enough:

Typical prompts:

• Generate a deep-reading note for this paper: Attention Is All You Need
• Turn this paper into an Obsidian note: https://arxiv.org/abs/1706.03762
• Read this PDF and produce a Markdown note with figure context
• Use DeepPaperNote on this paper: 10.48550/arXiv.1706.03762

By default, DeepPaperNote writes the note in Chinese. At the moment, Chinese is the only note language that can fully benefit from the skill's current writing and linting rules. If you need English notes, please stay tuned for a future update.

By default, DeepPaperNote will:

• resolve the paper identity
• gather metadata and PDF evidence
• plan figure placeholders and attempt high-confidence figure replacement
• generate the final Markdown note
• save it into Obsidian when configured, or ask for your vault path before falling back to the current directory

4) You do not need perfect setup on day one

You can try DeepPaperNote even if you have not finished configuring Obsidian, Zotero, or OCR yet.

If you want the Python dependencies for local development:

python3 -m pip install -e .

If you want to check the environment first, you can also ask the agent with short requests such as:

• Please check whether DeepPaperNote is ready on this machine
• 查看 deeppapernote 的可用情况
• deeppapernote 有什么功能

🔧 Configuration (works out of the box, improves with setup)

Once you have PyMuPDF installed, you're ready to start generating notes with DeepPaperNote right away. The configurations outlined below are extensions of the core features, designed to help you seamlessly integrate the generated notes into your actual research workflow.

• if no Obsidian vault is configured, it can still save notes into the current working directory
• if you want an Obsidian-native long-term workflow, you should configure your vault path
• everything else in this section is optional and improves specific workflows

Core setup: point DeepPaperNote to your Obsidian vault

The cleanest setup is:

export DEEPPAPERNOTE_OBSIDIAN_VAULT="/absolute/path/to/your/Obsidian_Documents"

If you want your agent to keep seeing this default configuration in future terminal sessions:

• on macOS / Linux, add it to your shell config such as ~/.zshrc, then reload your shell (or restart the agent):

echo 'export DEEPPAPERNOTE_OBSIDIAN_VAULT="/absolute/path/to/your/Obsidian_Documents"' >> ~/.zshrc
source ~/.zshrc

• on Windows PowerShell, persist it as a user environment variable and then restart your terminal:

setx DEEPPAPERNOTE_OBSIDIAN_VAULT "C:\Users\YourName\Documents\Obsidian_Documents"

export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"
export DEEPPAPERNOTE_OUTPUT_DIR="tmp/DeepPaperNote"

echo 'export DEEPPAPERNOTE_PAPERS_DIR="Research/Papers"' >> ~/.zshrc
source ~/.zshrc

setx DEEPPAPERNOTE_PAPERS_DIR "Research/Papers"

export DEEPPAPERNOTE_SEMANTIC_SCHOLAR_API_KEY="your_api_key"

brew install tesseract
python3 -m pip install --user pytesseract Pillow

winget install UB-Mannheim.TesseractOCR
py -m pip install --user pytesseract Pillow

py -m pip install --user pytesseract Pillow

tesseract --version
python3 -c "import pytesseract, PIL; print('python_ok')"
python3 -c "import pytesseract; print(pytesseract.get_tesseract_version())"

📝 Changelog Preview

For release-level updates, see CHANGELOG.md.

⚙️ Workflow

The default path is:

1. resolve the paper identity
2. collect metadata
3. fetch a PDF or enough full-text evidence
4. extract evidence
5. extract PDF image assets
6. plan figure positions
7. build a synthesis bundle
8. let the model write the note
9. lint the final note
10. perform the final readability review and write it into Obsidian

Core principle:

• scripts gather evidence
• the model understands and writes
• linting and final readability review are the final gates before saving

Related docs:

• Workflow
• Architecture
• Model Synthesis

🖼️ Figure Strategy

When figure handling breaks down, the quality of the whole note usually drops with it.

That is why DeepPaperNote uses a more structure-first, placeholder-first figure strategy:

• keep the semantic place of important figures inside the note
• avoid breaking the reading flow when extraction is incomplete
• show which figure belonged there and why it matters, so you can later revisit the paper and add the image yourself if needed

Recommended placeholder format:

> [!figure] Fig. 3 Data Distribution and Quality Evaluation
> Suggested location: Data and task definition
> Why here: This figure combines sample composition, conversation-length statistics, and expert quality checks, making it one of the most important figures for understanding the data boundaries.
> Current status: Placeholder kept; current extraction only recovered partial subpanels and cannot yet reconstruct the full original figure reliably.

In other words, DeepPaperNote prioritizes:

note completeness and readability over forcing every figure to be extracted automatically at any cost

See figure placement rules.

✅ Quality Bar

DeepPaperNote has a concrete bar for what counts as a usable note.

The final note should:

• clearly separate the research question and the task definition
• explain the real method or analytical pipeline
• capture the numbers that actually matter
• point out where the paper is easiest to misread
• include at least one honest limitation
• use real heading structure: #, ##, ###
• avoid mixed Chinese-English prose in the body

If the evidence is not strong enough, the workflow should degrade gracefully or fail instead of pretending that a deep reading note is complete.

Related docs:

• Evidence First
• Deep Analysis
• Note Quality
• Final Writing
• Figure Placement

🗂️ Repository Layout

DeepPaperNote/
├── SKILL.md
├── README.md
├── README.zh-CN.md
├── CHANGELOG.md
├── LICENSE
├── pyproject.toml
├── agents/
│   └── openai.yaml
├── assets/
│   ├── hero-academic.svg
│   ├── usage-example.png
│   └── note_template.md
├── references/
│   ├── architecture.md
│   ├── deep-analysis.md
│   ├── evidence-first.md
│   ├── figure-placement.md
│   ├── final-writing.md
│   ├── metadata-sources.md
│   ├── model-synthesis.md
│   ├── note-quality.md
│   ├── obsidian-format.md
│   ├── paper-types.md
│   └── workflow.md
└── scripts/
    ├── build_synthesis_bundle.py
    ├── check_environment.py
    ├── collect_metadata.py
    ├── common.py
    ├── contracts.py
    ├── create_input_record.py
    ├── extract_evidence.py
    ├── extract_pdf_assets.py
    ├── fetch_pdf.py
    ├── lint_note.py
    ├── locate_zotero_attachment.py
    ├── materialize_figure_asset.py
    ├── plan_figures.py
    ├── resolve_paper.py
    ├── run_pipeline.py
    └── write_obsidian_note.py

🧰 Recommended Environment

🧭 Design Principles

The core judgment behind DeepPaperNote is simple:

1. A good paper note is not just a paragraph-style summary.

A useful note should help you understand:

• how the method works
• where the evidence comes from
• what the experiments actually show
• what the real boundaries and limitations are

2. The goal of paper reading is a reusable research asset.

Not just “I kind of get it right now,” but something you can revisit, cite, and build on later.

3. Note generation should serve a real research workflow.

That is why it is designed to fit naturally with:

• Obsidian
• Zotero
• local paper management
• long-term knowledge-base building

🧭 Inspirations

DeepPaperNote was influenced by projects that take paper reading, evidence extraction, and note generation seriously, especially:

• heleninsights-dot/phd-deepread-workflow
• juliye2025/evil-read-arxiv

Star History

📄 License

This project is licensed under the MIT License.