From jupyter-notebooks
Build, manipulate, execute, validate, and version-control Jupyter notebooks programmatically. Use when working with .ipynb files, creating notebooks from code, running parameterised analyses, diffing/merging notebooks in git, stripping outputs, or converting notebooks to other formats. Triggers on: jupyter, notebook, ipynb, nbformat, nbconvert, nbclient, papermill, nbdime, cell, kernel, execute notebook, parameterise, notebook diff, notebook merge.
How this skill is triggered — by the user, by Claude, or both
Slash command
/jupyter-notebooks:jupyter-notebooksThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Programmatic notebook operations from CLI only (no Jupyter UI):
agents/openai.yamlassets/templates/blank.ipynbassets/templates/data-analysis.ipynbassets/templates/parameterised.ipynbassets/templates/report.ipynbreferences/cell-operations.mdreferences/error-handling.mdreferences/execution-guide.mdreferences/metadata-reference.mdreferences/output-handling.mdreferences/papermill-patterns.mdreferences/validation-and-linting.mdreferences/versioning-guide.mdscripts/nb_cells.pyscripts/nb_convert.pyscripts/nb_create.pyscripts/nb_diff.pyscripts/nb_execute.pyscripts/nb_metadata.pyscripts/nb_outputs.pyProgrammatic notebook operations from CLI only (no Jupyter UI):
Python requirement: 3.9+.
Scripts require these Python packages:
nbformat, nbclient, nbconvert, nbdimepapermill, nbstripoutEach script declares its own dependencies via PEP 723 inline metadata (the # /// script block at the top of each file). Read this block to determine exactly which packages a script needs.
Run the preflight check to verify environment readiness:
python scripts/nb_preflight.py --mode auto
This script has no dependencies (stdlib only). It supports --mode auto|python|uv:
auto (default): succeed if either Python-mode or uv-mode is ready,python: check interpreter package availability directly,uv: verify uv run readiness by smoke-testing all script --help entrypoints.It emits a JSON report to stdout with ok, ok_python, ok_uv, ok_execute, and mode-specific details.
If packages are missing:
pyproject.toml, requirements.txt, Pipfile, uv.lock, poetry.lock, or similar).nb_preflight.py to confirm.Do not skip or abandon a script because its dependencies are not currently installed. Resolve them first.
Run scripts with whatever Python interpreter the project environment provides:
python scripts/<tool>.py [args]
If the project uses a tool that handles PEP 723 inline metadata automatically (e.g. uv run), that works too — the metadata block in each script is compatible.
nb_execute.py) requires a Jupyter kernel (typically ipykernel).scripts/nb_create.py: Create notebook from blank/template/script; inject script as one cell into existing notebook.scripts/nb_cells.py: Cell CRUD, reorder, metadata/tags, bulk ops, regex search.scripts/nb_execute.py: Execute with nbclient (default), selective range execution, or papermill mode.scripts/nb_validate.py: Schema validation + operational lint checks for CI/pre-commit.scripts/nb_convert.py: Convert notebook to html/pdf/latex/script/markdown/rst/slides.scripts/nb_metadata.py: Notebook/cell metadata and tag management.scripts/nb_outputs.py: Output listing, size checks, stripping, image extraction, clear execution counts.scripts/nb_diff.py: nbdime-backed diff (text/json) and three-way merge.scripts/nb_create.py.scripts/nb_cells.py; details in references/cell-operations.md.scripts/nb_execute.py; decision guidance in references/execution-guide.md.scripts/nb_execute.py --papermill; patterns in references/papermill-patterns.md.scripts/nb_validate.py; rules in references/validation-and-linting.md.scripts/nb_convert.py.scripts/nb_metadata.py; schema map in references/metadata-reference.md.scripts/nb_outputs.py; guidance in references/output-handling.md.scripts/nb_diff.py; setup in references/versioning-guide.md.references/error-handling.md.nb_create.pynb_cells.pynb_execute.pynb_validate.pynb_convert.pynb_metadata.pynb_outputs.pynb_diff.pyCreate from template:
python scripts/nb_create.py --template data-analysis --output notebooks/0.1-mmk-initial-eda.ipynb
Add a code cell:
python scripts/nb_cells.py --input notebooks/0.1-mmk-initial-eda.ipynb add --cell-type code --source "print('hello')"
Execute selective range (cornerstone pattern):
python scripts/nb_execute.py --input notebooks/0.1-mmk-initial-eda.ipynb --start-index 3 --end-index 7
Validate for CI:
python scripts/nb_validate.py --input notebooks/0.1-mmk-initial-eda.ipynb --forbid-outputs
Convert to markdown:
python scripts/nb_convert.py --input notebooks/0.1-mmk-initial-eda.ipynb --to markdown --output reports/eda.md
Scripts follow a consistent contract:
0 success, 1 error.nb_validate.py: 0 no issues, 1 issues found, 2 runtime/tool failure.<step>-<owner>-<description>.ipynbnbstripout + nbdime together for repository hygiene and readable diffs..gitattributes is provided in assets/.gitattributes.example.Guides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.
npx claudepluginhub marcinmiklitz/jupyter-notebooks-skill --plugin jupyter-notebooks