How to use the Jupyter Notebooks agent skill

What an agent skill is and what this one does

An agent skill is a folder of instructions that an AI agent loads when a task matches the skill's description. This one is named jupyter-notebooks and is described as creating, editing, or validating reproducible SQL or Python notebooks.

Once installed, the agent builds notebooks as reader-friendly analysis documents. It follows a fixed structure for analytical notebooks: tl;dr, Context & Methods, Data, Results, and Takeaways. For tutorials it uses Goal, Setup, Steps, Checks, and Next Steps instead. It keeps code cells short and focused, records where data came from, and tries to execute the notebook top-to-bottom to confirm it works.

• Writes section headers before most code cells, such as '### 1. Load Data'.
• Separates data preparation from plotting and interpretation.
• Writes the tl;dr and takeaways only after reviewing executed outputs.
• If it cannot run the notebook, it should say so and give the exact steps to reproduce the run.

Install the jupyter-notebooks skill

Download the skill ZIP from this page and unzip it. You can install it for yourself or for a single project.

For a personal install, unzip the folder into ~/.claude/skills/. For a project install, unzip it into the project's .claude/skills/ folder. If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

The package contains two files: SKILL.md, which holds the instructions, and agents/openai.yaml. Keep the folder structure intact after unzipping.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills (upload)

Trigger the skill with a natural request

You do not need a special command. The agent loads the skill when your request matches its description, so mention notebooks and the reason the analysis should be reviewable or rerunnable. The description lists triggers such as notebooks, SQL or Python scratchpads, reproducible exploration, audit trails, and runnable companions.

If your result supports a recommendation or decision, the skill points to a related skill, $validate-data. Mention that in the request if the numbers will be shared.

• 'Build a reproducible Jupyter notebook that shows how we calculated last quarter's churn, with a summary and a record of where the data came from.'
• 'Turn this SQL exploration into a rerunnable notebook others can audit.'
• 'Create a teaching notebook on pandas groupby with Goal, Setup, Steps, Checks and Next Steps sections.'
• 'Edit my existing notebook so the results section matches what it actually outputs, and run it top-to-bottom.'

What the notebook process looks like

The skill asks the agent to lock the notebook's mode and scope first: who the reader is, what decision it supports, and what inputs are needed. It then prefers JupyterLab, nbformat, nbclient, or an existing scaffold over hand-editing raw JSON, and it tries to preserve an existing notebook's intent.

For execution, the skill gives this command. If your environment lacks the tools, it gives an optional install line.

• Keep parameters, date ranges, filters and assumptions near the top.
• Keep heavy queries filtered and bounded rather than scanning live sources broadly.
• Bound outputs with small previews, sampled rows and explicit limits.

What you need before you start

To execute notebooks, the agent needs Python with Jupyter tooling. The source names jupyterlab, nbformat, nbclient and ipykernel as examples. If these are missing, the skill's optional setup line installs them with uv.

If the notebook queries real tables, you also need access to the relevant data sources or exports. The skill refers to connectors such as structured data and operations logs, which you must have configured yourself. Without them, the agent can work from exports or pasted SQL instead.

• Python with jupyterlab, nbformat, nbclient, ipykernel (or the ability to install them)
• Access to the tables, exports or extracts the notebook uses
• Any credentials the notebook depends on, set up in the notebook or environment

Safety notes: scripts and network access

This skill runs scripts and uses the network. Executing a notebook runs its code, and queries can reach connected data sources. Review the code before you let the agent execute it, especially in shared or production environments.

The skill asks the agent to query connected data sources, so confirm permissions and the cost of a query before running it. Keep queries narrow by partition, cohort or time window. If the agent cannot execute the notebook, it should state that clearly rather than present an unrun file as validated.

• Check table permissions and query cost first.
• Prefer filtered, bounded queries.
• Ask for an explicit statement of any execution gap.

Tips for better notebooks

Give the agent the reader, the decision and the source tables in your first message. The skill's workflow depends on these to choose the right structure. For tutorials, say so explicitly so it uses the teaching layout.

Ask the agent to record source details such as table names, query links, source paths or extract names. The skill expects these to appear in the notebook context for any executed result that supports the analysis.

• State whether the notebook is an analysis report, experiment, diagnostic or tutorial.
• Ask it to add a Key Assumptions subsection when assumptions affect results.
• Ask for a reasonableness check on any surprising number before it appears in the summary.
• Keep an existing notebook's structure by asking for targeted edits.