Deepnote Skill

.deepnote files are YAML-based, portable, git-friendly files that each hold a single notebook. Each notebook holds an ordered list of blocks (code, SQL, markdown, inputs, visualizations, etc.). Snapshot files (.snapshot.deepnote) use the same format but include execution outputs.

File Structure

A minimal valid .deepnote file:

version: 1.0.0
metadata:
  createdAt: "2025-01-08T10:00:00.000Z"
project:
  id: 2e814690-4f02-465c-8848-5567ab9253b7
  name: My Project
  notebooks:
    - id: e132b172-b114-410e-8331-011517db664f
      name: Main
      blocks:
        - id: b75d3ada977549b29f4c7f2183d52fcf
          blockGroup: 9dd9578e604a4235a552d1f4a53336ee
          type: code
          content: |
            print("Hello World!")
          sortingKey: a0
          metadata: {}

Top-level fields: version (required, "1.0.0"), metadata (required), project (required), integrations (optional), environment (optional).

Schema Reference

TypeScript schema — auto-generated types for .deepnote and .snapshot.deepnote files

Notebooks

Each entry in project.notebooks has:

id - UUID v4 identifier
name - Human-readable name
executionMode - block (run individually) or downstream (run with dependents)
blocks - Array of content blocks
workingDirectory - Optional base directory for file operations

Blocks

Every block has these common fields:

| Field | Description | | ------------ | --------------------------------------------------------------- | | id | Unique hex identifier (32 chars) | | blockGroup | Groups related blocks (same format as id) | | type | Block type string | | content | Source code, text, or query (YAML multi-line \| syntax) | | sortingKey | Determines display order (lexicographic, e.g. a0, a1, a2) | | metadata | Type-specific configuration object |

Block Types

| Category | Types | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Code | code | | SQL | sql | | Text | markdown, text-cell-h1, text-cell-h2, text-cell-h3, text-cell-p, text-cell-bullet, text-cell-todo, text-cell-callout | | Input | input-text, input-textarea, input-checkbox, input-select, input-slider, input-date, input-date-range, input-file | | Display | visualization, big-number, image, separator | | Other | button, notebook-function |

Block Type References

Integrations

Database connections stored in the top-level integrations array:

integrations:
  - id: 084f5334-5dbe-41c7-9020-3f66b9418062
    name: Production DB
    type: pgsql

Each integration has id (UUID), name, and type. Supported types: alloydb, athena, big-query, clickhouse, databricks, dremio, mariadb, materialize, mindsdb, mongodb, mysql, pgsql, redshift, snowflake, spanner, sql-server, trino. (Note: pandas-dataframe exists as a type but is not configurable via CLI.)

SQL blocks reference integrations via metadata.sql_integration_id.

Snapshots

Snapshot files (.snapshot.deepnote) store execution outputs separately from source.

Location

Snapshots are saved in a snapshots/ directory adjacent to the source file:

project.deepnote
snapshots/
  my-project_<projectId>_<notebookId>_latest.snapshot.deepnote
  my-project_<projectId>_<notebookId>_2025-01-08T10-30-00.snapshot.deepnote
  my-project_<projectId>_latest.snapshot.deepnote
  my-project_<projectId>_2025-01-08T10-30-00.snapshot.deepnote

Naming:

Single-notebook files: {slug}_{projectId}_{notebookId}_{timestamp}.snapshot.deepnote
Legacy files: {slug}_{projectId}_{timestamp}.snapshot.deepnote
slug — slugified project name
projectId — UUID from project.id
notebookId — notebook UUID (for single-notebook files)
timestamp — latest or ISO 8601 (e.g. 2025-01-08T10-30-00)

Reading Snapshot Data (token-efficient)

Use CLI commands — they're cross-platform and avoid loading the full YAML:

deepnote cat snapshots/*_latest.snapshot.deepnote                    # All block outputs
deepnote cat snapshots/*_latest.snapshot.deepnote --type code        # Only code outputs
deepnote inspect snapshots/*_latest.snapshot.deepnote                # Metadata + summary
deepnote inspect snapshots/*_latest.snapshot.deepnote -o json        # JSON for parsing

Do not read snapshot files directly — always use CLI commands or MCP tools to inspect them.

Diagnosing Errors

When execution fails, check the latest snapshot:

execution.summary — blocksExecuted, blocksSucceeded, blocksFailed, totalDurationMs
execution.error — name, message, traceback (top-level error)
Per-block outputs — individual blocks have error output_type with ename, evalue, traceback

Quick error check:

deepnote inspect snapshots/*_latest.snapshot.deepnote -o json
deepnote run project.deepnote -o json   # Errors inline in output

Content Hash Verification

Each block in a snapshot has contentHash (SHA-256). If block content changed since the snapshot, the hash won't match — the output is stale.

Latest vs Timestamped

| Aspect | _latest | Timestamped | | ----------- | ----------------------------------- | ---------------------- | | Updated | Overwritten on each run | Immutable, one per run | | Consistency | May mix outputs from different runs | All from same run | | Use case | Quick access to recent results | Audit trail |

Editing Guidelines

When creating or modifying .deepnote files:

Block IDs - Generate random 32-character hex strings (e.g. crypto.randomUUID().replace(/-/g, ''))
Block groups - Each block needs a blockGroup (same hex format); blocks in the same group share a group ID
Sorting keys - Use lexicographic strings: a0, a1, ..., a9, b0, etc. Insert between existing keys for ordering
Content - Use YAML literal block scalar (|) for multi-line content to preserve newlines
Metadata - Use {} for defaults; add type-specific fields as needed

Important Policies

Stay in .deepnote format. When something goes wrong, do not fall back to converting to .ipynb and working in Jupyter format. The .deepnote format has better debugging tools (deepnote inspect, deepnote cat, deepnote lint, deepnote dag) that are not available for .ipynb files. Stay in .deepnote and use these tools to diagnose and fix issues.
Only convert on explicit request. Only use deepnote convert to export when the user explicitly asks for a format conversion.

Running After Edits

After creating or modifying blocks, always run the project to verify changes.

Prerequisites

Check if the CLI is installed:

deepnote --version

If not installed, find the best available Python and install via pip:

IDE environment — check for a deepnote.json file in .vscode/, .cursor/, or .agent/ (see IDE Environment Detection below) and use its venvPath
Project instructions — if the project has a .python-version file or pyproject.toml with requires-python, use the specified version
Project venv — look for .venv/bin/python, venv/bin/python, or env/bin/python
Homebrew Python — check if /opt/homebrew/bin/python3 or brew --prefix python3 exists
System Python — use python3 (preferred) or python

Install with the best available Python (must be >= 3.9):

<best-python> -m pip install deepnote-cli

If no suitable Python is available, install via npm instead:

npm install -g @deepnote/cli

IDE Environment Detection

The Deepnote extension for VS Code, Cursor, and Antigravity creates a virtual environment for each project. Before running, check if an IDE-configured environment exists so the CLI uses the same Python interpreter.

Look for a deepnote.json file in these directories (in order):

.vscode/deepnote.json
.cursor/deepnote.json
.agent/deepnote.json (Antigravity)

The file maps project IDs to virtual environments:

{
  "mappings": {
    "<project-id>": {
      "environmentId": "<env-id>",
      "venvPath": "/path/to/deepnote-envs/<env-id>"
    }
  }
}

To use the IDE environment:

Read the project.id from the .deepnote file
Check each deepnote.json for a matching key in mappings
If found, pass the venvPath to the CLI with --python:

deepnote run project.deepnote --python /path/to/deepnote-envs/<env-id>

If no IDE environment is found, omit --python and the CLI will use the system Python.

Running

deepnote run project.deepnote                         # Run full project
deepnote run project.deepnote --notebook "Analysis"    # Specific notebook
deepnote run project.deepnote --block abc123           # Specific block
deepnote run project.deepnote --dry-run                # Preview only
deepnote run project.deepnote -o json                  # JSON output

Checking Results

Inline output — stdout/stderr printed directly
Snapshot — outputs saved to snapshots/ directory (see Snapshots section above)
Exit codes — 0 success, 1 runtime error, 2 invalid usage
JSON — use -o json for structured per-block results

Workflow

Edit the .deepnote file
Run: deepnote run project.deepnote
If errors, check snapshot for details
Fix and re-run

CLI Quick Reference

| Command | Description | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | deepnote run [path] | Execute notebooks (.deepnote, .ipynb, .py, .qmd) | | deepnote convert <path> | Convert between formats (Jupyter, Quarto, Percent, Marimo) | | deepnote inspect [path] | Display file metadata | | deepnote cat <path> | Display block contents | | deepnote diff <a> <b> | Compare two files | | deepnote validate <path> | Schema validation | | deepnote lint [path] | Check a .deepnote or integrations yaml file for issues | | deepnote stats <path> | Project statistics | | deepnote analyze <path> | Comprehensive analysis with quality score | | deepnote dag show\|vars\|downstream | Dependency analysis | | deepnote split <path> | Split a multi-notebook file into one .deepnote per notebook. The init notebook (if any) becomes its own standalone file; each main file keeps initNotebookId so deepnote run resolves and runs the sibling init as a prelude. | | deepnote open <path> | Open in Deepnote Cloud |