# Paper2read

> Turn a local academic PDF into readable, source-checkable Markdown that restores document structure and highlights the paper's research question, hypothesis, methods, findings, conclusions, limitations, key terms, and explicit reasoning connectors; publish to Notion only when requested. Use when the user wants help actually reading a paper, not merely a summary. Never bypass publisher authentication.

- Skill: `sylviahuang987/paper2read` (Agent Skill, multi-file: 9 files)
- Install (CLI): `npx skillmds@latest add sylviahuang987/paper2read`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sylviahuang987/paper2read/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: sylviahuang987 (https://skillmd.com/u/sylviahuang987)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/sylviahuang987/paper2read

---


# Paper2Read

Create one calm reading surface from a dense paper. Preserve the paper's text,
make its structure and argument easier to follow, and keep machine plumbing out
of the human-facing report.

All paths below are relative to this Skill root. Keep the environment and paper
outputs in the user's active workspace, not in the installed Skill directory.

## Local PDF to reading document

If dependencies are unavailable, prepare the workspace environment:

```bash
python scripts/setup_environment.py --use-uv --install
```

Run the complete pipeline:

```bash
.paper2read/.venv/bin/python scripts/process_paper.py PAPER.pdf \
  --output paper-output \
  --ui-language zh
```

The user-facing result is `paper-output/report.md`. Internal source,
interpretation, metadata, and publishing data belongs under
`paper-output/.paper2read/` and must not be presented as reading material.

Read [references/reading-format.md](references/reading-format.md) when changing
the report or judging its quality.

## Non-negotiable reading boundary

- Preserve the complete extracted source; do not replace it with a summary.
- Keep H1/H2/H3, lists, tables, formulas, figures, captions, and reading order
  where extraction supports them. Crop captioned figures into `images/` and
  place them beside their captions; do not silently reduce a figure to its caption.
- Render the three reading modules as H1, separate them with dividers, and infer
  numbered paper hierarchy (`3` → H2, `3.1` → H3, `3.1.1` → H4).
- Highlight research roles and explicit connectors without rewriting the
  author's claims. For connector categories, change foreground text color only;
  keep the background unchanged and never add colored-square swatches.
- If a research question or hypothesis is not explicit, say `原文未明确陈述` or
  `Not explicitly stated`.
- Use one quiet divider per source page and retain page references on selected
  claims; do not append a page number to every paragraph. Never expose parser names, hashes, item refs,
  confidence percentages, test notes, build status, or implementation commentary
  in `report.md` or the Notion page.
- Do not publish a report that fails validation. Spot-check the title, one
  heading transition, one formula, one embedded figure, one emphasized claim,
  and its page against the PDF. If extracted math is not valid LaTeX, use the
  cropped source formula instead of sending broken text to KaTeX.

## Notion

When the user asks for Notion publishing, read
[references/notion.md](references/notion.md). Fetch the real destination schema,
deduplicate by DOI or title, write the report as the page body, and fetch the
page afterward to verify it. Do not create or modify cloud content without the
user's request.

When no connector is available, deliver `report.md`. Use the REST fallback only
if the user explicitly chooses it and supplies credentials through local
environment variables.

## Access boundary

Accept local PDFs the user is authorized to access. For authenticated publisher
pages, ask for the downloaded PDF. Never bypass paywalls, logins, or access
controls, and never present public metadata or an abstract as a full-paper read.

## Handoff

Lead with the reading document or confirmed Notion page. Mention one remaining
manual action only when necessary; keep validation logs and internal artifacts
out of the user-facing handoff unless the user asks for debugging details.