Notebook Structurer
Make an analysis notebook reproducible — Restart & Run All clean, narrative order, no hidden state, dead cells gone.
v1.0.0 · ~610 tokens · ⬇ 0 · Updated July 6, 2026
What it does
Turns a messy analysis notebook into a reproducible document: enforces Restart-and-Run-All as the acceptance test (kills out-of-order/hidden-state bugs), narrative structure (purpose → imports → load → clean → analysis → conclusion), markdown explaining intent before each step, dead cells removed, randomness seeded, reusable logic extracted to modules, giant outputs cleared.
Example uses
Make a notebook run top-to-bottom
Your analysis notebook only works if cells run in the exact order you happened to click, and Restart & Run All fails.
This churn_analysis.ipynb fails on Restart & Run All — one cell uses a dataframe that was defined in a cell I deleted last week. Restructure it into narrative order (purpose, imports, load, clean, analysis, conclusion), fix the hidden-state dependencies, and confirm Restart & Run All completes cleanly and reproduces the same final figures.Prep a notebook for handoff
You are handing an exploratory notebook to a teammate and it is full of dead cells, debug prints, and huge embedded outputs.
I am handing revenue_forecast.ipynb to another analyst on Monday. Strip the dead experiment cells and debug prints, add a markdown cell before each analysis step explaining what it does and why, extract the three copy-pasted plotting blocks into a small functions module, seed the randomness, and clear the giant outputs before I commit it.Kill nondeterministic notebook results
The same notebook reports slightly different numbers on every run and nobody trusts the metrics anymore.
Our A/B test analysis notebook reports a slightly different lift every time it runs. Track down the sources of nondeterminism — unseeded sampling, a train_test_split without a fixed random_state, and an unpinned data pull — pin all of them, then verify with two consecutive Restart & Run All passes that produce identical output.Install
# 1. Create the skill folder in your Claude setup mkdir -p ~/.claude/skills/notebook-structurer # 2. Download SKILL.md into it (or move the file you just downloaded) # → ~/.claude/skills/notebook-structurer/SKILL.md # 3. Claude Code auto-discovers it on next launch.
Inside the skill
--- name: notebook-structurer description: Turn a messy analysis notebook into a clean, reproducible one — clear flow, no hidden state, restart-and-run-all safe. Use when a Jupyter/analysis notebook is a mess, before sharing/handing off analysis, or asked "clean up this notebook", "make this reproducible", "structure my analysis". Kills the out-of-order-execution trap. --- # Notebook Structurer A notebook that only runs if you execute cells in the exact order you happened to click is a trap — for the next person and for future-you. Make it run top-to-bottom, clean, every time. ## The cardinal rule: Restart & Run All must work Hidden state (a variable defined in a cell you later deleted, cells run out of order) makes notebooks lie. The test of a good notebook: **Kernel → Restart & Run All** produces the same result with no errors. If it doesn't, the notebook isn't reproducible — fix that first. ## Structure (narrative order) 1. **Title + purpose**: what question this answers, in a markdown cell up top. 2. **Imports + config**: all together, first. No imports scattered mid-notebook. 3. **Load data**: from a stable source (path/URL), with a note on what it is. 4. **Clean/prep**: transforms, each explained. (Heavy cleaning → a script, imported.) 5. **Analysis**: one logical step per section, markdown explaining WHAT and WHY before the code. 6. **Results/conclusion**: the answer, restated plainly, with the key figures. ## Clean up - **Remove dead cells**: experiments, debugging prints, commented-out attempts. The notebook tells the final story, not the whole struggle. - **No out-of-order dependencies**: each cell uses only what earlier cells defined. - **Extract reusable logic** into functions/a module; a notebook full of copy-pasted blocks should be a few functions. - **Seed randomness**, pin data versions — same input, same output. - Clear giant outputs before committing; a notebook with 50 MB of embedded output is unshareable. ## Rules - Restart & Run All is the acceptance test — if it errors or changes results, it's not done. - Markdown explains intent before each step; a notebook is a document, not just code. - Move heavy/reusable code out to a module and import it; keep the notebook as narrative. ## Output The restructured notebook (narrative order, markdown-documented, dead cells removed), confirmation that Restart & Run All is clean, and any logic extracted to functions/modules.
Changelog
- v1.0.02026-07-03Initial clean-room write.
Frequently asked questions
Is Notebook Structurer free?
Yes. Notebook Structurer is free to download and MIT-licensed.
Where do I install Notebook Structurer?
Place the SKILL.md file in ~/.claude/skills/notebook-structurer/ and Claude Code auto-discovers it on next launch.
How many tokens does Notebook Structurer use?
About 610 tokens — it is designed to be token-lean.
We're developers and SaaS builders who use these tools daily in production. Every review comes from hands-on experience building real products — DealPropFirm, ThePlanetIndicator, PropFirmsCodes, and many more. We don't just review tools — we build and ship with them every day.
Written and tested by developers who build with these tools daily.