Paper To Course

Paper-to-Course

Transform any academic or research paper into a stunning, interactive single-page HTML course. The output is a single self-contained HTML file (no dependencies except Google Fonts) that teaches the paper's ideas through scroll-based modules, animated visualizations, embedded quizzes, and plain-English translations of equations and academic jargon.

First-Run Welcome

When the skill is first triggered and the user hasn't specified a paper yet, introduce yourself and explain what you do:

> I can turn any research paper into an interactive course that teaches its key ideas — no academic background required. > > Just point me at a paper: > - A PDF file — e.g., "turn ./attention-is-all-you-need.pdf into a course" > - An arXiv link — e.g., "make a course from https://arxiv.org/abs/1706.03762" > - A paper title — e.g., "make a course about the Transformer paper" > - A pasted abstract or excerpt — if you have the text handy > > I'll read through the paper, extract the key ideas, and generate a beautiful single-page HTML course with animated diagrams, plain-English equation explanations, and interactive quizzes. The whole thing runs in your browser — no setup needed.

If the user provides an arXiv link, fetch the PDF first. If they provide a local PDF path, read it directly. If they give a paper title, search for it and confirm before proceeding.

Who This Is For

The target learner is a curious non-expert — someone who encountered an interesting paper (shared on social media, referenced in a blog post, cited in a meeting) and wants to actually understand what it says. They might be a product manager trying to evaluate whether a new technique is relevant, a journalist covering a scientific breakthrough, a student encountering a field for the first time, or simply a curious person who refuses to accept "just trust the experts."

Assume no domain expertise. Every technical concept — from p-values to attention mechanisms to gene expression — needs to be explained in plain language as if the learner has never encountered it. No jargon without definition. No "as is well-known in the literature." The tone should be like a brilliant friend who happens to have a PhD explaining things over coffee, not a professor lecturing.

Their goals are practical, not academic:

• Understand the core claim — what did the researchers actually find, and why does it matter?
• Follow the reasoning — how did they get from question to answer? What evidence supports the conclusion?
• Think critically — what are the limitations? What did the paper NOT prove? Where might the authors be wrong?
• Join the conversation — acquire enough vocabulary and understanding to discuss the paper intelligently with experts, write about it, or decide whether it's relevant to their work
• Build intuition — develop a mental model of the domain so future papers in the area are less intimidating
• Spot oversimplifications — when someone on Twitter says "this paper proves X," know enough to evaluate whether that's actually what it says

They are NOT trying to become researchers. They want understanding as a superpower that amplifies what they're already good at. They don't need to reproduce the experiments — they need to grasp the ideas, evaluate the evidence, and explain the significance.

Why This Approach Works

Academic papers are written for other researchers — dense, jargon-heavy, and structured for peer review, not comprehension. This skill inverts that: instead of starting with methodology and building toward results (the way papers are written), we start with what the researchers found and why you should care, then peel back the layers to show how they got there.

The learner already has something traditional students don't — motivation. They found this paper because something about it is relevant to their life. The course meets them where they are: "You've heard that [X technique] is changing [Y field]. Here's what's actually going on under the hood."

Every module answers "why should I care?" before "how does it work?" The answer is always practical: because this finding affects how you think about [topic], or because understanding this method helps you evaluate claims in the news, or because this concept shows up everywhere once you know what to look for.

The single-file constraint is intentional: one HTML file means zero setup, instant sharing, works offline, and forces tight design decisions.

---

The Process (4 Phases)

Phase 1: Paper Analysis

Before writing any HTML, deeply understand the paper. Read it carefully, extract the core argument, map the logical structure, and identify what makes it significant. Thoroughness here pays off — the more you understand, the better the course.

What to extract:

• The central claim — what is the paper arguing or demonstrating? State it in one plain sentence.
• The motivation — what problem existed before this paper? Why did the authors care?
• The key concepts — the main ideas, techniques, or theories the paper introduces or builds on. These are the "cast of characters" for the course.
• The methodology — how did the researchers test their claim? What experiments, proofs, or analyses did they use?
• The evidence chain — what results support the claim? Key figures, tables, statistics.
• The limitations and caveats — what does the paper NOT prove? What assumptions did the authors make?
• The significance — why does this paper matter? What changed because of it? Who cited it and why?
• The related work — what came before, and how does this paper build on or differ from prior work?

Figure out what the paper is about yourself by reading the abstract, introduction, conclusion, and key figures first (the "three-pass" approach). Don't ask the user to explain the paper — they may not fully understand it either. The course should open by explaining what the paper discovered in plain language (a brief "here's what this research found and why it's exciting") before diving into how it works. The first module should start with a concrete, relatable hook — "Imagine you're trying to translate a sentence from English to French — here's the breakthrough that changed how computers do this."

Phase 2: Curriculum Design

Structure the course as 5-8 modules. The arc always starts from what the learner already knows (the real-world problem) and moves toward what they don't (the paper's solution and evidence). Think of it as zooming in: start wide with the impact, then progressively peel back layers.

| Module Position | Purpose | Why it matters for a non-expert | |---|---|---| | 1 | "Here's what this paper found — and why you should care" | Start with the discovery and its real-world impact. Ground everything in something concrete the learner can relate to. | | 2 | Meet the key concepts | Know the building blocks so you can follow the argument and recognize these ideas elsewhere | | 3 | The problem before this paper | Understand what wasn't working so the solution makes sense — and appreciate why this was hard | | 4 | How they solved it (the method) | Follow the researchers' approach step-by-step, building intuition for what "doing research" looks like | | 5 | The evidence (results and experiments) | See the proof — learn to read figures, evaluate statistics, and judge whether the evidence is convincing | | 6 | What it doesn't prove (limitations) | Build critical thinking — every paper has boundaries, assumptions, and open questions | | 7 | The big picture (impact and future) | See how this fits into the larger field and what it means going forward |

Not every paper needs all 7. A short, focused paper might only need 4-5 modules. A foundational paper with wide impact might need 8. Adapt the arc to the paper's complexity — use your judgment on which modules are worth including based on what would actually help the learner understand and evaluate the work.

The key principle: Every module should connect back to a practical skill — understanding claims, evaluating evidence, thinking critically, joining conversations. If a module doesn't help the learner DO something better with this knowledge, cut it or reframe it until it does.

Each module should contain:

• 3-6 screens (sub-sections that flow within the module)
• At least one equation/jargon↔English translation (or paper excerpt↔plain English)
• At least one interactive element (quiz, visualization, or animation)
• One or two "insight" callout boxes with transferable thinking skills
• A metaphor that grounds the technical concept in everyday life — but NEVER reuse the same metaphor across modules, and NEVER default to the "factory" or "assembly line" metaphor (it's overused). Pick metaphors that organically fit the specific concept.

Mandatory interactive elements (every course must include ALL of these):

• Expert Roundtable Animation — at least one across the course. These are chat-style conversations between key concepts personified, or between "researchers" debating the paper's approach. They make abstract ideas feel like a conversation the learner can follow.
• Research Pipeline / Methodology Flow Animation — at least one across the course. The step-by-step animation showing how data flows through the research process — from question to data collection to analysis to conclusion. Every paper has a methodology pipeline — animate it.
• Equation/Jargon ↔ Plain English Translation Blocks — at least one per module. The left panel shows the actual equation, formula, or dense academic passage. The right panel gives a line-by-line plain English explanation. This is the core teaching tool.
• Quizzes — at least one per module (multiple-choice, scenario, drag-and-drop, or "spot the flaw" — any quiz type counts).
• Glossary Tooltips — on every technical term, first use per module.

These five element types are the backbone of every course. Other interactive elements (concept maps, layer toggles, comparison cards, etc.) are optional and should be added when they fit. But the five above must ALWAYS be present — no exceptions.

Do NOT present the curriculum for approval — just build it. The user wants a course, not a planning document. Design the curriculum internally, then go straight to generating the HTML. If they want changes, they'll tell you after seeing the result.

Phase 3: Build the Course

Generate a single HTML file with embedded CSS and JavaScript. Read references/design-system.md for the complete CSS design tokens, typography, and color system. Read references/interactive-elements.md for implementation patterns of every interactive element type.

Build order (task by task):

1. Foundation first — HTML shell with all module sections (empty), complete CSS design system, navigation bar with progress tracking, scroll-snap behavior, keyboard navigation, and scroll-triggered animations. After this step, you should have a working skeleton you can scroll through.

1. One module at a time — Fill in each module's content, translations, and interactive elements. Don't try to write all modules in one pass — the quality drops. Build Module 1, verify it works, then Module 2, etc.

1. Polish pass — After all modules are built, do a final pass for transitions, mobile responsiveness, and visual consistency.

Critical implementation rules:

• The file must be completely self-contained (only external dependency: Google Fonts CDN)
• Use CSS scroll-snap-type: y proximity (NOT mandatory — mandatory traps users in long modules)
• Use min-height: 100dvh with 100vh fallback for sections
• Only animate transform and opacity for GPU performance
• Wrap all JS in an IIFE, use passive: true on scroll listeners, throttle with requestAnimationFrame
• Include touch support for drag-and-drop, keyboard navigation (arrow keys), and ARIA attributes
• Render equations using HTML/CSS (styled spans with proper symbols) — do NOT depend on MathJax or KaTeX CDNs to keep the file self-contained. For complex equations, use Unicode math symbols and careful CSS positioning.

Phase 4: Review and Open

After generating the course HTML file, open it in the browser for the user to review. Walk them through what was built and ask for feedback on content, design, and interactivity.

---

Content Philosophy

These principles are what separate a great course from a generic tutorial. They should guide every content decision:

Show, Don't Tell — Aggressively Visual

People's eyes glaze over text blocks. The course should feel closer to an infographic than a textbook. Follow these hard rules:

Text limits:

• Max 2-3 sentences per text block. If you're writing a fourth sentence, stop and convert it into a visual instead.
• No text block should ever be wider than the content width AND taller than ~4 lines. If it is, break it up with a visual element.
• Every screen must be at least 50% visual (diagrams, equation blocks, cards, animations, badges — anything that isn't a paragraph).

Convert text to visuals:

• A list of 3+ items → cards with icons (concept cards, finding cards)
• A sequence of steps → flow diagram with arrows or numbered step cards
• "Concept A relates to Concept B" → animated relationship flow or expert roundtable visualization
• "This equation means X" → equation↔English translation block (not a paragraph about the equation)
• Comparing two approaches → side-by-side columns with visual contrast
• Experimental results → animated chart or figure recreation with annotations explaining what to look at
• Study timeline or process → methodology pipeline animation

Visual breathing room:

• Use generous spacing between elements (--space-8 to --space-12 between sections)
• Alternate between full-width visuals and narrow text blocks to create rhythm
• Every module should have at least one "hero visual" — a diagram, animation, or interactive element that dominates the screen and teaches the core concept at a glance

Equation/Jargon ↔ Plain English Translations

Every equation, formula, or dense academic passage gets a side-by-side plain English translation. Left panel: the original notation or text with proper formatting. Right panel: line-by-line plain English explaining what each part means and why it matters. This is the single most valuable teaching tool for non-expert learners.

Critical: Explain the intuition, not just the symbols. Don't just say "sigma means sum" — say "Add up the following for every single data point in our dataset — like going through a checklist one item at a time." The explanation should build a mental picture.

Critical: Use the paper's original notation exactly as-is. Never simplify or alter equations from the paper. The learner should be able to look at the actual paper and recognize the same notation they learned from — that builds confidence. Instead of modifying equations to make them simpler, choose the most illustrative equations (the ones that capture the core idea) and explain those deeply, rather than trying to cover every equation in the paper.

One Concept Per Screen

No walls of text. Each screen within a module teaches exactly one idea. If you need more space, add another screen — don't cram.

Metaphors First, Then Reality

Introduce every new concept with a metaphor from everyday life. Then immediately ground it: "In the paper, this looks like..." The metaphor builds intuition; the actual notation grounds it in reality.

Critical: No recycled metaphors. Do NOT default to "factory" or "assembly line" for everything — those are the #1 crutch. Each concept deserves its own metaphor that feels natural to that specific idea. Neural attention is a spotlight in a crowded room. A loss function is a GPS recalculating your route. Gradient descent is rolling

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cyyeh
• Source: cyyeh/skills-playground
• License: Apache-2.0
• Homepage: https://cyyeh.github.io/skills-playground/

Install and usage instructions live in the source repository linked above.