Paper Explainer Skill

English | 中文

PDF → personalized, interactive HTML tutorial — in one command.

A skill that transforms academic papers into tailored learning experiences. It interviews you about your goals and background, then generates a self-contained HTML page you can open in any browser.

Features

• Personalized interview — asks about your purpose, focus areas, background knowledge, and preferred depth before generating anything
• Interactive HTML output — dark-themed page with sidebar navigation, collapsible sections, step-by-step walkthroughs, tabs, tooltips, and lightbox image viewer
• Self-contained — all figures are base64-inlined; the output is a single HTML file with zero external dependencies
• Quiz section — multiple-choice and open-ended questions to verify understanding
• Smart PDF extraction — ML-based figure detection (LayoutParser + PubLayNet) with automatic fallback to heuristic detection
• Multi-language — automatically generates content in your language; English technical terms are preserved on first mention

Demo

HTML Output

See example/html/llm/ for complete outputs generated from Attention Is All You Need. Open the HTML files directly in your browser.

Interactive Interview

The skill asks 4 structured questions to understand what you need. Your answers directly shape the tutorial content — sections are expanded, condensed, or skipped based on your selections.

Quick Start

1. Install dependencies

# System dependency
brew install poppler          # macOS
# apt-get install poppler-utils  # Linux

# Python packages
pip install -r requirements.txt

2. Copy the skill into your project

your-project/
└── .claude/skills/
    └── paper-explainer/
        ├── SKILL.md                    ← Agent instructions (workflow, prompts, quality bar)
        ├── scripts/
        │   ├── extract_pdf_content.py  ← PDF extraction (text + figures + tables)
        │   └── bundle_html.py          ← Inline images into self-contained HTML
        └── assets/
            └── template.html           ← HTML design system (CSS + JS + components)

3. Invoke in coding agent

/paper-explainer @some_paper.pdf

Or simply ask the agent: "explain this paper", "create a tutorial for this PDF", etc.

Usage

The skill is invoked by an agent (Claude Code, Cursor, etc.) and follows a three-phase workflow:

1. Phase 1 — Extraction: Runs scripts/extract_pdf_content.py to extract text, tables, and figures from the PDF
2. Phase 2 — Interview: Agent asks the user 2-3 questions about their focus and background
3. Phase 3 — HTML Generation: Agent builds a self-contained HTML tutorial using assets/template.html

Example

The example/ directory contains a complete working example using Attention Is All You Need:

example/
├── articles/llm/
│   └── Attention Is All You Need.pdf    ← Input PDF
└── html/llm/
    ├── attention-is-all-you-need.html   ← English output
    └── attention-is-all-you-need-cn.html ← Chinese output

Open either HTML file directly in your browser to see the full interactive tutorial.

Dependencies

Required

pip install -r requirements.txt
# Installs: pymupdf, pdf2image, Pillow, numpy

Package	Purpose
PyMuPDF (fitz)	Text/table extraction, PDF structure analysis
poppler	PDF page rendering (correct transparency/gradient handling)
pdf2image	Python wrapper for poppler rendering
Pillow	Image cropping and processing
numpy	Array operations for image processing

Recommended (ML-based figure detection)

pip install torch
pip install --no-build-isolation 'git+https://github.com/facebookresearch/detectron2.git'
pip install layoutparser

Package	Purpose
torch	Deep learning runtime
detectron2	Object detection framework (must build from source)
layoutparser	ML-based document layout detection using PubLayNet model

The extraction script automatically falls back to heuristic caption-based figure detection when layoutparser is unavailable. Both paths use poppler for rendering, so figures are always correct.

LayoutParser Model Setup

The PubLayNet model (~330MB) is auto-downloaded from HuggingFace on first run and cached at ~/.cache/layoutparser/PubLayNet/faster_rcnn_R_50_FPN_3x/.

Known issue: layoutparser's built-in model download links (Dropbox) are broken. The extraction script works around this by downloading directly from the HuggingFace mirror nlpconnect/PubLayNet-faster_rcnn_R_50_FPN_3x. If auto-download fails (e.g. network restrictions), manually download config.yml and model_final.pth from that repo and pass the directory via --model-dir:

mkdir -p ~/.cache/layoutparser/PubLayNet/faster_rcnn_R_50_FPN_3x
cd ~/.cache/layoutparser/PubLayNet/faster_rcnn_R_50_FPN_3x
curl -LO https://huggingface.co/nlpconnect/PubLayNet-faster_rcnn_R_50_FPN_3x/resolve/main/config.yml
curl -LO https://huggingface.co/nlpconnect/PubLayNet-faster_rcnn_R_50_FPN_3x/resolve/main/model_final.pth

Platform Notes

• macOS (Apple Silicon): detectron2 must be built from source (--no-build-isolation). Ensure PyTorch is installed first.
• Linux: apt-get install poppler-utils instead of brew install poppler.
• Python version: 3.10 - 3.12 recommended. detectron2 may have issues on 3.13+.