# Paper Reading

> Use when user asks to read, summarize, or analyze a research paper (PDF or text). Triggers on keywords like "read paper", "summarize paper", "paper summary", "literature review", "analyze this paper". Produces either a Markdown summary or a styled HTML summary with hand-drawn SVG diagrams — when the user hasn't said which, ask first.

- **Type:** Skill
- **Install:** `agentstack add skill-mizoreww-awesome-claude-code-config-paper-reading`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Mizoreww](https://agentstack.voostack.com/s/mizoreww)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Mizoreww](https://github.com/Mizoreww)
- **Source:** https://github.com/Mizoreww/awesome-claude-code-config/tree/main/skills/paper-reading

## Install

```sh
agentstack add skill-mizoreww-awesome-claude-code-config-paper-reading
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Paper Reading - Research Paper Summarization

## Overview

A structured approach to reading and summarizing scientific research papers. **Automatically identifies paper type** (empirical/theoretical/survey/systems), selects the appropriate template, screenshots important figures, and embeds them in the summary document.

## When to Use

- User provides a paper (PDF path, URL, or pasted content) and asks for summary
- User asks to "read", "summarize", or "analyze" a research paper
- User wants to understand a paper's contribution quickly
- Literature review tasks

**Not for:** Tutorial papers, textbooks, or non-research documents

## Workflow

```dot
digraph paper_reading {
    rankdir=TB;
    "Receive paper" -> "Choose format (md/html)";
    "Choose format (md/html)" -> "Get PDF file";
    "Get PDF file" -> "Read PDF content";
    "Read PDF content" -> "Identify paper type";
    "Identify paper type" -> "Prepare output directory";
    "Prepare output directory" -> "Extract figures (pymupdf4llm)";
    "Extract figures (pymupdf4llm)" -> "Filter & rename images";
    "Filter & rename images" -> "Fill type-specific template";
    "Fill type-specific template" -> "Write markdown file" [label="md"];
    "Fill type-specific template" -> "Render styled HTML + inline SVG" [label="html"];
}
```

## Step 0: Choose Output Format (md vs html)

Settle the output format before doing the work — it shapes how you present everything downstream, and the token cost difference is real, so the user deserves the choice.

- **User already named a format** → honor it, don't ask. Treat a request for a web page, a "nice-looking"/visual summary, or an explicit "html" as HTML; treat "md"/"markdown"/plain-text requests as Markdown. The user may phrase this in any language — match on intent, not on literal English keywords.
- **User didn't say** → ask one short question **in the user's language** and wait for the answer. Name the trade-off honestly rather than guessing: Markdown is lightweight and token-cheap (good for archiving and re-editing), while HTML looks better and adds hand-drawn SVG flowcharts/diagrams at the key points to aid understanding, but costs more tokens.

Both formats share the **same content backbone**: the type-specific template, the same extracted figures, the same depth-first writing. HTML is not a different or thinner summary — it's the same analysis, presented so a reader grasps it faster. So always do the full analysis (Steps 1–4), then either write Markdown or render it as HTML (see **HTML Output Mode** near the end).

## Step 1: PDF Acquisition

All papers are processed as PDF. No HTML/ar5iv path.

| Source | Detection | Action |
|--------|-----------|--------|
| Local PDF | File path ends with `.pdf` | Use directly |
| arXiv URL | Contains `arxiv.org` | Extract paper ID → download `https://arxiv.org/pdf/XXXX.XXXXX` |
| Other URL | Default | Try downloading as PDF; if not a PDF, use WebFetch for text |

### Download Flow

```bash
# For arXiv: extract ID and download PDF
curl -L -o /paper.pdf "https://arxiv.org/pdf/XXXX.XXXXX"

# For other URLs: try direct download
curl -L -o /paper.pdf ""
# Verify it's a valid PDF: file /paper.pdf should show "PDF document"
```

### Read Content

Use the **Read tool** to read the PDF file. Claude natively supports reading PDF files and extracting text content. For large PDFs (>10 pages), read in page ranges (e.g., `pages: "1-10"`, then `pages: "11-20"`).

## Step 2: Paper Type Identification

After reading the title, abstract, and introduction, determine paper type:

| Type | Identification Signals |
|------|----------------------|
| **Empirical** | Proposes new method/model, has experimental comparisons, includes baselines |
| **Theoretical** | Theorem/proof-driven, math-heavy derivations, few or no experiments |
| **Survey** | Many citations (>100), taxonomy/classification, "survey"/"review" keywords |
| **Systems** | System design, engineering implementation, benchmarks, deployment experience |

**When uncertain, default to the Empirical template.**

## Step 3: Figure & Table Extraction (pymupdf4llm)

### 1. Prepare Output Directory

```bash
mkdir -p /images
```

### 2. Screenshot Priority Guide

| Priority | Figure Type | When to Capture |
|----------|-------------|-----------------|
| Must | System architecture / overall framework | If available |
| Must | Main experiment results table/chart | If available |
| Recommended | Core algorithm flowchart | If available |
| Recommended | Ablation study charts | If available |
| Optional | Visualization / qualitative results | If space allows |
| Optional | Auxiliary illustrations | As needed |

Capture **3-8** key figures per paper. If the paper has few or no meaningful figures (e.g., theoretical papers, short workshop papers), skip figure extraction and produce a text-only summary.

### 3. Automated Extraction with pymupdf4llm

Use pymupdf4llm to extract all images and vector graphics in one call. This handles raster images (photos, embedded figures) AND vector graphics (plots, diagrams, flowcharts) automatically.

**Prerequisites:** `pymupdf` and `pymupdf4llm` must be installed in the conda base environment.

```bash
# Install if needed (one-time)
source $HOME/anaconda3/etc/profile.d/conda.sh && conda activate base
pip install pymupdf4llm
```

**Run extraction:**

```bash
source $HOME/anaconda3/etc/profile.d/conda.sh && conda activate base && python3 "
image_dir = "/images"
os.makedirs(image_dir, exist_ok=True)

# Extract all figures, tables, and vector graphics as images
md_result = pymupdf4llm.to_markdown(
    pdf_path,
    write_images=True,
    image_path=image_dir,
    image_format="png",
    dpi=200,
    use_ocr=False,        # Disable OCR (avoids tesseract dependency)
)

# List extracted images
for f in sorted(os.listdir(image_dir)):
    if f.endswith(('.png', '.jpg', '.jpeg')):
        from PIL import Image
        try:
            img = Image.open(os.path.join(image_dir, f))
            print(f"{f}: {img.size[0]}x{img.size[1]}")
        except:
            print(f"{f}: (size unknown)")
PYEOF
```

### 4. Filter & Rename Extracted Images

pymupdf4llm extracts ALL graphical regions, including logos, watermarks, and decorative elements. Filter and rename:

**Step 4a: Filter out noise** — Remove images that are:
- Too small ( 10:1 or /images"
removed = []
for f in os.listdir(image_dir):
    path = os.path.join(image_dir, f)
    try:
        img = Image.open(path)
        w, h = img.size
        ratio = max(w, h) / max(min(w, h), 1)
        if w  10:
            os.remove(path)
            removed.append(f"{f} (too narrow: {w}x{h})")
    except:
        pass

print(f"Removed {len(removed)} noise images:")
for r in removed:
    print(f"  - {r}")

kept = [f for f in sorted(os.listdir(image_dir)) if f.endswith(('.png', '.jpg'))]
print(f"\nKept {len(kept)} images:")
for f in kept:
    img = Image.open(os.path.join(image_dir, f))
    print(f"  {f}: {img.size[0]}x{img.size[1]}")
PYEOF
```

**Step 4b: Visual review & rename** — Use the Read tool to view each remaining image. Based on content:
- Rename to descriptive names: `figure_1_overview.png`, `table_2_main_results.png`, etc.
- Delete any remaining non-figure images (headers, footers, etc.)
- Select 3-8 key figures for the summary based on the priority guide above

### 5. Fallback: Manual pymupdf clip extraction

If pymupdf4llm misses a specific figure or table (rare), use direct pymupdf clip rendering:

```bash
source $HOME/anaconda3/etc/profile.d/conda.sh && conda activate base && python3 ")
page = doc[PAGE_NUM]  # 0-indexed

# Render a specific region at high resolution
clip = fitz.Rect(x0, y0, x1, y1)  # coordinates from page layout
mat = fitz.Matrix(3, 3)  # 3x zoom
pix = page.get_pixmap(matrix=mat, clip=clip)
pix.save("/images/figure_N_desc.png")
doc.close()
PYEOF
```

To find coordinates: use `page.get_text("dict")` to find text blocks containing "Figure N" or "Table N", then estimate the figure region nearby.

### File Naming

Format: `figure_N_.png` / `table_N_.png`

Examples:
- `figure_1_overview.png` — system overview
- `figure_2_architecture.png` — model architecture
- `table_3_comparison.png` — main results table
- `figure_4_ablation.png` — ablation study

## Step 4: Fill Template

### After identifying paper type, select the corresponding template

### Writing Principles (Critical)

**Depth-first**: For every section, ask "why" and "how", not just "what".

| Shallow writing (prohibited) | Deep writing (required) |
|------------------------------|------------------------|
| "Proposes a new method" | "Addresses bottleneck Y in problem X via mechanism Z" |
| "Achieves SOTA results" | "Improves X% over method B on dataset A, primarily because of Y" |
| "Uses a Transformer" | "Uses L-layer Transformer with input dim D, H attention heads, key modification is Z" |
| "Has some limitations" | "Only validated in scenario X, does not account for distribution shift Y, assumption Z may not hold in practice" |

### After identifying paper type, select the corresponding template

All types share these sections:

```markdown
## Basic Information
- **Title:**
- **Authors:**
- **Affiliation:** (optional)
- **Published:**
- **Link:**
- **Paper Type:** [Empirical / Theoretical / Survey / Systems]
- **One-line summary:** What was done + how + what was the result

## Research Problem
- **What problem does it solve?** Identify the specific gap in existing methods
- **Key assumptions:** What constraints/limitations frame the research
- **Why is it important?** The practical impact on the field
- **Positioning among related work:** What are the 2-3 closest prior works? What is the key difference?
```

---

### Template A: Empirical Paper

```markdown
## Basic Information
[shared section]

## Research Problem
[shared section]
- **Mathematical formulation:** (optional)

## Key Insight
> Distill the paper's core new idea in 2-3 sentences. Not "what was done", but "what insight makes this method work".
> Example: Rather than predicting frame-by-frame, first establish long-term 3D point tracking, then leverage temporal consistency for joint optimization.

## Technical Method
### Overall Framework and Principles

- Overall system architecture description
- Modules/components and their responsibilities
- Signal/data flow direction
- **Why this design?** Advantages over the intuitive/naive approach

### Core Component Details

- Model/algorithm architecture details (layers, dimensions, input/output)
- Training objective and loss function (write key equations)
- Training data source (synthetic/real/mixed, dataset names and scale)
- Key tricks and design decisions
- **Motivation for each design choice:** Why use A instead of B? Does the paper provide justification?

## Experimental Results

### Results (Facts)
- **Experimental setup:** Environment, hardware, hyperparameters
- **Baselines compared:** List specific method names and sources
- **Key results:** Quantitative improvement margins (specific numbers + percentages)
- **Ablation study:** Component contributions (removing X decreases performance by Y%)
- **Surprising findings:** Any counterintuitive results

### Analysis (Interpretation)
- Authors' explanation and attribution of results
- Which scenarios/datasets show best performance? Worst?
- Root cause of performance gains (authors' claims vs actual evidence)

## Critical Analysis
### Strengths
- Specific improvements over prior work (not just "good results")

### Limitations
- **Acknowledged by authors:**
- **My observations:** Issues not mentioned in the paper
  - Do assumptions hold in practice?
  - Are compute/data requirements reasonable?
  - Are evaluation metrics comprehensive?

### Reproducibility Assessment
- Is code open-sourced? Is data available?
- Are key implementation details sufficiently described?

## Summary
[shared section]
```

---

### Template B: Theoretical Paper

```markdown
## Basic Information
[shared section]

## Research Problem
[shared section]
- **Mathematical formulation:** Formal problem definition

## Key Insight
> Distill the paper's core theoretical contribution in 2-3 sentences. What new mathematical tool/perspective makes this result possible?

## Theoretical Framework
### Problem Formalization
- Symbol definitions and notation conventions
- Core mathematical definitions

### Main Theorems and Proof Sketches
- **Theorem 1:** Statement + key proof idea (not full proof, but key steps and key lemmas)
- **Theorem 2:** ...
- Key techniques used in proofs: Why does this technique work? Is there a more intuitive explanation?

### Theoretical Analysis
- Implications and intuitive interpretation of results (restate in non-mathematical language)
- Tightness of upper/lower bounds
- Relationship to and comparison with known results: Which bound was improved? Which assumption was relaxed?

## Validation (if experiments exist)
- Experimental setup
- Comparison of theoretical predictions vs actual results
- How is the gap between theory and experiments explained?

## Critical Analysis
### Strengths
- Importance and novelty of the theoretical contribution

### Limitations
- **Acknowledged by authors:**
- **My observations:** Reasonableness of assumptions, practical utility, difficulty of generalization

## Summary
[shared section]
```

---

### Template C: Survey Paper

```markdown
## Basic Information
[shared section]
- **Coverage:** Number of papers surveyed, time span

## Research Problem
[shared section]

## Key Insight
> What is the core contribution of this survey? What classification perspective was proposed, or what important trends were identified?

## Taxonomy

- Main classification dimensions and rationale for their selection
- Category definitions and representative works

### Direction 1: [Name]
- Key methods and advances
- Representative works (author, year)
- Pros and cons
- **Current bottleneck:** The core challenge facing this direction

### Direction 2: [Name]
- ...

### Method Comparison
| Method Type | Strengths | Weaknesses | Representative Works | Best Use Case |
|-------------|-----------|------------|---------------------|---------------|
| ... | ... | ... | ... | ... |

## Open Problems and Trends
- Current major challenges in the field
- Emerging trends and directions
- Authors' predictions and recommendations
- **Most promising direction:** Based on the survey analysis, which direction deserves most attention? Why?

## Critical Analysis
- Is the survey's coverage comprehensive? Any important directions missed?
- Is the taxonomy reasonable? Could it be organized better?
- Do the authors' opinions/biases affect the survey's objectivity?

## Summary
[shared section]
```

---

### Template D: Systems Paper

```markdown
## Basic Information
[shared section]

## Research Problem
[shared section]
- **Design goals:** Key requirements the system must meet

## Key Insight
> What is the core design insight of this system? What trade-off or observation makes this design superior to existing solutions?

## System Design
### Architecture Overview

- Overall architecture and component breakdown
- Component responsibilities and interfaces

### Key Design Decisions
- Decision 1: What choice was made, why (and not the alternative)
- Decision 2: Trade-offs considered (performance vs complexity vs maintainability)
- Key differences from existing systems

### Implementation Details
- Key tech stack/dependencies
- Optimization techniques
- Fault tolerance / scalability design

## Performance Evaluation

### Experimental Facts
- **Benchmark setup:** Environment, hardware, workloads
- **Compared systems:**
- **Key metrics:** Throughput, latency, resource usage (specific numbers)
- **Scalability:** Performance as scale increases

### Result Interpretation
- Under what conditions does it perform best? When does it degrade?
- Root cause of performance advantages

## Deployment Experience (if available)
- Real-world production performance
- Problems en

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Mizoreww](https://github.com/Mizoreww)
- **Source:** [Mizoreww/awesome-claude-code-config](https://github.com/Mizoreww/awesome-claude-code-config)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-mizoreww-awesome-claude-code-config-paper-reading
- Seller: https://agentstack.voostack.com/s/mizoreww
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.