# Read Research Paper > Renders ANY research paper (URL / arXiv ID / DOI / PDF / pasted text) into a visually engaging multi-format reading experience — with mind maps, method flowcharts, key-finding infographics, comparison tables, related-work timelines, and a plain-English layer alongside the technical content. Activates on slash commands (`/read-research-paper`, `/read-paper`, `/explain-paper`, `/visualize-paper`) and natural-language requests like "read this research paper [URL]", "explain this paper [URL]", "make this paper visual [URL]". Caches every fetched paper locally so re-asks are instant. Ships with a bundled corpus of canonical papers for offline fallback. Hands off to `research-paper` for citation reuse and to `get-research-paper` for related-work expansion. Runtime-neutral. - Skill: `aniketkrs/read-research-paper` (Agent Skill, multi-file: 28 files) - Install (CLI): `npx skillmds@latest add aniketkrs/read-research-paper` - Raw SKILL.md: https://api.skillmd.com/api/skills/aniketkrs/read-research-paper/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - License: MIT - Author: aniketkrs (https://skillmd.com/u/aniketkrs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/aniketkrs/read-research-paper --- # Read Research Paper Where the other two skills do this: | Skill | What it does | |---|---| | `get-research-paper` | **FINDS** real papers on a topic | | `research-paper` | **WRITES** new papers | | **`read-research-paper`** (this) | **READS** ONE paper and makes it engaging | Give it a URL, arXiv ID, DOI, or pasted text. It produces a visual, multi-layer rendering: technical depth + plain English + mind maps + method flowcharts + key-finding infographics + comparison tables + related-work timelines. This file is the **entry point**. Heavier guidance lives in topic folders and is loaded on demand. --- ## 1. When to activate ### Slash commands | Command | What it does | | ---------------------------- | ----------------------------------------- | | `/read-research-paper ` | Full visual rendering (default) | | `/read-paper ` | Alias | | `/explain-paper ` | Same, with extra plain-English layer | | `/visualize-paper ` | Same, emphasizing visuals over prose | | `/tldr-paper ` | One-page infographic summary only | `` can be: - A URL: `https://arxiv.org/abs/2403.01234`, `https://doi.org/...`, `https://example.com/paper.pdf`, journal landing page, etc. - An arXiv ID: `2403.01234` or `cs.LG/0701002` - A DOI: `10.1145/3589334` - Pasted text: the paper's abstract or full body - **A local file** in any supported format (see below). ### Supported file formats The skill reads **any of these** as input: | Format | Extensions | Library used | Always available? | | --------- | ---------------------- | --------------------------- | ----------------------- | | Markdown | `.md`, `.markdown` | stdlib | yes | | Plain text | `.txt` | stdlib | yes | | LaTeX | `.tex`, `.latex` | stdlib + regex de-LaTeX | yes | | JSON | `.json` | stdlib | yes | | HTML | `.html`, `.htm` | beautifulsoup4 (or regex) | yes (regex fallback) | | CSV / TSV | `.csv`, `.tsv` | pandas (or stdlib) | yes (basic via stdlib) | | RTF | `.rtf` | striprtf (or regex) | yes (regex fallback) | | **PDF** | `.pdf` | pdfplumber / pypdf | install one | | **DOCX** | `.docx` | python-docx | install | | **PPTX** | `.pptx` | python-pptx | install | | **XLSX** | `.xlsx`, `.xls` | pandas + openpyxl | install | | **EPUB** | `.epub` | ebooklib | install | | **Images** | `.png`, `.jpg`, `.tiff`, `.bmp` | pytesseract + PIL | install (OCR) | One-line install for everything: ```bash pip install pdfplumber python-docx python-pptx pandas openpyxl \ beautifulsoup4 striprtf ebooklib pytesseract Pillow ``` (Plus install Tesseract OCR system-wide for images.) The reader is `toolchains/read_any_file.py`. Self-test: ```bash python toolchains/read_any_file.py --self-test python toolchains/read_any_file.py --list-formats ``` Full reference: `sources/file-formats.md`. ### Common options | Option | Default | Effect | | ------------------- | ----------- | ------------------------------------------- | | `--depth` | `standard` | quick / standard / deep | | `--audience` | `mixed` | academic / technical / general / mixed | | `--visuals` | `auto` | auto / max / minimal / none | | `--include-figures` | `true` | Try to extract / re-create paper's own figures | | `--cache` | `true` | Use local cache (auto-fill on re-asks) | | `--language` | `en` | Plain-English language | | `--out` | `.//` | Working directory | | `--with-related` | `false` | Trigger `get-research-paper` for related work | | `--with-handoff` | `false` | Emit bibliography.yaml for `research-paper` | ### Natural-language patterns - "read this research paper " - "explain this paper " - "make this paper visual " - "I want to understand this paper " - "summarize this paper " - "tldr this paper " - "what does this paper say " ### Negative activation Do NOT activate for: - Requests to **find** papers on a topic (route to `get-research-paper`). - Requests to **write** a new paper (route to `research-paper`). - Pasted prose without a paper-shaped input ("here's an article…"). - Casual questions about a topic that don't reference a specific paper. --- ## 2. Output contract Every run produces: 1. **`paper-visual.md`** — the headline deliverable. Multi-layer: - One-page **infographic** at the top (mind map + key numbers). - **TL;DR** in 5–8 sentences. - **Plain-English summary** in 5–10 sentences. - **Section-by-section walk-through** with each section preceded by a 1-paragraph plain-English version, then the technical content with extracted / generated visuals. - **Method flowchart** (Mermaid). - **Key findings infographic** (charts with the paper's headline numbers). - **Comparison table** to baselines (when present). - **Related work timeline** (when references are available). - **"Why this matters" footer**. 2. **`paper-data.json`** — structured extracted metadata: title, authors, year, abstract, sections, figures, tables, key numbers, references. Schema in `schemas/visual-paper.json`. 3. **`figures/`** — generated charts / diagrams / mind maps as PNG + SVG + Mermaid sources. 4. **`cache/.json`** — cached for re-use. 5. **`Known-gaps.md`** — anything that couldn't be fetched / parsed. If `--with-handoff` is set, also produces `bibliography.yaml` ready for the `research-paper` skill. If `--with-related` is set, the orchestrator dispatches `get-research-paper` on the paper's key topics to seed a related-work section. --- ## 3. Operating principles 0. **Anchor to TODAY's date.** When the input is a topic-style query (rather than a specific URL/DOI/path), determine today's actual date first (via `date -u +%Y-%m-%d`, runtime context, or asking the user). For a specific paper input, the freshness check compares the paper's publication date to today and flags stale findings. Full protocol: `instructions/freshness.md`. 1. **Don't bluff.** If a URL doesn't resolve or a PDF can't be parsed, say so. Mark `[FETCH FAILED — fallback to cache | model knowledge | corpus]` and surface in `Known-gaps.md`. 2. **Cache everything.** Every successfully fetched paper is written to `~/.agents/skills/read-research-paper/cache/`. Re-asks are instant. 3. **Ship the corpus.** A small bundled corpus of canonical papers (`corpus/anchor-papers.yaml`) is searched first when the input is a topic-style query rather than a specific paper. 4. **Visual-by-default.** Generate at minimum: 1 mind map + 1 method flowchart + 1 key-findings figure + 1 comparison table. 5. **Dual register.** Every section has BOTH plain-English and technical content. Never strip the technical depth — augment with simpler language alongside. 6. **Honest interpretation.** Don't oversell findings. Match the paper's own certainty. If the paper hedges, the visual paper hedges. --- ## 4. Top-level workflow ``` intake → fetch → parse → extract-figures-and-data → plan-visuals → render → assemble → cache → output ``` Each phase has a dedicated playbook. Master pipeline: **`workflows/ingestion.md`**. --- ## 5. Source detection The skill auto-detects input type: | Input pattern | Path | | ----------------------------------------------- | ------------------------------------------ | | `arxiv.org/abs/...` | arXiv API | | `\d{4}\.\d{4,5}` (bare arXiv ID) | arXiv API | | `doi.org/...` or `10\..../...` | Crossref → URL → fetch | | `*.pdf` (URL or local path) | PDF extraction | | Journal landing page URL | URL scrape + Crossref enrichment | | Pasted text (no URL) | Treat as paper body; build structure heuristically | See `workflows/ingestion.md §1`. --- ## 6. Three-tier fallback ``` 1. Local cache (~/.agents/skills/read-research-paper/cache/) ├── Hit → return immediately (instant) └── Miss → next tier 2. Live fetch (arXiv API / Crossref / WebFetch / PDF parser) ├── Success → render + cache └── Fail → next tier 3. Bundled corpus (corpus/anchor-papers.yaml) ├── Hit → return + flag as "from bundled corpus" └── Miss → next tier 4. Model knowledge ├── Confident → render + flag every fact [UNVERIFIED — offline] └── Not confident → fail honestly with a Known-gaps entry ``` Every tier transition is logged in `Known-gaps.md` so the user knows where the rendered paper came from. --- ## 7. Visual rendering plan For every paper, the skill produces: | Visual | Source | Renderer | | ------------------------ | ------------------------------------ | ------------------------------ | | **Mind map** | Paper structure (sections + key ideas) | Mermaid `mindmap` | | **Method flowchart** | Method section | Mermaid `flowchart` | | **Key-findings infographic** | Headline numbers from results | matplotlib if available, else Markdown table | | **Comparison table** | Paper's own benchmark table | Markdown table | | **Related-work timeline** | References + their years | Mermaid `gantt`-style timeline | | **Author network** | Authors + affiliations | Mermaid `flowchart` (small) | | **Concept map** | Paper's terminology | Mermaid `mindmap` | | **Figure re-captions** | Original figures (when extractable) | Pass-through with new captions | Decision logic: `workflows/visualization.md`. --- ## 8. Cache architecture The cache lives at: ``` ~/.agents/skills/read-research-paper/cache/ ├── manifest.json # index of all cached papers ├── arxiv/ │ ├── 2403.01234.json │ └── 2005.11401.json ├── doi/ │ ├── 10.1145_3589334.json │ └── ... ├── url/ │ └── .json └── topics/ └── .json # topic → list of cached paper IDs ``` When the user asks about a topic (not a specific paper), the cache's `topics/` index is searched first, before any live fetch. Cache schema: `workflows/caching.md`. --- ## 9. Bundled corpus Ships in `corpus/`: - `anchor-papers.yaml` — ~30 canonical, high-impact papers across major topics (transformers, RAG, RLHF, contrastive learning, RCT methodology, PRISMA, etc.). - `topics-index.yaml` — maps topic keywords to the anchor papers. When the user asks for a paper that's in the corpus, the skill uses the corpus version (always available, even offline). Users can extend the corpus by adding files to `corpus/user/`. --- ## 10. Failure handling - **URL doesn't resolve** → try arXiv ID extraction, then DOI lookup, then surface in `Known-gaps.md`. - **PDF unparseable** → fall back to abstract-only rendering with a warning. - **Model couldn't extract figures** → generate Mermaid alternatives. - **No headline numbers in results** → use qualitative findings. - **Web tools unavailable** → cache + corpus + model-knowledge in that order. Full matrix: `workflows/ingestion.md §10`. --- ## 11. Where to look next - **Plan an ingestion** → `workflows/ingestion.md` - **Pick visuals** → `workflows/visualization.md` - **Cache protocol** → `workflows/caching.md` - **Plain-English layer** → `prompts/plain-english.md` - **Mind-map generation** → `prompts/generate-mindmap.md` - **Output format** → `templates/visual-paper.md` - **Bundled corpus** → `corpus/` - **Fetch tools** → `toolchains/fetch_paper.py`, `toolchains/extract_pdf.py` This skill complements but does not require the other two: - `get-research-paper` → **find** papers - `research-paper` → **write** papers - `read-research-paper` → **read** papers (this one)