---
name: claude-paper-study
description: Use this skill when the user wants to read, study, analyze, or deeply understand a research paper (PDF).
allowed-tools: Bash, Write, Edit, Read
---

## Cross-Agent Compatibility

> This file is generated from the existing Claude Paper Skill. Its workflow and output requirements are unchanged; only equivalent host metadata, the plugin-root variable, and cross-skill invocation are adapted.

Resolve `CLAUDE_PAPER_PLUGIN_ROOT` to the absolute `plugin/` directory in this package before each shell invocation. From this `SKILL.md`, that directory is `../../../plugin`.
Treat every `${CLAUDE_PAPER_PLUGIN_ROOT}` reference below as that resolved absolute directory. Do not substitute the current workspace root.

When this workflow asks to launch the viewer, load and follow the `claude-paper-webui` skill.

---

# Paper Study Workflow

Invoke this skill with a paper PDF path.

**Language Detection**: Detect the user's language from their input and generate ALL materials in that language.
- Example: User says "我们学习一下这篇论文吧" → Generate materials in Chinese
- Example: User says "Let's study this paper" → Generate materials in English

---

# Core Philosophy

Primary Objective:
Facilitate deep conceptual understanding and research-level thinking.

Secondary Objective:
Create a structured, reusable paper knowledge system.

This workflow is not just for summarizing — it builds a learning environment around the paper.

---

# Step 0: Check Dependencies (First Run Only)

```bash
if [ ! -f "${CLAUDE_PAPER_PLUGIN_ROOT}/.installed" ]; then
  echo "First run - installing dependencies..."
  cd "${CLAUDE_PAPER_PLUGIN_ROOT}"
  npm install || exit 1

  # Install Python dependencies for image extraction
  python3 -m pip install pymupdf --user 2>/dev/null || pip3 install pymupdf --user 2>/dev/null || echo "Warning: Failed to install pymupdf"

  touch "${CLAUDE_PAPER_PLUGIN_ROOT}/.installed"
  echo "Dependencies installed!"
fi
```

Recommended:

* Node >= 18
* Python 3 with pip (for image extraction)

---

# Step 1: Download and Parse PDF

Supports multiple input formats:

* **Local path**: `~/Downloads/paper.pdf`
* **Direct PDF URL**: `https://arxiv.org/pdf/1706.03762.pdf`
* **arXiv URL**: `https://arxiv.org/abs/1706.03762`

## Step 1a: Check input type and download if URL

```bash
USER_INPUT="<user-input>"

# Check if input is a URL (starts with http:// or https://)
if [[ "$USER_INPUT" =~ ^https?:// ]]; then
  # Download PDF from URL
  INPUT_PATH=$(node ${CLAUDE_PAPER_PLUGIN_ROOT}/skills/study/scripts/download-pdf.cjs "$USER_INPUT")
else
  # Use local path directly
  INPUT_PATH="$USER_INPUT"
fi
```

For URLs, the download script will:
* Download PDFs to `/tmp/claude-paper-downloads/`
* Convert arXiv `/abs/` URLs to PDF URLs automatically
* Validate that URLs point to PDF files
* Return the local file path for processing

For local paths, use the path directly without downloading.

## Step 1b: Parse PDF

Extract structured information:

```bash
PARSE_OUTPUT_DIR=$(mktemp -d)
node ${CLAUDE_PAPER_PLUGIN_ROOT}/skills/study/scripts/parse-pdf.js \
  "$INPUT_PATH" \
  --output-dir "$PARSE_OUTPUT_DIR"
```

The command prints a small, strict JSON summary to stdout and writes:

* `meta.json` — title, authors, abstract, links, page count, and a context-safe content preview
* `paper.txt` — complete extracted text without the 50k preview limit

Use `paper.txt` as the source for generating materials. Search it and read relevant sections as needed; do not treat `meta.json.content` as the complete paper when `contentTruncated` is true.

After choosing `{paper-slug}`, create the paper directory and copy both parser artifacts plus the original PDF:

```bash
mkdir -p ~/claude-papers/papers/{paper-slug}
cp "<metaPath-from-parser-output>" ~/claude-papers/papers/{paper-slug}/meta.json
cp "<fullTextPath-from-parser-output>" ~/claude-papers/papers/{paper-slug}/paper.txt
cp "$INPUT_PATH" ~/claude-papers/papers/{paper-slug}/paper.pdf
```

Generate exactly 2 tags in Step 2.5 and add them to the saved `meta.json`.

Fallback:
If structured parsing fails, extract raw text and continue with degraded structure.

---

# Step 2: Assess Paper Before Generating Materials

Before generating any files, evaluate:

1. Difficulty Level

   * Beginner
   * Intermediate
   * Advanced
   * Highly Theoretical

2. Paper Nature

   * Theoretical
   * Architecture-based
   * Empirical-heavy
   * System design
   * Survey

3. Methodological Complexity

   * Simple pipeline
   * Multi-stage training
   * Novel architecture
   * Heavy mathematical derivation

This assessment determines:

* Whether to create method.md
* Whether to create .ipynb
* Explanation depth
* Code demo complexity

---

# Step 2.5: Generate Exactly 2 Semantic Tags (Mandatory)

Before generating files, infer exactly 2 tags from semantic understanding of the paper.

Rules:

* Generate exactly 2 tags, no more and no less
* Tags must be distinct
* Each tag should be short (1-3 words)
* Avoid generic tags: `paper`, `research`, `ai`, `ml`
* Prefer one tag for problem/domain and one for method/core idea

Examples:

* `machine translation`, `self-attention`
* `3d detection`, `bev transformer`
* `protein folding`, `structure prediction`

Persist these 2 tags in both locations:

* `~/claude-papers/papers/{paper-slug}/meta.json` as `tags`
* `~/claude-papers/index.json` entry as `tags`

---

# Step 3: Generate Core Study Materials

Create folder:

```
~/claude-papers/papers/{paper-slug}/
```

---

## Required Files

### README.md

* What the paper is about (one paragraph)
* Difficulty level
* How to navigate materials
* Key takeaways
* Estimated study time
* Folder structure overview

---

### summary.md

* Background context
* Problem statement
* Main contributions
* Key results
* Quantitative metrics

---

### insights.md (Most Important)

* Core idea explained plainly
* Why this works
* What conceptual shift it introduces
* Trade-offs
* Limitations
* Comparison to prior work
* Practical implications

---

### qa.md

15 questions:

* 5 basic
* 5 intermediate
* 5 advanced

Use this format:

```markdown
### Question

<details>
<summary>Answer</summary>

Detailed explanation.

</details>

---
```

---

## Conditional Files

### method.md (Recommended for most papers)

Include:

* Component breakdown
* Algorithm flow
* Architecture diagram (ASCII if needed)
* Step-by-step explanation
* Pseudocode (balanced with explanation)
* Implementation pitfalls
* Hyperparameter sensitivity
* Reproduction risks

---

### mental-model.md (Recommended for most papers)

* What type of problem is this?
* What prior knowledge is assumed?
* How it fits into the broader research map
* How to mentally categorize this work

---

### reflection.md (Optional auto-generated)

* If I were to extend this paper
* What open problems remain
* What assumptions are fragile
* Where it might fail in practice

---

# Step 4: Code Demonstrations (Mandatory)

At least one runnable demo must be created.

**All code demos must be placed in:**
```
~/claude-papers/papers/{paper-slug}/code/
```

Create the code directory first:

```bash
mkdir -p ~/claude-papers/papers/{paper-slug}/code
```

Guidelines:

* Self-contained
* Runnable independently
* Educational comments (explain why)
* Focus on core contribution
* Prefer clarity over completeness

Possible types:

* Simplified conceptual implementation
* Visualization script
* Minimal architecture demo
* Interactive notebook (.ipynb)

Name descriptively:

* model_demo.py
* vectorized_planning_demo.py
* contrastive_loss_visualization.ipynb

Avoid generic names.

---

# Step 5: Generate Interactive HTML Explorer

Create a single self-contained HTML file for interactively exploring the paper's core concepts.

**Output path:**
```
~/claude-papers/papers/{paper-slug}/index.html
```

## Requirements

* Single HTML file, all CSS/JS inline, zero external dependencies
* Uses **real data from the paper** (actual metrics, hyperparameters, comparisons) — never invent numbers
* Must work in a sandboxed iframe (no external fetches, no localStorage)

## Guidelines

Choose the interaction pattern that best fits the paper — architecture diagrams, parameter explorers, result dashboards, formula breakdowns, comparison matrices, etc. Let the paper's content dictate the format rather than forcing a fixed layout, focusing on the core ideas of the paper.

Every interactive control (slider, toggle, dropdown) should visibly change the visualization. Include brief explanatory text alongside interactive elements to teach concepts.

---

# Step 6: Extract Images

```bash
mkdir -p ~/claude-papers/papers/{paper-slug}/images

python3 ${CLAUDE_PAPER_PLUGIN_ROOT}/skills/study/scripts/extract-images.py \
  paper.pdf \
  ~/claude-papers/papers/{paper-slug}/images
```

Rename key images descriptively:

* architecture.png
* training_pipeline.png
* results_table.png

---

# Step 7: Update Index

**CRITICAL**: Read existing index.json first, then append the new paper. Never overwrite the entire file.

If index.json does not exist, create:

```json
{"papers": []}
```

Append new entry to the papers array:

```json
{
  "id": "paper-slug",
  "title": "Paper Title",
  "slug": "paper-slug",
  "authors": ["Author 1", "Author 2"],
  "abstract": "Paper abstract...",
  "year": 2024,
  "date": "2024-01-01",
  "tags": ["tag-1", "tag-2"],
  "githubLinks": ["https://github.com/..."],
  "codeLinks": ["https://..."]
}
```
**IMPORTANT**: The index.json file must be located at:
```
~/claude-papers/index.json
```

---


# Step 8: Relaunch Web UI

Load and follow the `claude-paper-webui` skill.


# Step 9: Interactive Deep Learning Loop

After all files are generated:

## Present to User:

1. Ask:

   * What part is still unclear?
   * Do you want deeper mathematical breakdown?
   * Do you want implementation-level analysis?
   * Do you want comparison with another paper?

2. Allow user to:

   * Ask deeper questions
   * Summarize their understanding
   * Propose new ideas

---

## If user asks deeper questions:

Generate a new file inside the same folder:

Examples:

* deep-dive-contrastive-loss.md
* math-derivation-breakdown.md
* comparison-with-transformers.md
* extension-ideas.md

---

## If user provides their own summary:

1. Refine it.
2. Improve structure.
3. Save as:

* user-summary-v1.md

If iterated:

* user-summary-v2.md

---

## If user wants structured consolidation:

Create:

* consolidated-notes.md
* study-session-1.md
* exam-review.md

---

This makes the paper folder a growing knowledge node.

---