# Cs Paper Reader > Use when the user wants to read, summarize, dissect, compare, or write structured Chinese Markdown notes for computer science research papers, especially from PDF/arXiv/conference papers. Supports both single-paper deep reads (Mode A) and unattended batch reading of an entire folder / chapter / manifest (Mode B). Produces deep paper-reading notes in a style with background, motivation, formal definitions, method details, formula explanations, experiments, differences from related work, contributions, limitations, and research ideas. - Skill: `randydkx/cs-paper-reader` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add randydkx/cs-paper-reader` - Raw SKILL.md: https://api.skillmd.com/api/skills/randydkx/cs-paper-reader/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: randydkx (https://skillmd.com/u/randydkx) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/randydkx/cs-paper-reader --- # CS Paper Reader ## Output Goal Produce a Chinese Markdown paper-reading note modeled after the user's existing long-form notes: precise, structured, explanatory, and useful for research reuse. **Prefer deep interpretation over shallow summary.** Notes must be grounded in the actual PDF content, not in second-hand descriptions from a citation index or another note. ## Output Hygiene **Display math formatting**: keep readable Markdown display equations in the normal multi-line form with standalone `$$` fence lines. Standalone `$$` lines are formatting-only and must be ignored by anti-template / collision checks; do not collapse formulas into one-line `$$...$$` blocks merely to avoid repeated fence-line collisions. Evidence files, scan manifests, raw OCR/text dumps, exploratory crops, and other intermediate artifacts must stay under `/tmp` or another explicit scratch path, not inside the final reading output directory. The final reading output directory should contain only: - finalized Markdown notes; - progress / final report / collision-warning files (`_progress_.md`, `_final_report_.md`, `_collision_warnings.md`); - images actually referenced by the notes. In Mode B, store per-paper evidence and `paper-figure-clipper` `manifest.json` files under a task-specific `/tmp` directory, for example `/tmp/cs-paper-reader-/`, and promote only referenced images into `/_figs//`. ## When To Use Use this skill for computer science papers when the user asks to: - 精读 / 解读 / 总结 / 拆解论文 - 写 `论文名称.md` 笔记 - 批量重写一个目录 / 章节 / manifest 里的多篇论文笔记 - 比较一组论文或梳理相关工作 - 提取公式、算法、实验、贡献、局限、可借鉴点 - 判断方法和某类范式 / 技术是否相似 If the task mainly needs PDF rendering / layout extraction, also call the `pdf` skill. ## Two Operating Modes This skill has two modes. Decide which one at the start and announce it. ### Mode A — Single paper deep read The default. The user provides one PDF or arXiv ID. Follow §"Reading Workflow" and write one note. ### Mode B — Batch reading Triggered when any of these is true: - The user points at a folder of PDFs and asks to "逐篇阅读 / 全部读完 / 整章 / 全自动". - The user provides a manifest / progress file (e.g. `_manifest_XXX.md`, `_progress_XXX.md`). - The user points at a folder containing multiple existing low-quality notes to rewrite. - The user explicitly asks "一次性 / 全自动 / 跑完 / 重写整章". Batch reading covers both **fresh batch reading** (no prior notes — generate from PDFs) and **batch rewrite** (replace existing low-quality notes). The workflow is the same; only Step §2.Step E's "delete old version" branch differs. In Mode B, read **`references/batch-workflow.md`** first and follow it strictly. Mode B has additional requirements that Mode A does not (progress tracking, anti-template enforcement, response-budget splitting, etc.) — failing to honor them is the failure mode this skill was hardened against. **🚫 Hard prohibition in Mode B**: you MUST NOT write a Python / shell script that auto-generates the notes themselves from templates + evidence files. Each note must be produced by the model itself in its own `Write` call, after re-reading and re-reasoning about that specific PDF. Scripts are allowed only for pure data-prep (pdftotext, evidence extraction, progress-table updates, quality-check invocations) — never for content generation. See `references/batch-workflow.md` §2.5 for the full rule and detection signals. Even when the user says "自动 / 全自动 / 批量", this prohibition still applies — "automated" means "no questions to the user between papers", NOT "delegate writing to a script". ## Reading Workflow (both modes) 1. **Identify source**: PDF / arXiv / OpenReview / ACL Anthology / PMLR / local Markdown. If only a citation is given, locate the actual PDF before writing anything. 2. **Extract the PDF with `pdftotext -layout`** into `/tmp/.txt`. If the layout breaks formulas, also run `pdftoppm` and visually inspect the relevant pages. **Never write a note without opening the PDF.** "I know this paper from training data" is not acceptable — quote the PDF. 3. **Collect the Evidence Seven-Pack** before drafting any §1-§6 prose: 1. The **problem statement sentence** from the abstract (verbatim quote). 2. At least **one paragraph from the introduction that names a prior work and explains why it fails**. 3. At least **two numbered equations** from the method section (with their Eq. number). 4. The **Algorithm box / pseudocode** (or the closest equivalent). 5. At least **two numerical results from the main table** (with table number, column name, dataset name). 6. At least **one ablation table/figure** with its key numbers. 7. The **Limitations / Future Work paragraph** verbatim. If the PDF has no such section, write literally `PDF 中无 Limitations 章节` in your note. 4. **Skim structure**: title, authors, venue/date, abstract, introduction, method, experiments, limitations, relevant appendix. 5. **Extract the central claim**: write the paper's one-sentence thesis before details. 6. **Build the note around questions**: - 这篇论文解决什么问题？为什么重要？ - 现有方法为什么不够？根本瓶颈是什么？ - 论文的核心 insight 是什么？ - 问题如何数学化定义？训练域、目标域、假设、输入输出、风险函数分别是什么？ - 方法具体怎么做？每个模块输入/输出/优化目标是什么？ - 算法如何用符号、目标函数、递推/优化步骤严谨描述？每一步的数学含义和直觉是什么？ - 实验如何证明 claim？哪些表格/消融最关键？ - 与相关工作的区别是什么？ - 局限、失败场景、可改进点是什么？ 7. **Write with interpretation**: Do not merely translate the abstract. Explain why each design matters and how it connects to the problem. 8. **Flag uncertainty**: If a claim is inferred rather than explicitly stated, say "我的理解是" or "可理解为". If the PDF itself contains a typo (e.g. a subscript that disagrees with another part of the same paper), copy it faithfully but add a `> 笔者注：原文此处 ...，疑为笔误` line. 9. **Run the per-note self-check before `Write`** (mandatory, both modes). Procedure and pass thresholds in §"Per-Note Self-Check"; result file goes to `/tmp/...`, never into the md. ## Mathematical Rigor Requirements These are mandatory for standard and deep notes: - **Problem definition must be formula-based**: Define source/target domains, samples, labels, time/domain descriptors, model family, prediction target, and risk/objective using inline or block equations. Do not describe the task only in prose. - **State assumptions explicitly**: Write the paper's modeling assumptions as equations or quantified statements whenever possible. - **Algorithm section must be mathematically self-contained**: For each module, specify input, output, learned parameters, update rule/objective, and how it composes with other modules. - **Explain every central formula**: After each key equation, explain each symbol and the logic connecting it to the paper's claim. - **Use the paper's own symbols** wherever possible. Do not silently replace `W_l, X_l, H^{-1}` with generic `θ, x, H`. If you must normalize notation across two papers being compared, declare it once at the top of the relevant section. - **Quantitative hard floors per note**: - §3 (方法详解) must contain **≥ 3 formulas that are numbered or recognizable as appearing in the PDF** (not invented). At least 2 of them must be the paper's actual Eq. (with their `Eq. N` label). - §4 (实验结果) must contain **≥ 2 specific numbers from real tables**, each annotated with `Table X, column name, model/dataset`. - §5 (与相关工作的区别) must name **≥ 2 specific compared methods** and give a quantitative or mechanism-level difference (not vague claims like "更适合该任务" / "performance is better on benchmark X"). ## LaTeX & Markdown Hygiene (critical — silently breaks notes if violated) These bugs have been observed in real outputs and must be guarded against on every write: - **Backslash commands must survive serialization.** When writing math like `\frac{a}{b}`, `\sum`, `\sqrt{}`, `\alpha`, `\beta`, etc., the leading backslash gets eaten in some shells and JSON tool-call paths. **Before declaring a note done, grep the file for these residues and fix them**: ```bash grep -nE '[^\\](rac\{|um_|qrt\{|lpha|eta\s|ambda|abla)' ".md" ``` If anything matches, replace `rac{` → `\frac{`, `um_` → `\sum_`, etc. **The note is not done until this grep returns empty.** - **Block formulas use `$$ ... $$` on their own lines.** Tags use `\tag{N}` only when the paper has an Eq. N you're directly citing. - **Inline math uses `$...$`, never backticks.** Symbols, formulas, function/set/space names that the reader should see *rendered* (e.g. `$x \in \mathcal{X}$`, `$\theta$`, `$\mathbb{E}[\cdot]$`, `$O(n \log n)$`) must be wrapped in `$...$`. **Backticks are reserved for code, file paths, shell commands, and CLI flags** — wrapping a formula in `` ` `` produces monospace literal text (`x \in \mathcal{X}`) that doesn't render and is unreadable. This applies inside bullet lists too: `- $\theta$：模型参数`, NOT `` - `\theta`：模型参数 ``. - **Never use `\\sum`, `\\frac`, `\\{`, `\\}` etc.** with double-backslash in Markdown math — Markdown will eat one backslash and you get a literal `\sum`. - **Math Render Gate is mandatory** before marking any note done: - no invisible control characters in the Markdown body; CRLF line endings are OK, but a bare carriage return byte (`\r`) or NUL byte is blocking because it can split commands like `\right` into an unrenderable fragment; - display math fences are standalone `$$` lines; standalone `$$` lines are valid and must not be treated as anti-template collisions; do not collapse multi-line formulas into one-line `$$...$$`; - every display math block is closed, has balanced braces after ignoring escaped `\{` / `\}`, and has matching `\left` / `\right`; - suspicious over-escaped literal braces such as `\\}` or `\\{` are blocking unless the source PDF visibly uses a LaTeX line break followed by a brace, which is extremely rare in these notes. - **Position Render Gate is mandatory** for embedded crops: every `![...](_figs/...)` line must have a nearby visible red explanation block. If the red block is **before** the image, use `下图解释 / 下表解释 / 下方算法`; if the red block is **after** the image, use `上图解释 / 上表解释 / 上方伪代码`. A block saying `上表解释` before a table, or `下图解释` after a figure, is a render-position error. If Markdown layout is uncertain, use a neutral label like `Table 1 解释`, but keep the block adjacent to the image. - **Tables must be Markdown-renderable**: every row has the same column count, separator row uses `---` / `---:` consistently, numbers preserve the paper's decimal precision. - **Hidden HTML for color emphasis**: use ``, ``, `` sparingly (1-3 per note), each highlighting a distinct insight. Don't sprinkle them throughout. ## Default Note Template Use this structure unless the user requests another format: ```markdown # MethodName: Full Paper Title > **发表信息**: venue/year or arXiv date > **作者**: 第一作者 (单位) / 共同一作 (单位) / 其他作者 … > **机构**: ... > **代码/项目**: ... > **本地 PDF**: --- ## 一、研究背景与动机 ### 1.1 [论文自己关心的具体问题 — 写论文实际针对的瓶颈，不写适用于全领域的通用句] ### 1.2 [论文具体批评的 2-4 个先前方法，必须出现具体方法名] ### 1.3 关键 Insight: "[≤25 字的论文自己的一句话]" ## 二、预备知识与形式化定义 ### 2.1 数学化任务定义（用论文符号） ### 2.2 论文用到的关键工具 / 前置算法 ### 2.3 符号表（≥ 4 个新符号时显式列出） ## 三、方法详解 ### 3.1 总览（一张数据流图 or 100-200 字的 mechanism） ### 3.2 模块 / Stage 1 #### 3.2.1 输入 / 输出 / 可学习参数 #### 3.2.2 核心公式（带 Eq. 编号、逐符号解释） #### 3.2.3 直觉：这一步解决 §1.2 的哪个具体缺陷 ### 3.3 模块 / Stage 2 ... ### 3.x 算法伪代码（与论文 Algorithm 框对齐；若论文没有，自构时标"归一化伪代码"） ### 3.x+1 复杂度 / 实现成本 ## 四、实验结果 ### 4.1 实验设置：模型族 / 数据集 / 关键超参（论文所在子领域的核心控制变量，如稀疏率、比特数、学生大小、检索深度、上下文长度等） ### 4.2 主结果（≥ 1 张数值表，数字必须来自 PDF） ### 4.3 关键消融（≥ 1 张表/图的关键发现） ### 4.4 失败 / 不利场景（来自 PDF） ### 4.5 与最直接 baseline 的具体数字差 ## 五、与相关工作的区别 ## 六、核心贡献总结 ## 七、讨论与局限 ## 八、对后续研究的启发（可选） ``` For short notes, compress sections but keep: 背景动机、方法、实验、区别、贡献局限. ## Style Rules - Write in Chinese; keep paper-specific technical terms in English when clearer. - Use numbered Chinese section headers: `## 一、...`, `### 1.1 ...`. - Start with metadata block if available. - **Author affiliations**: in the `作者` line, always annotate the **first author** (and any co-first authors marked with `*` / `†` / `equal contribution`) with their affiliation in parentheses, read from the PDF's title-page footnote. Example: `Alice Wang* (MIT) / Bob Chen* (Tsinghua) / Carol Liu (Google)`. Other authors get affiliations only if it materially helps (e.g. cross-institution collab worth highlighting). - Use bold emphasis for key concepts. - For formulas, show the equation and then explain each symbol line by line. - For algorithms, describe stages with inputs/outputs, learned variables, objective functions, update/recurrence rules, inference rules, and intuitive purpose. - For tables, state what each table proves rather than copying all numbers — but **always** include enough specific numbers to anchor the claim. - Prefer "根本原因 / 直觉 / 为什么有效 / 为什么失败" explanations. - Add "与相关工作的区别" even if the original paper only has a related work section. - Be critical: distinguish author claims, evidence, and your own inference. ## Image-Rich Notes (figure / table / algorithm / equation crops) A high-quality paper note is often **image-rich**: schematic figures, result tables, and pseudocode are easier to read as crops from the original PDF than as transcribed prose. Use the companion skill **`paper-figure-clipper`** to produce these crops with precise bounding boxes (never percent-of-page heuristics). **Image-Rich Notes is ON by default** — every note should embed figures/tables unless the paper genuinely has none worth citing. Don't ask the user whether to enable it. ### When to embed an image Embed a crop in the note when ANY of these is true: - **§3 has a key schematic** (e.g. an architecture diagram, data-flow chart, or routing pattern) the prose can't fully convey. - **§3 has algorithm pseudocode** that matters for reproducibility (any boxed `Algorithm N` with non-trivial control flow). - **§4 reports a multi-column ablation** whose structure (header hierarchy, grouped rows) is more readable as the original table. - **§4 has a scaling or trend curve** (e.g. metric-vs-control-parameter) whose visual trend is more informative than 3-5 transcribed numbers. - **A single equation is too complex** for faithful Markdown reproduction (multi-level subscripts, matrix operators) and a tight crop is clearer. Do NOT embed crops: - For decorative reasons. Every embedded image must be cited by name and explained in the surrounding prose. - As a substitute for transcribed numbers. Tables in §4 should be discussed by specific cell values; the crop is supplemental. ### Workflow 1. **Once per paper (MUST, no shortcuts)**: run `clip.py scan` to enumerate all figures/tables. **Do NOT bypass this with self-written `PyMuPDF` / `fitz` / `pdfplumber` bbox guessing** — `clip.py` uses caption-anchored bboxes that are far more reliable than hand-picked coordinates, and it produces the `manifest.json` that downstream steps depend on. Roll-your-own clipping is only allowed if `clip.py scan` itself errors out, and you must say so in the progress remark. ```bash ~/.codex/skills/paper-figure-clipper/scripts/clip.py scan \ --pdf "" \ --out-dir "/tmp/paper-figs/" ``` Read the resulting `manifest.json` to learn which figures/tables exist and their captions. **Sort entries by `body_refs` descending** — figures with `body_refs ≥ 3` are central to the paper's narrative and should be embedded first; `body_refs = 1` is usually supplementary and can be skipped unless it carries a unique ablation insight. **🚫 Do NOT call `view_image` on every scan-produced PNG.** That burns enormous token budget for negligible quality gain — scan output is reliable by default. Open **only the top 1~3 PNG by `body_refs`** to visually verify the crop is clean (no caption cut off, no neighboring text bleed, no missing legend). Open the top 2~3 only when they are equally critical to the note. All other crops are accepted as-is from `scan` without inspection. If the top-1~3 crop is broken, fix via `clip bbox` per step 2 — **inspecting more PNGs will not change this decision**. 2. **For algorithm/equation/sub-figure crops** that `scan` doesn't cover, use `clip` mode (also to `/tmp/`). **优先级**：若 step 1 产出的概念图/框架图 bbox 有严重问题（截断、漏标题、含杂内容），优先用 `clip bbox` 微调原图；其它情况（scan 没覆盖的算法/公式/子图）才走 `clip` mode 重裁。 **Bad-crop salvage (4-candidate recipe)**: when the top-1 (or top-2/3) figure / algorithm has severe truncation (only the title, missing last lines, half a figure cut off), do **NOT** retry with one larger bbox — that usually fails again. Instead generate **4 bbox candidates** at progressively larger margins into `/tmp/paper-figs//_candidates/`, view the 2×2 contact sheet, `cp` only the winner to the canonical filename, delete the rest. Copy-pasteable commands in `~/.codex/skills/paper-figure-clipper/references/recipe-book.md` §R4.5. **Trigger** — step 2 fixes at most the top-1/top-2 critical figures this way; all other figures keep `scan` output unchanged. Never run the 4-candidate recipe proactively. ```bash clip.py clip --pdf P.pdf --out /tmp/paper-figs//algorithm_1_p5.png algorithm --label "Algorithm 1" --page 5 clip.py clip --pdf P.pdf --out /tmp/paper-figs//equation_3_p3.png equation --label "3" --page 3 ``` 3. **Reference in the note** with relative Markdown image syntax. **The explanation goes in the body as a red-font block**, never in alt text. The example below is from an LLM-compression note (SparseGPT) — the format generalizes to any paper: ```markdown **下方算法**：第 6–9 行的 Hessian 更新只依赖右下子矩阵，这是 SparseGPT 复杂度优化的来源；第 4 行的 mask reselect 每 $B_s=128$ 列做一次。 ![Algorithm 1 — SparseGPT 单层剪枝主循环](_figs/SparseGPT/algorithm_1_p5.png) ``` Why a body block instead of a long alt text: Markdown viewers render alt text as a hover tooltip — readers can't see it without mousing over. Putting the explanation as visible body text means it's readable on first scroll. Use one of `上图解释 / 下图解释 / 上表解释 / 下表解释 / 下方算法 / 上方伪代码` depending on position (**IMPORTANT**: image-below content uses `上*`, image-above content uses `下*` !). The alt-text inside `[ ]` must be **minimal** — just `