# notebook-guidance

> Claude/Codex skill by [@googlecloudplatform](https://omgskills.com/library/googlecloudplatform/index.md) · 226 stars · Updated 2026-10-23

This skill guides the use of Jupyter notebooks for data analysis, exploration, and visualization, particularly with BigQuery. It outlines best practices for notebook execution and validation (supporting both cell-by-cell execution and full notebook generation depending on tool availability), library installation, and structuring notebooks for clarity. It also covers specific rules for data cleaning, plotting, and integrating with BigQuery SQL and machine learning workflows. Relevant when any of the following conditions are true: 1. The user request involves a data analysis, data exploration, data visualization, or data insights task that requires multiple steps, queries, or visualizations to answer. 2. The user explicitly requests a notebook (.ipynb). 3. You are creating, editing, or executing cells in a Jupyter notebook. 4. You need to query BigQuery from within a notebook. DO NOT use the Python BigQuery client library; instead, you MUST use the \`%%bqsql\` magics explained in this skill.

## Install

```sh
git clone https://github.com/GoogleCloudPlatform/data-agent-kit-plugin /tmp/data-agent-kit-plugin && ln -s /tmp/data-agent-kit-plugin/skills/notebook-guidance ~/.claude/skills/notebook-guidance
```

## From README

Notebook Guidance When to Use a Notebook Before choosing to use a notebook, evaluate the task complexity using these heuristics. Use a notebook if you meet at least one of these criteria: 📈 Data Insights & Storytelling: Use a notebook for any request to "give insights", "find trends", "explore data", or "analyze data". These tasks benefit from using visualizations to present the data. 📊 Visualizations are requested: The user explicitly asks for charts or plots. 🔄 Stateful / Iterative Exploration: You need to run a query, inspect results, and decide the next query based on those results while keeping state in memory. Do NOT use a notebook ONLY if: 📝 Simple Fact/Status: The request only requires a single number (e.g., "how many rows") or a status check (e.g., "when was this table updated"). 🏃‍♂️ Schema Preview: The request is only about the schema or field types.

## Links

- HTML page: https://omgskills.com/library/googlecloudplatform/data-agent-kit-plugin/skills/notebook-guidance/
- GitHub: https://github.com/GoogleCloudPlatform/data-agent-kit-plugin
- Author: [@googlecloudplatform](https://omgskills.com/library/googlecloudplatform/index.md)

## More from this repo

- [accidental-data-loss-prevention](https://omgskills.com/library/googlecloudplatform/data-agent-kit-plugin/skills/accidental-data-loss-prevention/index.md) — \*\*STOP AND VERIFY\*\*: Before running any command or tool that results in irreversible data loss, you MUST obtain...
   - [@googlecloudplatform](https://omgskills.com/library/googlecloudplatform/index.md) · 226 stars
- [bigquery-ai-ml](https://omgskills.com/library/googlecloudplatform/data-agent-kit-plugin/skills/bigquery-ai-ml/index.md) — Leverages BigQuery's built-in machine learning and GenAI capabilities for advanced data analytics.
   - [@googlecloudplatform](https://omgskills.com/library/googlecloudplatform/index.md) · 226 stars
- [bigquery-bigframes](https://omgskills.com/library/googlecloudplatform/data-agent-kit-plugin/skills/bigquery-bigframes/index.md) — Generates Python code using BigQuery DataFrames (BigFrames).
   - [@googlecloudplatform](https://omgskills.com/library/googlecloudplatform/index.md) · 226 stars