Study

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)

bashCopy code
if [ ! -f "${CLAUDE_PLUGIN_ROOT}/.installed" ]; then
  echo "First run - installing dependencies..."
  cd "${CLAUDE_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_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

bashCopy code
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_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:

bashCopy code
PARSE_OUTPUT_DIR=$(mktemp -d)
node ${CLAUDE_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:

bashCopy code
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:

Copy code
~/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:

markdownCopy code
### 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:

Copy code
~/claude-papers/papers/{paper-slug}/code/

Create the code directory first:

bashCopy code
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.pyCheck Domain?
• vectorized_planning_demo.pyCheck Domain?
• 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:

Copy code
~/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

bashCopy code
mkdir -p ~/claude-papers/papers/{paper-slug}/images

python3 ${CLAUDE_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:

jsonCopy code
{"papers": []}

Append new entry to the papers array:

jsonCopy code
{
  "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:

Copy code
~/claude-papers/index.json

Step 8: Relaunch Web UI

Invoke:

Copy code
/claude-paper:webui

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.mdCheck Domain?
• math-derivation-breakdown.mdCheck Domain?
• comparison-with-transformers.mdCheck Domain?
• extension-ideas.mdCheck Domain?

If user provides their own summary:

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

• user-summary-v1.mdCheck Domain?

If iterated:

• user-summary-v2.mdCheck Domain?

If user wants structured consolidation:

Create:

• consolidated-notes.mdCheck Domain?
• study-session-1.mdCheck Domain?
• exam-review.mdCheck Domain?

This makes the paper folder a growing knowledge node.