Understand the paper. Trace the mechanism. Explore the hard parts.
English · 简体中文 · Examples · Installation · Documentation
PaperUnfold is a pair of agent skills for researchers across disciplines. It turns readable papers into visual HTML guides and supports focused teaching through conversation. Explanations follow your conversation language and keep the paper's original terminology.
A summary can name a method without explaining how it works. PaperUnfold connects the research question, intermediate steps, evidence and conclusion. You get an overview first, then enough detail to follow the central mechanism or argument and choose where to go deeper.
| Skill | Purpose | Output |
|---|---|---|
paper-guide |
Understand the paper's main thread, mechanism and evidence. | A single-file HTML guide with diagrams, formulas and source links. |
paper-tutor |
Work through a selected concept, mechanism or argument. | Focused dialogue and a saved learning-progress record. |
Use either skill independently, or copy a learning prompt from a guide into your agent conversation.
- Mechanism explanations. Follow inputs, operations, outputs, conditions and the role of each central step.
- Visual reading. Method papers use connected pipelines. Empirical and theoretical papers use study-design or argument maps. Relevant formulas and result tables support the explanation.
- Traceable evidence. Check claims against observed source locations. Evidence excerpts are folded by default; citation links open the corresponding excerpt.
- Source-aware coverage. Accept pasted text, local PDFs, accessible paper webpages, online PDFs and DOI locators. The guide states what was actually read and what is missing.
- Focused teaching. Ask a specific question, request a direct explanation, pause, or resume with your progress record and readable source.
- Portable guides. Saved HTML embeds its resources, including mathematical rendering, for offline viewing and sharing.
Actual English guide for Challenging the N-Heuristic. See the example and source notes.
- An agent that can read skill files, access your paper and run the included helpers. Explicit invocation has been verified in Codex desktop on Windows.
- Node.js/npm for installation through the Skills CLI.
- Python 3.10+ for the helpers; pypdf 6.x when extracting PDF text.
Run from your target project's root:
npx skills add Kstheme/PaperUnfold --skill paper-guide paper-tutor --agent codex --copy --yesThe installed packages are in .agents/skills/. To select one skill, pass only its name after --skill.
For PDF input, install the dependency with the Python interpreter your agent will use:
python -m pip install -r .agents/skills/paper-guide/requirements.txtnpx skills update paper-guide paper-tutor --projectFor local development, run from the checkout root:
npx skills add . --skill paper-guide paper-tutor --agent codex --copy --yesTo install into another project, run there and replace . with the absolute checkout path. After changing the local source, rerun the same add command to refresh installed copies. Keep customizations in the source package, since refreshing replaces those copies.
The Python copy installer is also available. See installation details for that route, global installs, dependencies and update behavior.
Open your target project in Codex and give it readable paper material. These prompts explicitly load the installed entry files.
Read .agents/skills/paper-guide/SKILL.md and follow it.
Explain inputs/paper.pdf in English. Include the central mechanism or argument,
its visual structure, key evidence and limits. Save outputs/guide.html.
You can replace the PDF path with an accessible paper URL, DOI or pasted passage. Explanations use the conversation language unless you specify another one. The guide starts with the main thread and expands the central steps; detailed appendix audits are available on request.
Read .agents/skills/paper-tutor/SKILL.md and follow it.
Using inputs/paper.pdf, help me understand how the main evidence supports
its conclusion. Work through one question at a time and wait for my answer.
From an HTML guide, expand a chapter or term's teaching panel and copy its prompt into your agent conversation. The page provides the prompt; teaching happens in the agent.
Pause and save my learning progress to outputs/learning-progress.json.
In a new conversation, provide the progress file and readable paper source:
Read .agents/skills/paper-tutor/SKILL.md and follow it.
Resume from outputs/learning-progress.json using inputs/paper.pdf.
A progress record preserves the learning position and demonstrated understanding. It does not replace the paper or establish mastery on its own.
Download or open the HTML files locally to view the guides. Each example includes coverage and source information.
| Research structure | Paper | Guide |
|---|---|---|
| Algorithm and mechanism | Attention Is All You Need | Chinese HTML |
| Empirical evidence | Challenging the N-Heuristic | English HTML |
| Theoretical argument | Why Most Published Research Findings Are False | Chinese HTML · English HTML |
See the example collection, teaching and resumption record, and same-passage presentation comparison. These demonstrate the workflow; they do not measure human learning gains or establish quality across every discipline.
PaperUnfold packages instructions and helpers for your agent. Analysis and teaching depend on the agent and the readable source material.
- A DOI or abstract does not establish full-paper access. Missing or unreadable material limits the guide.
- PDF extraction does not perform OCR. Figures, tables and ambiguous equations need source inspection.
- Automatic discovery, Codex CLI execution and other agent/platform combinations have not been verified for this project.
- Interactive experiments currently support a bounded softmax teaching example. Other mechanisms use source-guided diagrams or worked examples.
- Source reuse and targeted checks reduce repeat work. End-to-end speed and learning improvements are not guaranteed.
| Document | Contents |
|---|---|
| Installation | Local and remote installation, dependencies, updates and fallback paths. |
| npx validation | Actual package discovery, local installation and refresh checks. |
| Guide workflow | Explanation depth, pipelines and performance-validation limits. |
| Specification | Behavior contracts and acceptance scenarios. |
| Design | Reading and teaching methodology, in Chinese. |
| Glossary | Shared project terminology, in Chinese. |
Contributions to explanation quality, diagrams, source handling and agent compatibility are welcome. See CONTRIBUTING.md for observable behavior checks and source-fidelity requirements. Report the source version, agent environment, expected behavior and actual result when describing an issue.
Inspired by Karpathy's discussion of clear explanations and custom artifacts and asd-ste100-skill. PaperUnfold applies clear terminology, explicit steps and meaning-preserving explanations to paper reading. These projects are references, not runtime dependencies or endorsements.
Original code, skills and documentation are licensed under MIT. Papers and bundled KaTeX retain their own licenses and attribution.