Turn any academic paper or GitHub repository into a beautiful, single-file static HTML explainer page. Supports PDF, arxiv URLs, GitHub repos, and combined paper+code analysis — with code highlighting, KaTeX formulas, Mermaid diagrams, dark mode, and example-driven explanations that make readers feel they understand the content better than reading the original.
Install:
npx skills add ViviQuan/deep-explainerOr manually:
git clone https://github.com/ViviQuan/deep-explainer "$AGENT_SKILLS_DIR/deep-explainer"Set AGENT_SKILLS_DIR to your runtime's skills directory before manual install.
中文文档: README.zh-CN.md
/deep-explainer https://arxiv.org/abs/1706.03762
/deep-explainer https://github.com/karpathy/micrograd
/deep-explainer /path/to/paper.pdf
/deep-explainer https://arxiv.org/abs/2005.14165 --with-code https://github.com/karpathy/minGPT
The skill auto-detects input type, extracts content via CLI tools (pdftotext, pymupdf, pdfplumber — cascading fallbacks for any model), performs deep analysis, and generates one static HTML file.
| Feature | Details |
|---|---|
| 📄 Paper explainer | PDF, arxiv URL, pasted text → HTML |
| 💻 Code explainer | GitHub repo → core-file and key-function walkthrough |
| 🔗 Paper + Code | Cross-references paper formulas ↔ code implementations |
| 🎨 Modern tech blog style | Medium/Notion aesthetic, clean typography |
| 📑 Sidebar TOC | Auto-generated from headings, scroll-spy highlighting |
| 🌓 Dark mode | Toggle button, persisted to localStorage |
| 📱 Responsive | Sidebar collapses to floating button on mobile |
| 💻 Code highlighting | highlight.js with GitHub theme |
| 📐 Formula rendering | KaTeX (inline $...$ + block $$...$$) |
| 📊 Diagrams | Mermaid (flowcharts, architecture, sequence, class) |
| 🧮 Example-driven | Every method has concrete examples, numerical walkthroughs, analogies |
| 🔧 Robust PDF reading | Cascading CLI extraction: pdftotext → pymupdf → pdfplumber → arxiv HTML → native file/PDF reader → OCR |
Round 1: Identify Input → detect type (PDF / arxiv / GitHub / text)
Round 1.5: External Access → ask before installs, sudo, huge clones, private fetches
Round 2: Deep Reading → extract full content via CLI tools
Round 2.5: Evidence Gate → verify every claim has a source or mark it unknown
Round 2.75: Evidence Scope → disclose low-confidence mappings or omitted scope
Round 3: Structured Analysis → internal: innovations, modules, data flow
Round 4: Ask User → depth, code details, language
Round 5: Generate HTML → runtime file-write operation, single complete file
Round 6: Self-Review → static/render checks, fix issues
Many models cannot read PDFs natively. The skill uses CLI tools with automatic fallbacks:
| Priority | Method | When |
|---|---|---|
| 1 | pdftotext (poppler) |
Default — fastest, most reliable |
| 2 | pymupdf (fitz) |
Complex PDFs, embedded fonts |
| 3 | pdfplumber |
Best table preservation |
| 4 | arxiv HTML | For arxiv papers — structured, clean |
| 5 | Native file/PDF reader | Last resort — runtime-dependent |
| 6 | OCR (tesseract) | Scanned/image PDFs |
Each step includes auto-install (brew install poppler / pip install pymupdf)
and quality checks (title visible? abstract readable? <20% garbled?).
git clone --depth 1 <url> /tmp/repo
↓ fails?
GitHub API: /repos/{owner}/{repo}/git/trees/main?recursive=1
↓ rate-limited?
Browse web → read key files individually
A single static HTML file with:
┌──────────┬─────────────────────────────────┐
│ │ ┌─────────────┐ │
│ Sidebar │ auto │ Content │ auto │
│ (sticky) │ margin │ max 960px │ margin │
│ TOC nav │ │ centered │ │
│ │ └─────────────┘ │
└──────────┴─────────────────────────────────┘
- Header: fixed top bar with logo + dark mode toggle
- Sidebar: auto-generated TOC from h2/h3, scroll-spy active highlighting
- Content: centered in available space, 960px max-width
- Mobile: sidebar collapses to floating 📑 button
| Library | Purpose | CDN |
|---|---|---|
| KaTeX | Formula rendering | cdn.jsdelivr.net/npm/katex@0.16.9 |
| Mermaid | Diagrams | cdn.jsdelivr.net/npm/mermaid@10 |
| highlight.js | Code highlighting | cdn.jsdelivr.net/gh/highlightjs/cdn-release@11.9.0 |
No build step. No npm install. CSS is inline; KaTeX, Mermaid, and highlight.js load from CDN unless the runtime/user provides offline assets.
The skill enforces concrete examples at every level:
For papers — each innovation must have:
- A running example with specific input traced through the method
- A numerical walkthrough with actual numbers (not just symbols)
- An analogy connecting to real-world concepts
- A before/after comparison showing the impact
For code — each key function must have:
- Concrete input (shape, values, type)
- Line-by-line execution trace with intermediate values
- Output with interpretation
- "Why" explanation — what would happen if written differently
Every visible claim is backed by a small internal evidence ledger:
| Output item | Required evidence |
|---|---|
| Paper claim | Source section, figure, table, or equation |
| Code claim | Real file path plus line range or symbol name |
| Paper ↔ code mapping | Paper item, implementation location, confidence, mismatch note |
| Large repo scope | Included modules and omitted paths |
Unknown details are labeled as not found. The skill does not invent formulas, file paths, line numbers, figures, benchmark values, or implementation matches.
deep-explainer/
├── SKILL.md Agent-facing skill definition
├── README.md This file
├── README.zh-CN.md Chinese documentation
├── test-prompts.json Darwin validation prompts
└── references/
└── html-template.md Full HTML template (CSS + JS + usage guide)
| paper-analyzer | deep-explainer | |
|---|---|---|
| Input | Paper-first | Paper OR GitHub repo OR both |
| Code handling | Searches for related code | Clones repo, explains core files |
| Output focus | Paper method analysis | Code + theory, cross-referenced |
| HTML style | 3 style choices | Modern tech blog (Medium/Notion) |
| PDF reading | Native model read | CLI-first cascading (model-agnostic) |
| Examples | Optional | Mandatory — enforced by skill |
- For arxiv papers: the skill fetches both the abstract page and the full HTML version. HTML extraction is often cleaner than PDF.
- For large repos: the skill uses
git clone --depth 1and reads entry files + core implementations only, not every file. - Depth selection: "Quick overview" (~2000 English words / ~3000 CJK chars), "Standard" (~5000 English words / ~8000 CJK chars), "Deep dive" (~8000+ English words / ~12000+ CJK chars) for line-by-line code walkthrough.
- Language: supports Chinese (with English technical terms) or full English. Follows user's language by default.
MIT.