Skip to main content
skill CX Codex

paper-to-runnable — Claude Code skill: what it does, how to install

The paper-to-runnable Claude Code skill turns a research paper into a minimal implementation of its central idea. It activates for requests to build or reproduce a paper, including from an arXiv link or local PDF.

MIT ★ 541 updated 2026-11-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dotslashsimran/simcraft --skill paper-to-runnable -a claude-code
Open on GitHub

What paper-to-runnable does

The skill identifies a paper’s main claim and the mechanism behind it, then builds a small implementation in one code file. The output folder contains notes.md, the code, checks, a toy reproduction, visualizations, and an explanation in explainer.md.

Verification proceeds through tensor shapes, gradient checks when gradients are written by hand, fitting a small batch, and checking the untrained model. The main run is then compared with an ablation that switches off the mechanism. The fetch script handles arXiv papers and extracts equation files; it asks for permission before downloading from another link.

The provided setup.sh creates an environment with numpy, matplotlib, and pypdf; NumPy is the default choice. PyTorch is reserved for cases where writing backpropagation by hand would take more code than the idea itself. Animation needs ffmpeg available through $FFMPEG or PATH. Read the Grokking example in examples/grokking/ before the first build.

What it helps with

  • build a minimal implementation of a paper’s core mechanism
  • check tensor shapes and hand-written gradients
  • compare a toy result with an ablation of the mechanism
  • visualize model internals with plots or animation
  • record which findings reproduced and which did not

Example prompts for the agent

  • Implement the main idea in this arXiv paper and test it with a toy run.
  • Reproduce the result from this local PDF and compare it with an ablation.
  • Explain how this paper works by building a small version and visualizing its mechanism.

How to install paper-to-runnable

1Skills CLI (Vercel)

npx skills add dotslashsimran/simcraft --skill paper-to-runnable -a claude-code

2Manually: put the files in place

~/.claude/skills/paper-to-runnable/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/paper-to-runnable/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about paper-to-runnable

How do I install paper-to-runnable in Claude Code?

Run npx skills add dotslashsimran/simcraft --skill paper-to-runnable -a claude-code. The skill file is then available at ~/.claude/skills/paper-to-runnable/SKILL.md.

What does paper-to-runnable do?

It turns a research paper into a small implementation of its central mechanism, checks it in stages, and compares a toy result with an ablation. The output includes notes, code, and a visual explanation.

What is needed to create animations with paper-to-runnable?

ffmpeg must be available through $FFMPEG or PATH. The basic environment setup installs numpy, matplotlib, and pypdf.

Source text

SKILL.md · MIT
---
name: paper-to-runnable
description: Turn a research paper (arXiv id, arXiv URL or local PDF) into the smallest honest working implementation of its core idea, checked with a sanity ladder and a toy reproduction of the paper's main result, plus plots or an animation of what happens inside and a short explainer. Use when the user says "implement this paper", "reproduce this paper", "explain this paper by building it", "code up this arXiv paper", "make this paper runnable", "does this paper's result hold", or pastes an arXiv link and wants to understand how it works.
---

# Paper to runnable

A paper is a claim. The way to understand it is to find the one mechanism the claim rests on, build only that, and watch it produce the paper's result at toy scale. Everything else in the paper is supporting detail.

The output is a folder with five things: `notes.md`, one code file, a sanity ladder that passes, a toy result next to the paper's figure, and visuals plus `explainer.md`. A full worked example (Grokking, arXiv 2201.02177) is in `examples/grokking/` and walked through in `reference.md`. Read it before the first build.

## Setup

```
sh <skill>/setup.sh          # .venv with numpy, matplotlib, pypdf
sh <skill>/setup.sh torch    # only if the build truly needs autograd
PY=<skill>/.venv/bin/python
```

Check first: if the system `python3` already has numpy and matplotlib, it can be used instead. Default to numpy. Reach for PyTorch only when hand-written backprop would be longer than the idea itself (a multi-layer transformer, a conv net). ffmpeg comes from `$FFMPEG` or `ffmpeg` on the PATH.

## 1. Fetch the paper

```
python3 <skill>/scripts/fetch_paper.py <arxiv id | arxiv url | local.pdf> --out <work>/paper
```

It writes `paper.txt`, `meta.json`, the LaTeX `source/` and `equations.md` (every display equation with its number, label and source line, plus the author's macros). LaTeX gives exact equations, so read `equations.md` over the PDF text for math. If a paper has no numbered equations, the script says so: cite sections, figures, algorithms and appendix tables instead.

The script only downloads from arXiv. For any other link, ask the user before downloading anything, then pass the local PDF.

## 2. Find the core claim, write `notes.md`

Read the abstract, the figure captions, the main method section and the experiment setup (usually an appendix). Then write `notes.md` with these headings:

- **Claim**: one sentence, falsifiable. "X causes Y under Z."
- **Mechanism**: the one thing that makes it work. If removing it should break the result, it is the mechanism.
- **Equations to code**: a table of each equation used, its number, and the variable names it becomes.
- **Result to reproduce**: which figure or table, and what qualitative shape counts as success. Decide this before running anything.
- **Ablation**: the one switch that turns the mechanism off. This is the experiment that proves the mechanism matters.
- **Not reproduced, and why**: scale, architecture swaps, datasets, extra experiments. Be specific.

Show the user the claim, the mechanism and the planned result before writing code. They may know what they care about.

## 3. Build the minimal version

One file, under about 300 lines, from scratch. Every line that implements part of the paper gets a comment citing it: `# Eq. 3`, `# Sec 4.2`, `# A.1.2: lr 1e-3, wd 1`. Use the paper's hyperparameters where they are given. When you swap something out (a smaller model, a different task variant), say so in a comment at the swap and in `notes.md`.

Keep the paper's names for variables where they are readable (`Q, K, V`, `beta`, `alpha`). Write the backward pass by hand in numpy when it is short, because that is where understanding comes from.

## 4. Verify with a sanity ladder, then the toy result

Put the ladder behind a `--check` flag and run it before any long run. Each rung must pass before the next:

1. **Shapes**: every tensor has the shape the paper implies. Check the data generator against a few hand-computed examples.
2. **Gradient check** (if you wrote gradients): analytic versus central finite differences in float64, worst relative error under 1e-5.
3. **Overfit one small batch**: loss goes near zero, accuracy reaches 100%. If it cannot, the model or optimiser is broken.
4. **Chance at init**: the untrained model scores near chance. If it doesn't, there is leakage.
5. **Toy result**: the main run and the ablation, same seed, same budget. Report the numbers that define the result (for example "train 99% at step 1700, validation 99% at step 6100; with the switch off, validation stays at 0%").

Aim for a full run under a few minutes on CPU. Shrink the problem, not the idea. If the qualitative result does not appear, try the paper's settings first, then do a small sweep, and report what you tried. Never tune until it works and then hide the sweep: list every setting tried in `notes.md`.

Be honest about gaps. Write down what matched, what did not, and what the toy cannot tell us.

## 5. Visualise the internals, write `explainer.md`

Curves show that it works. Internals show why. Plot the quantity the mechanism acts on (attention weights, an embedding, a loss landscape slice, a hidden state over time) as training goes, with the mechanism on and off side by side.

For motion, use the helper. It writes PNG frames and stitches them with ffmpeg:

```python
sys.path.insert(0, "<skill>/scripts"); from animate import animate
animate(draw, n_frames, "out/mechanism.mp4", fps=12, size=(13, 7), preview=True)  # look first
```

Render with `preview=True` first, open one frame from the `_frames/` folder, then render full size. Look at the output image yourself before describing it.

Then write `explainer.md`: one question, one story, one lesson, about 300 words, plain words, for a smart reader who has not read the paper. The story is what the visual shows happening. End with what the toy does not show.

## Rules

- Run everything you show. Never quote a number you did not get.
- The ablation is not optional. Without it you have a training curve, not evidence.
- A toy reproduction supports the mechanism, not the paper's exact numbers. Say so.
- If the result fails to reproduce after honest effort, that is a valid outcome. Report it with what you tried.

© dotslashsimran · MIT · dotslashsimran/simcraft

Similar skills

All skills for Science and research →

From the same set24

The whole set →
benchmark-honestly The benchmark-honestly Claude Code skill checks performance measurements and compares code versions. It activates for benchmark requests, load tests, latency percentiles, or claims that a change made code faster. CX Codex +1 ★ 541repo stars flaky-test-killer The flaky-test-killer Claude Code skill tracks down flaky-test causes and helps fix them at the root. It stresses the test and compares failure rates before and after the change. CX Codex +1 ★ 541repo stars reverse-engineer-video The reverse-engineer-video Claude Code skill breaks down a reference clip into shots, camera moves and editing beats. Invoke it to inspect a cut, plan a remake or compare one with the original. CX Codex +1 ★ 541repo stars system-design-from-scratch system-design-from-scratch — a skill for Claude Code that builds minimal distributed architectures, verifies invariants under simulated node failures, and stress-tests them with real metrics. CX Codex +1 ★ 541repo stars codebase-map The codebase-map Claude Code skill maps an unfamiliar repository and traces a real request through it. Ask it to explain the project structure, locate a code path, or onboard a new teammate. CX Codex +1 ★ 541repo stars api-design-review api-design-review — a skill for Claude Code reviews HTTP APIs, SDKs, and CLIs. It runs when asked to assess an API design, inspect a spec, or judge whether a change is safe to ship. CX Codex +1 ★ 541repo stars code-loop The code-loop Claude Code skill turns three.js scenes and GLSL shaders into looping videos. It activates for requests to make generative animations or GIFs that repeat without a visible cut. CX Codex +1 ★ 541repo stars dx-audit dx-audit — a Claude Code skill audits the onboarding path for an SDK, API, CLI, or framework using its official docs. It follows one task in a clean environment and records friction, errors, and time to first success. CX Codex +1 ★ 541repo stars

Project sponsors

Companies that keep this analytics open