Skip to content
Back to search

paper-guide

MarketplaceWorks with Claude CodeGitHub

Self-hosted marketplace for the paper-guide plugin.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/leanderlxz--paper-guide/badge.svg)](/listings/leanderlxz--paper-guide)

HTML

<a href="/listings/leanderlxz--paper-guide"><img src="/api/listings/leanderlxz--paper-guide/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install the Plugin

In Claude Code:

/plugin marketplace add https://github.com/LeanderLXZ/paper-guide.git
/plugin install paper-guide@paper-guide

2. Ask for a Guide

/paper-guide Turn ./papers/my-paper.pdf into a complete Chinese reading guide.
/paper-guide 把 ./papers/my-paper.pdf 做成完整的论文导读

`/paper-guide` is the short form; the full name is `/paper-guide:paper-guide`, which you can use if another command already claims `/paper-guide`. You can also just ask for a paper guide or 论文导读 — Claude loads the skill on its own.

3. What Claude Does

1. **Inspects the source** — the exact PDF and its SHA-256, page count, printed page labels, figures, tables and rotated pages. It looks at the rendered pages, not only at extracted text. 2. **Authors the content** into an editable `guide.json` — research stages, the English source and Chinese translation page by page, a Chinese note for every page, and the empirical setup (data, periods, splits, baselines) when it matters. 3. **Crops the original figures and builds** one self-contained HTML. 4. **Validates** structure and provenance against the PDF and, when a browser is available, exercises the reader in Chromium. 5. **Delivers** the HTML path, the source identity, the actual coverage and any unresolved pages. `guide.json` and the cropped images stay in a working directory, so the guide can be continued or edited later.

Long papers are written in batches and resume from saved coverage. Edits change only what you ask for — a wording fix doesn't regenerate the paper:

/paper-guide Continue the guide in ./work — pages 18–40 are still missing.
/paper-guide In ./guides/Paper_Guide.html, the AI note on page 7 misstates the sample size. Fix only that.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 28 lines
  1. {
  2. "name": "paper-guide",
  3. "description": "Self-hosted marketplace for the paper-guide plugin.",
  4. "owner": {
  5. "name": "LeanderLXZ",
  6. "email": "leander.lxz@gmail.com"
  7. },
  8. "plugins": [
  9. {
  10. "name": "paper-guide",
  11. "description": "Turn an English research paper into a complete offline Chinese reading guide: page-aligned translation, English source, original PDF and figures, a research roadmap and page-level Chinese AI notes in one HTML file.",
  12. "author": {
  13. "name": "LeanderLXZ",
  14. "email": "leander.lxz@gmail.com"
  15. },
  16. "category": "productivity",
  17. "source": "./",
  18. "homepage": "https://github.com/LeanderLXZ/paper-guide",
  19. "license": "MIT",
  20. "keywords": [
  21. "claude-code",
  22. "paper-reading",
  23. "translation",
  24. "pdf"
  25. ]
  26. }
  27. ]
  28. }
README.md · README · 240 lines
  1. # Paper Guide
  2. <p align="left">
  3. <img src="https://img.shields.io/badge/version-v1.0.0-blue" alt="Version">
  4. <img src="https://img.shields.io/badge/Claude%20Code-plugin-7857ED" alt="Claude Code Plugin">
  5. <a href="LICENSE"><img src="https://img.shields.io/github/license/LeanderLXZ/paper-guide?color=blue" alt="License: MIT"></a>
  6. </p>
  7. **Turn an English research paper into a complete, offline Chinese reading
  8. guide — one HTML file you can open anywhere.** Give Claude a PDF. It reads
  9. every page, writes a page-aligned Chinese translation and a Chinese
  10. explanation for each page, keeps the original figures and the original PDF,
  11. and packages everything into a single self-contained reader with an
  12. interactive map of the paper's argument.
  13. - 📖 **Three reading modes** — Chinese → English → 中文/英文 side by side,
  14. over one page-aligned source/translation pair.
  15. - 🤖 **Page-level AI notes** — a Chinese note card beside every page (summary,
  16. key concepts, how to read its figures and tables), toggled in any mode.
  17. - 🗺️ **Research roadmap** — the paper's own progression (question → method →
  18. evidence → robustness → limitations) as stages and numbered steps, each
  19. linked to its physical PDF page.
  20. - 🖼️ **Original figures, not redraws** — figures and tables cropped from the
  21. PDF, rotated upright and zoomable, with Chinese explanations kept outside
  22. the image.
  23. - 📦 **Fully offline** — styles, scripts, images and a byte-identical copy of
  24. the PDF are embedded; no network is needed to read.
  25. - 🔍 **Auditable provenance** — the file records the PDF's SHA-256, the
  26. physical/printed page mapping, each page's verification status and every
  27. crop box.
  28. ### 中文简介
  29. 把英文论文 PDF 变成一份**可离线打开的中文导读 HTML**:逐页中文译文、恢复成自然段落的英文原文、原版 PDF 与原图、交互式「研究路线图」,以及每页一张中文 AI 解读卡。阅读模式在 中文 / 英文 / 中文/英文 对照 之间切换,AI 解读可随时开关;所有内容都内嵌在一个 HTML 文件里,断网也能读。
  30. <p align="center">
  31. <a href="#-quick-start">Quick Start</a> ·
  32. <a href="#-the-reader">The Reader</a> ·
  33. <a href="#%EF%B8%8F-bundled-scripts">Bundled Scripts</a> ·
  34. <a href="#-installation">Installation</a> ·
  35. <a href="#%EF%B8%8F-scope-and-responsibility">Scope</a>
  36. </p>
  37. ---
  38. ## 🚀 Quick Start
  39. ### 1. Install the Plugin
  40. In Claude Code:
  41. ```
  42. /plugin marketplace add https://github.com/LeanderLXZ/paper-guide.git
  43. /plugin install paper-guide@paper-guide
  44. ```
  45. ### 2. Ask for a Guide
  46. ```
  47. /paper-guide Turn ./papers/my-paper.pdf into a complete Chinese reading guide.
  48. ```
  49. ```
  50. /paper-guide 把 ./papers/my-paper.pdf 做成完整的论文导读
  51. ```
  52. `/paper-guide` is the short form; the full name is `/paper-guide:paper-guide`,
  53. which you can use if another command already claims `/paper-guide`. You can
  54. also just ask for a paper guide or 论文导读 — Claude loads the skill on its own.
  55. ### 3. What Claude Does
  56. 1. **Inspects the source** — the exact PDF and its SHA-256, page count,
  57. printed page labels, figures, tables and rotated pages. It looks at the
  58. rendered pages, not only at extracted text.
  59. 2. **Authors the content** into an editable `guide.json` — research stages,
  60. the English source and Chinese translation page by page, a Chinese note
  61. for every page, and the empirical setup (data, periods, splits, baselines)
  62. when it matters.
  63. 3. **Crops the original figures and builds** one self-contained HTML.
  64. 4. **Validates** structure and provenance against the PDF and, when a browser
  65. is available, exercises the reader in Chromium.
  66. 5. **Delivers** the HTML path, the source identity, the actual coverage and
  67. any unresolved pages. `guide.json` and the cropped images stay in a working
  68. directory, so the guide can be continued or edited later.
  69. Long papers are written in batches and resume from saved coverage. Edits
  70. change only what you ask for — a wording fix doesn't regenerate the paper:
  71. ```
  72. /paper-guide Continue the guide in ./work — pages 18–40 are still missing.
  73. /paper-guide In ./guides/Paper_Guide.html, the AI note on page 7 misstates the sample size. Fix only that.
  74. ```
  75. ---
  76. ## 📘 The Reader
  77. | Feature | Behavior |
  78. |---|---|
  79. | **Reading modes** | Chinese (default) → English → 中文/英文, cycled from one control |
  80. | **AI notes** | On by default, always in Chinese, toggled independently of the language |
  81. | **Original PDF** | A second view in the same file; each page's button opens that exact PDF page, and switching back keeps your position |
  82. | **Navigation** | Hierarchical contents and the roadmap share one stage model, with active-stage highlighting, a progress bar and a page jump |
  83. | **Search** | Searches the selected language(s), shows match counts, and hides non-matching pages together with their AI notes |
  84. | **Figures** | Click or press Enter to enlarge; fit-to-window or original size |
  85. | **Themes & print** | Light and dark themes; prints the selected language at 100% with notes and navigation hidden |
  86. | **Screen size** | 125% effective zoom, applied once |
  87. Ask for different defaults when you need them — for example, open in English
  88. (`initial_mode`), start with the notes hidden (`ai_default`), or use another
  89. zoom level (`screen_zoom`).
  90. ---
  91. ## 🛠️ Bundled Scripts
  92. Claude runs these for you; you can also run them yourself from a clone. With
  93. [uv](https://docs.astral.sh/uv/) there is no install step:
  94. ```bash
  95. S=skills/paper-guide/scripts
  96. # Page count, SHA-256, rotations, extracted text and a PNG per page
  97. # (evidence for authoring — not a verified transcript)
  98. uv run --no-project --with pymupdf python $S/source_pdf.py inspect paper.pdf --out work/source --render-pages
  99. # Crop a figure or table: bbox in PDF points on the unrotated page, top-left origin
  100. # (placeholder coordinates — read them off the inspected page)
  101. uv run --no-project --with pymupdf python $S/source_pdf.py crop paper.pdf --page 6 --bbox 40 80 570 700 --out work/images/figure-1.png
  102. # Package guide.json + images + PDF into one HTML
  103. uv run --no-project --with beautifulsoup4 --with pymupdf python $S/build_reader.py work/guide.json --out Paper_Guide.html
  104. # Static structure/provenance check; add --browser for the Chromium pass
  105. uv run --no-project --with beautifulsoup4 --with pymupdf python $S/validate_reader.py Paper_Guide.html --pdf paper.pdf
  106. ```
  107. `build_reader.py` refuses pages that are unverified or incompletely translated
  108. unless you pass `--allow-incomplete`, and a partial build stays visibly
  109. labeled as partial. The `guide.json` format (`paper-guide/v1`) is documented
  110. in [`references/content-model.md`](skills/paper-guide/references/content-model.md).
  111. ---
  112. ## 📦 Installation
  113. ### From GitHub (Recommended)
  114. ```
  115. /plugin marketplace add https://github.com/LeanderLXZ/paper-guide.git
  116. /plugin install paper-guide@paper-guide
  117. ```
  118. ### From a Local Clone
  119. ```bash
  120. git clone https://github.com/LeanderLXZ/paper-guide.git
  121. ```
  122. Then in Claude Code:
  123. ```
  124. /plugin marketplace add /path/to/paper-guide
  125. /plugin install paper-guide@paper-guide
  126. ```
  127. ### As a Personal Skill (No Plugin)
  128. ```bash
  129. git clone https://github.com/LeanderLXZ/paper-guide.git
  130. cp -r paper-guide/skills/paper-guide ~/.claude/skills/
  131. ```
  132. The skill is then available as `/paper-guide` in all your projects.
  133. ### Updating
  134. ```
  135. /plugin marketplace update paper-guide
  136. /reload-plugins
  137. ```
  138. ### Requirements
  139. - **Claude Code** — plugin support is needed only for the plugin install.
  140. - **Python 3** with **PyMuPDF** and **Beautiful Soup 4**. With `uv` they are
  141. fetched on demand; otherwise run `pip install pymupdf beautifulsoup4`.
  142. - *Optional:* **Playwright** with Chromium or Chrome for the browser check
  143. (`--browser-bin /path/to/chrome`, or `playwright install chromium`). The
  144. validator never downloads a browser itself.
  145. - *Optional:* local OCR for scanned PDFs.
  146. ---
  147. ## 🗂️ Repository Layout
  148. ```
  149. paper-guide/
  150. ├── .claude-plugin/
  151. │ ├── plugin.json # plugin manifest
  152. │ └── marketplace.json # self-hosted marketplace listing this plugin
  153. ├── skills/paper-guide/ # the skill — copy this folder for a personal install
  154. │ ├── SKILL.md # workflow: inspect → author → build → validate → deliver
  155. │ ├── references/
  156. │ │ ├── content-model.md # guide.json schema (paper-guide/v1)
  157. │ │ ├── authoring.md # fidelity, figure, AI-note and roadmap rules
  158. │ │ └── reader-contract.md # reader behavior and acceptance checks
  159. │ ├── scripts/
  160. │ │ ├── source_pdf.py # inspect pages; crop figures with provenance
  161. │ │ ├── build_reader.py # guide.json → one self-contained HTML
  162. │ │ └── validate_reader.py # static + optional browser checks
  163. │ ├── assets/
  164. │ │ ├── shell.html # outer document: guide/PDF switch, zoom, embedded PDF
  165. │ │ └── reader.html # inner reader: map, contents, pages, AI notes
  166. │ └── agents/openai.yaml # interface metadata for OpenAI Codex (ignored by Claude Code)
  167. ├── README.md
  168. └── LICENSE
  169. ```
  170. ---
  171. ## ⚠️ Scope and Responsibility
  172. - The scripts **package and validate** what was written. They do not
  173. translate, summarize or certify scientific accuracy — check the translation
  174. and notes against the PDF before relying on any detail.
  175. - The skill does not send papers to third-party OCR or translation services
  176. unless you allow it, and it never publishes, shares or commits anything on
  177. its own.
  178. - Translations are unofficial; the generated reader says so and credits the
  179. original rights holders. **The reader embeds the complete original PDF**, so
  180. sharing a reader means sharing the paper. Process and share only papers you
  181. are entitled to use.
  182. ---
  183. ## 📄 License
  184. [MIT](LICENSE) © LeanderLXZ

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.