paper-to-note

name	paper-to-note
description	Use when reading an academic paper or paper URL and saving structured Chinese notes with metadata/assets to Obsidian.
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","WebFetch","WebSearch","Agent","mcp__codex__codex"]

Paper-to-Note

Generate high-quality structured reading notes for academic papers.

Scope（与 paper-to-skill 的分工）

• 本 skill 目的：生成"阅读笔记"，让人类读者读懂论文（motivation / 核心贡献 / 方法直觉）。
• 如果你的目标是"把算法植入新 codebase"（需要逐行代码映射、Porting Checklist、commit 锚点、模块接口 contracts）：请使用 paper-to-skill skill，产物在 ~/ai-skills/skills/。
• 最佳工作流：先用本 skill 读懂，再用 paper-to-skill 提炼工程手册。本 skill 在保存笔记时，如果已有对应 paper-to-skill skill，会自动填写 frontmatter 的 paper_to_skill 属性以便互相跳转。

Shared Infrastructure

• ~/.claude/skills/_shared/commit-anchor.md — commit SHA 锚点格式（Pitfall P5 引用）
• ~/.claude/skills/_shared/pseudocode-rules.md — 伪代码质量规则
• ~/.claude/skills/_shared/known-categories.md — Obsidian 分类
• paper-to-note/scripts/extract_figures.py — canonical 图像提取工具；arXiv source-first，保留原始 source raster/vector 质量。若 runtime 还有旧的 $SHARED/extract_figures.py 镜像，必须确认它与本脚本一致后再用。
• paper-to-note/scripts/calibrate_widths.py — 全 vault 批量校准/验收图片嵌入：<img width="N"> 与 extract_figures.recommend_width 同步，并通过 --auto-center 把裸 <img> 包成 <div align="center"> ... </div> / 多 img 同行时整行 inline-wrap。dry-run 默认无副作用，--apply 时自动 backup 到 ~/.cache/paper_notes_calibration_backup/<ts>/。同时承担自适应图片宽度推荐（--auto-width 子命令；详见 Step 5d / P12）。
• paper-to-note/scripts/calibrate_widths.py — 全 vault 批量校准 / 验收工具，支持 dry-run 与 --apply（带备份）。Step 5e Verify 阶段必须用 --tolerance 0 --limit-diffs 0 dry-run 检查"所有 <img> width 都已是脚本推荐值"。

Runtime Path Fallback（跨 runtime 路径约定）

本 skill 同时存在两份副本，在不同 runtime 下读取不同的物理路径（内容保持一致）：

逻辑引用	Claude Code 原生路径	Cursor / Codex / 其他共享 runtime
$SHARED/<file>	~/.claude/skills/_shared/<file>	~/.agents/skills/_shared/<file>
$REVIEWER	~/.claude/agents/paper-to-note-reviewer.md	~/.agents/skills/paper-to-note/agents/paper-to-note-reviewer.md

下文所有 ~/.claude/skills/_shared/... 与 ~/.claude/agents/paper-to-note-reviewer.md 引用，执行时按上表选择当前 runtime 下实际存在的那条路径即可（两条路径等价）。

Context Budget Rules（必须遵守）

The most common failure mode is re-counting the same long context across many turns and agents. Treat context as a budgeted artifact, not a transcript.

• Default to path-based handoff: write intermediate paper text, figure inventory, code notes, and review findings to files in an external scratch directory outside the Obsidian vault; pass only paths plus a short objective in prompts.
• Do not paste full artifacts into prompts: pass file paths for the PDF, note .md, image directory, repo checkout, and source files. Only paste small excerpts needed for the current decision.
• Create a compact work packet outside the vault before review: write a short review_packet.md under $PAPER_TO_NOTE_WORKDIR/<paper-slug>/ if set, otherwise ${TMPDIR:-/tmp}/paper-to-note/<paper-slug>/. It should contain only paper metadata, note path, image dir, code repo/ref, figure inventory, unresolved risks, and changed sections since the last review. Keep it under ~120 lines by default and never exceed ~200 lines.
• Never pollute the Obsidian vault with scratch artifacts: do not create review_packet*.md, revew_packet*.md, tmp/, _tmp/, _work/, extracted paper text, reviewer notes, or cloned repos anywhere under /Users/bytedance/Library/CloudStorage/OneDrive-个人/paper_notes/ (or the equivalent ~/OneDrive/paper_notes/). The vault may contain only the final note under notes/ and final referenced assets under files/.
• Read selectively: when revisiting the paper/note/source, use section-level reads, grep headers, or table/figure inventories instead of reloading the full paper, full note, full source tree, or prior chat.
• Bound multi-agent usage: multi-agent review is allowed, but use the rule-based set below (do NOT let the agent self-judge "low risk" to skip Source Code Reviewer):
  • Always run Format Reviewer + Content Reviewer.
  • Source Code Reviewer is MANDATORY whenever the paper has a public GitHub repo (i.e. github_ref will be set). The only valid skip condition is: the note explicitly states 代码搜索未找到开源实现 after a documented search.
  • Never spawn a coordinator that then spawns another 3 reviewers unless the runtime has no direct parallel-agent support. Never pass the full conversation or full paper to reviewers.
• No full-context subagent forks: when the runtime supports agent context controls, start reviewers without inheriting the whole chat history. Give them only $REVIEWER, the external review_packet.md path, and concrete file paths.
• Keep reviewer prompts small: reviewer prompt should be ≤ ~1,200 words and must not inline the whole skill, note, paper, transcript, or source code. Reference instruction files by path.
• Targeted re-review only: after fixing issues, re-run only the reviewer scope affected by the fix. Do not repeat all reviewers with the complete long context unless the note was substantially rewritten.
• No git-worktree review in paper/vault dirs: do not use Codex/worktree-isolated review when the current directory is a paper folder, Obsidian vault, or any git repository without a valid HEAD (git rev-parse --verify HEAD fails). In that case, review in-place with read-only file access and do not try to resolve base branch HEAD.

Language Rules

• All note content in Chinese, except:
  • Technical terms keep English (e.g. Diffusion Model, RLHF, Transformer)
  • Names, institutions, datasets, model names keep original language
  • Code and pseudocode in English
• All math formulas in LaTeX: inline $...$, display $$...$$

Note Format

Detail-first Standard（默认深度要求）

Unless the user explicitly asks for a short summary, write the note as a detailed reading note, not an abstract-style overview. The target is that a reader can understand the paper's motivation, method, experiments, and practical caveats from the note itself without immediately reopening the PDF.

• Depth over brevity: include concrete assumptions, design motivations, component-by-component mechanics, algorithm flow, objective terms, important implementation details, ablation interpretations, and limitations. Avoid one-paragraph summaries for sections where the paper spends substantial space.
• Specificity over generic prose: name the actual modules, datasets, baselines, reward models, losses, schedules, hyperparameters, and measured numbers. Do not write generic phrases like "提升效果明显" without the exact table/figure evidence.
• Explain, do not only transcribe: after formulas, figures, algorithms, and tables, add human-readable interpretation: what each symbol/component means, why the design is needed, what failure mode it addresses, and how it differs from prior work.
• Appendix is in scope: if appendix/supplement includes training details, extra ablations, prompt lists, implementation choices, or failure cases that materially affect understanding or reproduction, incorporate them into §3–§5 instead of ignoring them.
• Minimum length: unless the user explicitly asks for a short summary, the final saved note MUST contain at least 3000 effective words. Effective words are counted as Chinese CJK characters + English/alphanumeric word tokens after stripping YAML frontmatter, code blocks, image tags/embeds, URLs, and Markdown syntax. If the note is shorter, expand with substantive method details, experiment evidence, appendix material, code-to-paper interpretation, figure/table explanations, and limitations; never pad with repetitive filler, artificial line breaks, or one-sentence-per-line formatting.
• Depth priority: allocate the most detail to §1 Motivation, §2 Idea, and especially §3 Method. These three sections should carry the main paper understanding: why the problem matters, what the core insight is, and how the method actually works. Only after these are clear and detailed should §4 Experimental Setup and §5 Experimental Results be summarized with exact evidence.

Existing-note optimization（已有笔记补强）

When asked to optimize existing notes below the minimum length, the trigger is effective word count < 3000, not Markdown line count.

• Preserve the existing note path and category by default; only move/rename when the existing category is clearly wrong and the user asked for taxonomy cleanup.
• Back up before editing: copy the original .md to an external scratch/backup directory outside the vault before overwriting the note.
• Expand by substance, not formatting: add missing mechanisms, paper/code evidence, figure/table interpretation, limitations, and exact experimental details. Do not increase length by splitting sentences into many lines, adding boilerplate checklists, duplicating section prompts, or inserting generic filler.
• Re-count after editing using the same effective_words = CJK chars + Latin/alphanumeric tokens script in Step 5e. The final note must be effective_words >= 3000 unless the user explicitly sets a lower threshold.
• Batch hygiene: for large vault-wide optimization, process notes in small batches and run a post-batch check for word count, image refs, code fences, and vault scratch artifacts before continuing.

0. Mandatory Skeleton（每篇笔记的格式硬底线）

These are non-negotiable structural items. A note missing any of them will be marked P0 by the Format Reviewer and must be fixed before approval.

1. frontmatter MUST contain a title field with the full paper title (not just the short name). Reason: Obsidian uses title as the canonical display name; without it, search and graph view both degrade.

   ---
   title: "World-R1: Reinforcing 3D Constraints for Text-to-Video Generation"
   authors: ...
   ---
   

2. Top of the note MUST contain a Paper / Code / Code-reference blockquote block immediately after the H1 heading, before any section. Skip Code / Code reference lines only when no public code exists.

   # <Paper Title>
   
   > **Paper**: [arXiv:XXXX.XXXXX](https://arxiv.org/abs/XXXX.XXXXX)
   > **Code**: [<owner>/<repo>](https://github.com/<owner>/<repo>)
   > **Code reference**: `<branch>` @ `<short_sha>` (YYYY-MM-DD)
   

3. frontmatter MUST contain tags with ≥4 specific technical tags (concrete techniques, not generic categories). Bad: ["RL", "video"]. Good: ["RL", "video-generation", "Flow-GRPO", "3D-consistency"].
4. Training-config numbers MUST come from the actual launch script / experiment config (e.g. config/<paper_name>.py, configs/<exp>.yaml, scripts/train_*.py), NOT from config/base.py default values or generic README defaults. Whenever the reported number could plausibly be a default, the note MUST cite the specific file path that overrides it.
5. When paper formula and released code disagree (e.g. paper says HPSv3 but code calls hpsv2; paper writes "average over $K$ frames" but code samples 1 random frame), the note MUST explicitly call out the gap in §3 Method, format: 论文公式与 released code 实现差异：.... Do NOT silently align the note to one side.

Blog / article mode: if the input is a blog post, project article, or non-paper technical essay, save it under paper_notes/blogs/ (unless the user says otherwise), not the paper taxonomy. The Markdown filename MUST start with the visible/published date, e.g. YYYY-MM-DD Blog Title.md, and frontmatter MUST include date or published. Prefer the date visible in the rendered page/user-facing post; if raw metadata disagrees due to timezone or site build artifacts, record the rendered date in the filename/frontmatter and keep the raw value only as a secondary note if useful.

---

1–5: Required Section Content

Output strictly in these 5 sections, each with substantive content. Default to maximum useful detail: do not compress a multi-page method/experiment section into a few bullets unless the user explicitly asks for a brief note. The note's explanatory center of gravity should be Motivation → Idea → Method; experiments and results are still required, but they support the reader's understanding rather than replacing method explanation.

---

1. Motivation (研究动机)

• What problems exist in current methods? (be specific: what capability is missing or what bottleneck exists)
• What problem does this paper aim to solve? (state the concrete target, not a broad area)
• Why is this problem worth studying? (what unlocks once solved)

---

2. Idea (核心思想)

• What is the core insight? (1–3 sentences; what's fundamentally new, not just renamed)
• Summarize the key innovation in 1–3 sentences
• What is the fundamental difference from existing methods? (name a specific competing approach and contrast)

---

3. Method (方法)

This is the most important section — expand in detail. Cover every novel component and every paper section that materially contributes to the method. If the paper has multiple modules/stages/objectives, each should get its own subsection with intuition, mechanics, formula/code where applicable, and interaction with the rest of the pipeline.

1. Overall framework: describe the overall design, embed the architecture figure
2. Key components: explain each core module with sub-figures where available. For each component, include: what input it consumes, what output it produces, which objective or constraint it optimizes, why the authors need it, and what would likely fail if it were removed.
   • Every figure MUST have a "Figure N 解读" paragraph after the <img> tag, separated by a blank line (see P8)
   • The walkthrough should explain what each part of the figure shows and how it relates to the method
   • When text references a figure (e.g. "如图 3a 所示"), always specify the figure number
3. Math formulas: key loss functions, objectives, algorithm formulas (LaTeX)
4. Pseudocode (for algorithm-improvement papers):
   • ALWAYS search for open-source code — never assume code is unavailable just because the paper says "plan to release"
   • Use WebSearch to verify: [paper title] github, [author org] github [method name]
   • Read the actual source code and produce pseudocode reflecting real implementation
   • Write pseudocode for EACH key component separately, not just the overall pipeline
   • E.g. if a paper has 4 novel components, write 4 separate pseudocode blocks
   • Pseudocode MUST be Python/PyTorch style — use real Python syntax with PyTorch API (e.g. torch.tensor, nn.Module, F.cross_entropy)
   • Use python code blocks for syntax highlighting
   • Format: write as a runnable Python/PyTorch function or class, not numbered steps
   • Example:

   def train_step(model, batch, optimizer):
       x, y = batch
       logits = model(x)  # forward pass
       loss = F.cross_entropy(logits, y)
       loss.backward()
       optimizer.step()
       return loss.item()
   

5. Code-to-paper mapping table: map key paper concepts to actual source files/classes. Always add a reference header immediately before the table:

   > **Code reference**: `main` @ `abc12345` (2026-04-17) — pseudocode and mapping based on this commit
   

---

4. Experimental Setup (实验设置)

• Datasets used and their scale (name each dataset + sample count)
• Baseline methods compared (list specific methods by name)
• Evaluation metrics (list each metric with 1-line definition if non-obvious)
• Training config (model, hardware, hyperparameters) (GPU type/count, training steps, LR, batch size)

---

5. Experimental Results (实验结果)

• Performance numbers on main benchmarks (use tables or lists) (exact values from paper tables, no approximations)
• Key findings from ablation studies (which components matter and by how much)
• Limitations of the method (if mentioned by authors; do not fabricate)
• Overall conclusions (what the results demonstrate)

---

Execution Steps

Step 1: Obtain paper content

• User uploaded PDF: read directly with Read tool
• User gave a link: prefer WebFetch for normal web pages; if WebFetch fails with domain safety verification / enterprise policy errors, immediately fall back to Bash(curl -L ...) or python urllib/request and continue.
• arXiv links: use curl as the default path in proxy/offline-routed runtimes; fetch the HTML abstract page and PDF directly:

  curl -L "https://arxiv.org/abs/<arxiv_id>" -o ~/ai-skills/papers/<arxiv_id>.html
  curl -L "https://arxiv.org/pdf/<arxiv_id>" -o ~/ai-skills/papers/<arxiv_id>.pdf
  

• Only a title given: use WebSearch to find the paper, then fetch it
• Always download PDF to ~/ai-skills/papers/ for figure extraction

Step 2: Extract original figures

Source-first rule for arXiv papers（默认路径）: if the paper has an arXiv ID, you MUST extract figures from the arXiv LaTeX source before considering any PDF crop. The PDF is for reading/verification; it is not the default figure source. Do not create cropped PDF screenshots for arXiv papers unless source extraction returns no usable figure for a specific required figure/table, and record that exception in the working notes.

For arxiv papers (default): download source tarball/e-print to get original high-res figure files:

python3 ~/.claude/skills/paper-to-note/scripts/extract_figures.py \