# Gpu Paper To Code

> Skill: `gpu-paper-to-code`

- Skill: `maxiaotiao1105/gpu-paper-to-code` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add maxiaotiao1105/gpu-paper-to-code`
- Raw SKILL.md: https://api.skillmd.com/api/skills/maxiaotiao1105/gpu-paper-to-code/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: MaXiaoTiao1105 (https://skillmd.com/u/maxiaotiao1105)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/maxiaotiao1105/gpu-paper-to-code

---

# Skill: `gpu-paper-to-code`

## Purpose

A **reproduction-first** skill for turning GPU/systems papers into executable plans.

This skill does not summarize papers. It produces a **structured reproduction plan** centered on:
- MRU extraction (Minimal Reproducible Unit)
- Baseline design (weak + strong baselines, fairness rules)
- Ablation planning (what to turn on/off to validate the core mechanism)
- Repo execution roadmap (milestones you can actually work through)

Use this skill when you want to **build something**, not just understand something.

---

## When to use

Use this skill when:

- You have a paper and want a **reproduction plan**, not a summary
- You need to extract the **Minimal Reproducible Unit** that validates the core idea
- You want to design **fair baselines** and an **ablation matrix**
- You're building a repo and need a **milestone-based TODO roadmap**

---

## When not to use

Do not use this skill if:

- You want a literature review across multiple papers (split into multiple tasks)
- The paper has no technical content (no algorithm/mapping/memory/schedule)
- You don't plan to reproduce anything (a short summary suffices elsewhere)
- You want CUDA code immediately without understanding the paper first

---

## Core concepts

### MRU (Minimal Reproducible Unit)

The smallest implementation that demonstrates the paper's core claim.

**Why MRU first**:
- Full paper reproduction is overwhelming
- MRU lets you validate the core mechanism quickly
- Once MRU works, you can iterate toward full reproduction

**MRU criteria**:
- Demonstrates the core optimization mechanism
- Runs in < 1 minute on typical hardware
- Has a clear pass/fail criterion

**Rule**: The MRU should isolate the paper's key mechanism, not reproduce the full system or every optimization at once.

### Baseline quality

Every reproduction needs baselines. Not all baselines are equal.

| Baseline type | Description | When to use |
|---------------|-------------|-------------|
| Weak baseline | Naive implementation, unoptimized | To show the problem exists |
| Strong baseline | Best-practice implementation, vendor library | To show the improvement is meaningful |
| Prior art baseline | Implementation from previous paper | To compare against existing work |

**Baseline fairness rules**:
- Same shapes, same dtypes, same layouts
- Same warmup, same timing methodology
- No hidden work (transformations, copies)

### Ablation matrix

A structured way to validate that the core mechanism is what causes the improvement.

| Configuration | Expected result | What it validates |
|---------------|-----------------|-------------------|
| Full method | Best performance | Upper bound |
| Full method - optimization A | Degraded | A is necessary |
| Full method - optimization B | Degraded | B is necessary |
| Strong baseline | Baseline performance | Lower bound |

**Ablation rule**: Every claim should have at least one ablation that validates it.

---

## Workflow (must follow)

### Step 0 — Paper intake

Collect minimal required information:

| Required | Why |
|----------|-----|
| Abstract | The claim |
| Key figure(s) | The mechanism visualization |
| Method snippet | The algorithm |

If only partial info, proceed with:
- Explicit unknowns
- "What to read next" pointers

### Step 1 — One-paragraph story

Produce a single paragraph capturing the causal chain:

1. What problem does this paper solve?
2. Why were prior approaches insufficient?
3. What is the new idea?
4. What is the **core optimization mechanism**?

This is not a summary. It should explain **why** the paper exists, not just **what** it says.

### Step 2 — Bottleneck analysis

Identify what the paper is actually optimizing:

| Bottleneck type | Indicators |
|-----------------|------------|
| Memory bandwidth | High data movement, low compute intensity |
| Compute | High arithmetic intensity, compute-bound |
| Synchronization | Many kernel launches, barriers |
| Latency | Small batch sizes, underutilized hardware |

State what evidence the paper uses (roofline, profiler, microbench).

### Step 3 — Core mechanism extraction

Decompose the contribution:

| Mechanism type | Examples |
|----------------|----------|
| Algorithmic change | Different math, approximation |
| Parallel mapping change | Different loop → thread mapping |
| Memory hierarchy change | Different tiling, staging |
| Scheduling change | Different execution order |
| Fusion change | Combining kernels |

Identify the **minimal set of moving parts** needed to implement the mechanism.

### Step 4 — MRU extraction

Define the Minimal Reproducible Unit:

```
## MRU Definition

- Unit: [kernel? subroutine? pipeline?]
- Core mechanism: [single sentence]
- Expected measurable effect: [latency reduction / bandwidth reduction / memory savings / accuracy-preserving speedup]
- Pass criterion: [a concrete criterion that can falsify the claim]
- Estimated implementation time: [hours/days]
```

### Step 5 — Baseline design

Design at least two baselines:

```
## Weak Baseline
- Implementation: [description]
- Expected performance: [qualitative]
- Purpose: Show the problem exists

## Strong Baseline
- Implementation: [description]
- Expected performance: [close to paper baseline]
- Purpose: Meaningful comparison

## Fairness rules
- Same shapes: [...]
- Same dtypes: [...]
- Same layouts: [...]
- Same warmup/timing: [...]
```

### Step 6 — Ablation planning

Design an ablation matrix:

| Config | What's removed | What it validates |
|--------|---------------|-------------------|
| Full | — | Upper bound |
| Ablation 1 | [optimization A] | [claim about A] |
| Ablation 2 | [optimization B] | [claim about B] |
| Strong baseline | All optimizations | Lower bound |

Every core claim should have at least one ablation.

### Step 7 — Hardware mapping

For GPU/systems papers, map the algorithm to hardware:

| Element | Mapping |
|---------|---------|
| Outer loops | → Blocks / program IDs |
| Inner loops | → Warps / threads |
| Working set | → Shared memory? Registers? |
| Synchronization | Where and why |
| Expected occupancy | Register/shared budget hypothesis |

### Step 8 — Repo execution roadmap

Produce a milestone-based TODO:

```
## Milestone 0: Setup (Day 1)
- [ ] Environment capture (hardware, software, versions)
- [ ] Data generation utilities
- [ ] Baseline harness

## Milestone 1: Strong Baseline (Day 2-3)
- [ ] Implement strong baseline
- [ ] Correctness tests
- [ ] Baseline benchmark numbers

## Milestone 2: MRU (Day 3-5)
- [ ] Implement MRU
- [ ] Correctness vs baseline
- [ ] Initial performance comparison
- [ ] Pass/fail on MRU criterion

## Milestone 3: Ablations (Day 5-7)
- [ ] Implement ablation switches
- [ ] Run ablation matrix
- [ ] Validate core mechanism

## Milestone 4: Full reproduction (Week 2+)
- [ ] Expand shape coverage
- [ ] Match paper benchmark setup
- [ ] Document limitations
```

### Step 9 — Pitfalls

List common reproduction traps:

| Pitfall | How to avoid |
|---------|--------------|
| Wrong baseline | Use strong baseline, document methodology |
| Missing preprocessing | Check paper for data transforms |
| Wrong shapes | Match paper's exact shape regime |
| Hidden costs | Account for all work (transforms, copies) |

---

## Output contract

Every output must follow this structure:

```
## One-Paragraph Story
A single paragraph capturing the causal chain:
- What problem does this paper solve?
- Why were prior approaches insufficient?
- What is the new idea?
- What is the core optimization mechanism?

This should explain why the paper exists, not just what it says.

## Bottleneck Analysis
[What's being optimized + evidence]

## Core Mechanism
[Decomposition + minimal moving parts]

## MRU Definition
- Unit: [...]
- Core mechanism: [...]
- Expected measurable effect: [...]
- Pass criterion: [...]
- Estimated time: [...]

## Baseline Design
[Weak + strong + fairness rules]

## Ablation Matrix
[Table of configurations + what they validate]

## Hardware Mapping
[Loops → blocks/warps + memory hierarchy]

## Repo Execution Roadmap
[Milestones + deliverables + acceptance criteria]

## Pitfalls
[Reproduction traps + mitigations]
```

## Self-check before output

- [ ] Does the story explain *why*, not just *what*?
- [ ] Is the MRU the smallest unit, not the full system?
- [ ] Do baselines have fairness rules?
- [ ] Does the ablation matrix cover the core claim?
- [ ] Are pitfalls concrete, not generic?

---

## Quality bar

Output is acceptable only if:

- MRU is explicitly defined (not just "reproduce the paper")
- At least two baselines are designed with fairness rules
- Ablation matrix covers core claims
- Repo roadmap has concrete milestones
- No fabricated performance numbers

---

## Failure modes

| Mistake | Why it's wrong |
|---------|---------------|
| Summarizing instead of reproducing | This is not a summary skill |
| Missing baseline definition | Cannot validate improvement |
| No ablation plan | Cannot validate mechanism |
| Vague "then implement" | Needs concrete milestones |
| Copying jargon without mapping | Terms must connect to code decisions |
| Overfitting to one figure | May miss constraints in method section |

---

## Teaching mode (restrained)

If the user lacks background, explain only terms **relevant to this paper**:

- Keep definitions minimal and precise
- Immediately connect to implementation decisions
- Do not let teaching mode dominate the output

Example:
> "Occupancy" = how many warps can run concurrently per SM. For this paper, higher occupancy means more latency hiding, but may require reducing register usage per thread.

---

## Supporting docs

- `docs/PAPER_INTAKE.md` — Minimal extraction template
- `docs/TERMINOLOGY_CRASHCOURSE.md` — GPU vocabulary

## Templates

- `templates/PAPER_TO_CODE_REPORT.md` — Output template
- `templates/REPRO_REPO_TODO.md` — Roadmap template
- `templates/BENCHMARK_AND_VALIDATION.md` — Benchmark design

## Examples

- `examples/prompts.md` — 9+ example prompts
- `examples/worked-example-flashattention-style.md` — Full worked example