SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsread-research-paper

read-research-paper

Writing & research

View repository

Updated 10-15 16:49

About this skill

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 <input> Full visual rendering (default)
/read-paper <input> Alias
/explain-paper <input> Same, with extra plain-English layer
/visualize-paper <input> Same, emphasizing visuals over prose
/tldr-paper <input> One-page infographic summary only

<input> 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:

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:

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 ./<paper-slug>/ 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/<paper-id>.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

  1. 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.
  2. 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.
  3. Cache everything. Every successfully fetched paper is written to ~/.agents/skills/read-research-paper/cache/. Re-asks are instant.
  4. 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.
  5. Visual-by-default. Generate at minimum: 1 mind map + 1 method flowchart + 1 key-findings figure + 1 comparison table.
  6. Dual register. Every section has BOTH plain-English and technical content. Never strip the technical depth — augment with simpler language alongside.
  7. 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/
│   └── <sha256-hash>.json
└── topics/
    └── <topic-slug>.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)