# Nanorepl

> Build minimal reimplementations of complex projects following Karpathy's nano/micro/min philosophy. Analyzes a target project to identify its irreducible algorithmic core, decomposes it into progressive layers, and guides incremental building with verification at each step. Works for any domain. Triggers on "build a minimal version of", "nanorepl", "reimplement from scratch", "strip down to the core", "build a micro/nano/mini version", or when a project URL is provided with a request to understand or rebuild its core. Invoke with "nanorepl".

- Skill: `chrisliu298/nanorepl` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add chrisliu298/nanorepl`
- Raw SKILL.md: https://api.skillmd.com/api/skills/chrisliu298/nanorepl/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: chrisliu298 (https://skillmd.com/u/chrisliu298)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/chrisliu298/nanorepl

---


# nanorepl

> "What I Cannot Create, I Do Not Understand." -- Richard Feynman

Build a minimal reimplementation of any complex project. Strip away everything that isn't the core algorithm, then layer complexity back in one concept at a time.

## Two-Dimensional Complexity Control

Two independent dials control the output:

**Scale (1-5)** -- how much of the project to replicate:

| Scale | LOC Target | Scope |
|-------|-----------|-------|
| 1 | ~50-200 | Core algorithm only |
| 2 | ~200-500 | + real I/O, runs on real data |
| 3 | ~500-1000 | + essential features, produces useful results |
| 4 | ~1000-2000 | + complete feature set, basic error handling |
| 5 | ~2000+ | + configuration, optimizations, usable tool |

**Level (micro/nano/mini)** -- implementation style:

| Level | Style | Dependencies | Files |
|-------|-------|-------------|-------|
| micro | Pure algorithm, zero external deps, implement everything from scratch | stdlib only | single file |
| nano | Pragmatic minimal, stdlib + one key dependency | stdlib + 1 | single file |
| mini | Structured minimal, essential deps, some organization | essential deps | 1-3 files |

**Default:** `nano-3` -- single file, one dependency, produces real results.

**Reference points:** `micro-1` = microGPT gist (~200 LOC, pure Python autograd + GPT). `nano-3` = nanoGPT (~600 LOC, PyTorch model + training). `mini-5` = nanochat (~8000 LOC, full pipeline).

## Invocation

```
nanorepl                           # Start new project
nanorepl <url>                     # Analyze a specific project
nanorepl <concept> <level>-<scale> # Quick start with parameters
```

## Workflow

### Step 1: Target Acquisition

Use AskUserQuestion to gather parameters:

**Q1 -- Target:** "What do you want to build a minimal version of?"
- URL -- GitHub repo, documentation page, or paper
- Local path -- existing project on disk
- Concept -- describe what it does (e.g., "a B-tree key-value store with WAL")

**Q2 -- Scale and Level:** "What complexity?"
- Show the scale/level matrix above
- Default: nano-3
- User can specify as `{level}-{scale}` (e.g., `micro-2`, `mini-4`)
- Or separately: "scale 3, level nano"

**Q3 -- Language:** "What language?" (default: Python)

**Q4 -- Output location:** "Where to create the project?" (default: `./nanorepl-{name}/`)

If the user provided arguments with `nanorepl`, skip already-answered questions.

### Step 2: Source Analysis

Analyze the target to identify the irreducible core. Approach depends on input type:

If the target is very large (e.g., an entire framework like PyTorch or Linux), ask the user to identify a specific subsystem or capability to reimplement. Do not attempt to analyze an entire large codebase.

| Input | Action |
|-------|--------|
| GitHub URL | Fetch README via WebFetch. Clone if needed. Read entry points and core modules. Trace imports only for core algorithm -- do NOT read the entire repo. |
| Local path | Read directory structure. Read entry points and core modules. Map dependencies between modules. |
| Concept | WebSearch for reference implementations. Read 2-3 authoritative sources. Synthesize understanding of the core algorithm. |
| Paper URL | Fetch and extract the key algorithm, data structures, and evaluation approach. |

**Produce an anatomy** -- classify every component of the original:

| Category | Action |
|----------|--------|
| Core algorithm | KEEP -- implement explicitly, no black boxes |
| Essential data structures | KEEP -- simplest representation that works |
| I/O interface | KEEP -- simplify to minimum viable |
| Everything else | Classify per `references/stripping-heuristics.md` -- STRIP, DEFER to higher scale, or MAKE EXPLICIT |

Read `references/stripping-heuristics.md` from this skill's directory for the full decision framework.

### Step 3: Decomposition

Generate a layer plan. Number of layers = scale value (scale 3 = layers L0, L1, L2).

**Rules:**
- **Layer 0** is always the irreducible core -- the thing that makes this project what it IS, not what makes it fast or convenient
- **One concept per layer** -- each layer adds exactly ONE conceptual component (one data structure, one mechanism, one I/O mode, one optimization). At low scale (1-2), the final layer may bundle 2-3 closely related concepts if they cannot be meaningfully separated (e.g., "HTTP handling" may include method filtering + path params). At scale 3+, strictly one concept per layer.
- **Keep the I/O paradigm stable across layers** -- if L0 uses a REPL, L1 should extend that REPL (not replace it with TCP). If an I/O paradigm shift is needed, it should BE the concept that layer introduces, and the core algorithm code should carry over unchanged so the diff stays clean.
- If a layer's diff from the previous would exceed ~200 LOC, split into sub-layers (2a, 2b)
- Every layer must be runnable and verifiable independently

**Layer template from microGPT blog (example for a language model at micro-5):**
- L0: bigram counting (simplest possible model)
- L1: MLP with manual gradients (add neural network)
- L2: autograd engine (add automatic differentiation)
- L3: self-attention mechanism (add the transformer's key idea)
- L4: full transformer block (add feedforward, norm, residuals)
- L5: Adam optimizer + LR decay (add real training)

For each layer, specify:
- What it adds (3-5 bullets)
- New capability unlocked (what it can do that the previous could not)
- Verification command and expected output
- Approximate LOC

### Step 4: Plan Presentation

Present the decomposition as a clean overview:

```
nanorepl-{name} [{level}-{scale}]: {one-line description}

L0 (~{N} LOC): {core algorithm name}
  adds: {what}
  verify: {command}

L1 (~{N} LOC): + {concept added}
  adds: {what}
  verify: {command}
  diff: {key additions from L0}

...

Stripped from original:
- {thing}: {why it was removed}
- {thing}: {why it was removed}
```

Wait for the user to confirm or adjust before building.

### Step 5: Progressive Building

Build one layer at a time, interactively.

For each layer:

1. **Generate the layer file** (`layer{N}.py` or appropriate extension)
   - Fully self-contained -- copy-paste runnable, no imports from other layers
   - Structured so `diff layer{N-1}.py layer{N}.py` shows clean, meaningful changes
   - **Zero comments except rare "why" notes.** Do not add section labels (`# forward pass`), step markers (`# step 1`), variable descriptions (`# learning rate`), or formula annotations (`# dL/dw`). If the code needs a comment to be understood, rename the variable or restructure the code instead. The only acceptable comment explains a non-obvious design choice (e.g., `# ReLU instead of sigmoid to avoid vanishing gradients`).
   - Short but clear variable names
   - No docstrings, no type annotations (unless language requires them)
   - At `micro` level: zero external deps, implement everything from scratch
   - At `nano` level: allow one key dependency
   - At `mini` level: allow essential deps, may use multiple files per layer

2. **Present with context**
   - Brief explanation of what's new relative to the previous layer
   - For L1+, highlight the key diff (what changed and why)

3. **Show verification**
   - Specific command to run
   - Expected output
   - What to check for correctness

4. **Wait for user input.** Supported commands:

   | Command | Action |
   |---------|--------|
   | `next` | Proceed to next layer |
   | `explain {thing}` | Walk through specific code, function, or concept |
   | `diff` | Show diff from previous layer |
   | `modify {request}` | Adjust current layer |
   | `done` | Stop here, skip remaining layers |
   | `restart {N}` | Regenerate from layer N |

### Step 6: Summary

After all layers are built (or user says "done"), generate `README.md` in the project directory:

```markdown
# nanorepl-{name}

A minimal reimplementation of {project} in {total LOC} lines of {language}.

> "{one-line description of what the irreducible core does}"

## Layers

| File | LOC | Concept Added |
|------|-----|---------------|
| layer0.py | {N} | {core algorithm} |
| layer1.py | {N} | + {concept} |
| ... | ... | ... |

## What Was Stripped

| Original Feature | Why Removed |
|-----------------|-------------|
| {feature} | {rationale from stripping heuristics} |

## Run

{command to run the final layer}

## Compare

- Original: {link to original project}
- This reimplementation: {total LOC} lines vs {original LOC estimate}
```

## Guiding Principles

These are non-negotiable -- they apply to every nanorepl project:

1. **The algorithm is NOT simplified.** Strip infrastructure, not the core logic. "Teeth over education" -- the hard parts stay hard.
2. **Every layer runs.** No layer is purely structural. Each produces verifiable output.
3. **Code is the documentation.** Zero comments by default. No section labels (`# forward pass`), no variable descriptions (`# weights`), no formula annotations. If the code isn't clear, rename variables or restructure -- don't add a comment.
4. **Make implicit things explicit.** If something is conceptually present but hidden by production code, expose it. Clarity > performance.
5. **One concept per layer.** If a layer adds two concepts, split it. At scale 1-2, the final layer may bundle closely related concepts that can't be meaningfully separated.
6. **Standalone and diffable.** Each layer file is self-contained. `diff` between adjacent layers reveals exactly what one concept looks like in code.
7. **No magic.** "It's a big math function." Every mechanism is visible and traceable.
8. **Everything else is just efficiency.** The gap between the nanorepl and production is engineering, not algorithmic understanding.

## Fixed Behaviors

| Behavior | Rule |
|----------|------|
| Layer files | Always standalone, never import from other layers |
| File naming | `layer{N}.py` at micro/nano level. At mini level with multiple files per layer: `layer{N}/` directory (e.g., `layer2/model.py`, `layer2/train.py`) |
| Default language | Python unless user specifies otherwise |
| Default complexity | nano-3 |
| Layer 0 | Always the irreducible core, always present |
| Verification | Required for every layer -- no unverifiable code |
| Dependencies at micro | Zero. Implement from scratch, including things like autograd, HTTP parsing, etc. |
| Dependencies at nano | One key dependency maximum |
| Comments | Zero comments by default. Only a rare "why" comment for a non-obvious design choice. No section labels, no variable descriptions, no formula annotations, no step markers. |
| README | Always generated at the end |