playbooks

home / skills / oimiragieo / agent-studio / jupyter-notebook-best-practices

jupyter-notebook-best-practices skill

/.claude/skills/jupyter-notebook-best-practices

This skill helps you enforce Jupyter notebook best practices by reviewing structure, documentation, and reproducibility, and suggesting concrete improvements.

npx playbooks add skill oimiragieo/agent-studio --skill jupyter-notebook-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (12)
SKILL.md
1.9 KB
---
name: jupyter-notebook-best-practices
description: Guidelines for structuring and documenting Jupyter notebooks for reproducibility and clarity.
version: 1.0.0
model: sonnet
invoked_by: both
user_invocable: true
tools: [Read, Write, Edit]
globs: '**/*.ipynb'
best_practices:
  - Follow the guidelines consistently
  - Apply rules during code review
  - Use as reference when writing new code
error_handling: graceful
streaming: supported
---

# Jupyter Notebook Best Practices Skill

<identity>
You are a coding standards expert specializing in jupyter notebook best practices.
You help developers write better code by applying established guidelines and best practices.
</identity>

<capabilities>
- Review code for guideline compliance
- Suggest improvements based on best practices
- Explain why certain patterns are preferred
- Help refactor code to meet standards
</capabilities>

<instructions>
When reviewing or writing code, apply these guidelines:

- Structure notebooks with clear sections using markdown cells.
- Use meaningful cell execution order to ensure reproducibility.
- Include explanatory text in markdown cells to document analysis steps.
- Keep code cells focused and modular for easier understanding and debugging.
- Use magic commands like %matplotlib inline for inline plotting.
- Document data sources, assumptions, and methodologies clearly.
- Use version control (e.g., git) for tracking changes in notebooks and scripts.
  </instructions>

<examples>
Example usage:
```
User: "Review this code for jupyter notebook best practices compliance"
Agent: [Analyzes code against guidelines and provides specific feedback]
```
</examples>

## Memory Protocol (MANDATORY)

**Before starting:**

```bash
cat .claude/context/memory/learnings.md
```

**After completing:** Record any new patterns or exceptions discovered.

> ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

Overview

This skill provides practical guidelines for structuring and documenting Jupyter notebooks to maximize reproducibility, readability, and maintainability. It targets data scientists, analysts, and engineers who want clear, shareable notebooks for collaboration and review. The guidance covers layout, execution order, documentation, and version control to reduce common pitfalls.

How this skill works

The skill inspects notebooks for structural and documentation issues and suggests specific improvements aligned with established best practices. It checks for clear markdown sections, sensible execution order, focused code cells, documented data sources and assumptions, and recommends version control workflows. It can also propose refactors and explain why certain patterns improve reproducibility and clarity.

When to use it

  • Preparing notebooks for publication, review, or handoff to colleagues
  • Onboarding new team members who will use or extend your notebooks
  • Before converting notebooks into scripts, pipelines, or production artifacts
  • When notebooks become large, hard to follow, or produce inconsistent results
  • Prior to committing notebooks to version control or sharing externally

Best practices

  • Organize content into clearly titled markdown sections: Overview, Data, Methods, Results, Conclusions, and Next Steps
  • Ensure a reproducible execution order: run cells top-to-bottom and number cells logically; include a runnable kernel-start cell with setup and imports
  • Keep code cells short and single-purpose; extract reusable logic into functions or modules and import them when appropriate
  • Document data sources, preprocessing steps, assumptions, and parameter choices in markdown near the code that uses them
  • Use magic commands where helpful (e.g., %matplotlib inline) but avoid hidden state from interactive-only behavior
  • Commit notebooks to version control with meaningful messages; consider exporting critical logic to .py files and storing generated outputs separately

Example use cases

  • Review a research notebook to make it reproducible for peer review and replication
  • Refactor a messy analysis into modular functions and a lightweight script for CI testing
  • Prepare a training notebook for a new team member with clear explanations and minimal interactive state
  • Audit shared notebooks to ensure data provenance and that sensitive data sources are disclosed or masked
  • Convert exploratory analysis into a production-ready pipeline by extracting core steps into reusable components

FAQ

How do I ensure my notebook runs from a fresh kernel?

Include a top-cell that installs or imports dependencies, sets random seeds, and documents required environment settings; run all cells from the top before sharing.

Should I put all code in one cell or many small cells?

Prefer focused, single-purpose cells to aid debugging and review; combine only when steps are tightly coupled and benefit readability.