Deepnote

View saved version →

---
name: deepnote
description: Use when a task mentions Deepnote, the connected Deepnote app, Deepnote OAuth connection, Deepnote docs, projects, workspaces, notebooks, blocks, integrations, or notebook runs.
---

# Deepnote Router

Use the connected Deepnote app tools as the source of truth for hosted Deepnote state. Prefer them over browser automation, screenshots, ad hoc HTTP calls, or local filesystem guesses for Deepnote projects, notebooks, blocks, integrations, docs, or runs.

If the Deepnote app tools are unavailable, say so and ask the user to connect the Deepnote app with OAuth. Do not pretend to have inspected Deepnote state.

When the user asks what Deepnote can do, start with:

Deepnote can identify the current workspace, search resources, list projects and integrations, inspect notebooks, create and edit notebook structure, map integration usage and cached table structure, read Deepnote docs, run notebooks, and fetch run status and history.

## Capability Map

Use the current tool surface only; if a required tool is absent, say which capability is missing.

- Identity and discovery: `get_me`, `search`, `list_projects`.
- Notebook inspection: `get_notebook`.
- Notebook editing: `create_project`, `create_notebook`, `create_block`, `update_block`, `reorder_notebook_blocks`.
- Integrations: `list_integrations`, `get_integration`, `list_integration_project_usages`, `list_integration_notebook_usages`, `list_integration_block_usages`.
- Execution: `create_run`, `list_notebook_runs`, `get_run`.
- Docs: `list_docs`, `get_doc`.

## Route By Intent

| User asks for | Use |
| --- | --- |
| Workspace overview, heartbeat, active/scheduled notebooks, broad inventory | `get_me`, `list_projects`, `list_integrations`, and [references/workspace-summary.md](references/workspace-summary.md) |
| Notebook contents, inputs, SQL, blocks, outputs, review, or explanation | `deepnote-notebooks` |
| Project/notebook creation, adding cells, updating cells, moving/reordering cells, scaffolded notebook content | `deepnote-notebook-editing` |
| Notebook execution, run status, recent/failed runs, run history, snapshots, integration usage, cached tables/columns | `deepnote-data-execution` |
| Project, notebook, workspace, or share links | `deepnote-links` |
| Product docs or how-to questions | `list_docs`, then `get_doc` |

## Routing Defaults

1. Resolve ambiguous names and IDs with `search`, `list_projects`, or `list_integrations`.
2. Use `get_me` when workspace identity, connected user, caller role, or OAuth context matters.
3. Read with `get_notebook` before reasoning about notebook blocks, inputs, latest run metadata, or before editing notebook structure.
4. Use `get_integration` for cached table, schema, column, or table-existence questions about an integration.
5. Use `list_notebook_runs` for run history or failed-run searches; use `get_run` for one selected run's status, errors, or snapshot.
6. Use specialist skills for any workflow with detailed rules. Keep this skill as the router.

## Global Guardrails

- Never expose tokens, secret values, raw credentials, or sensitive integration metadata. Refer to secret names only.
- Treat project creation, notebook creation, block creation, block updates, block reordering, and notebook runs as persistent or stateful actions. Resolve targets carefully and report affected IDs.
- Do not run a notebook unless the user asks for execution, clearly needs fresh results, or confirms a creation workflow's final run prompt. Creation workflows may ask whether to run the newly created notebook, but must not run it preemptively. Run input overrides apply only to that run.
- Do not expose `snapshotDownloadUrl` values unless the user asks for a download/file handoff; use inline snapshots only when output or error details are needed.
- Use cached integration structure when available, but do not claim a fresh live database scan, row preview, single-block execution, environment mutation, permission change, publishin

Preview of the first 4,000 characters. Read full instructions →

Referenced files: 1 — file references are metadata, not package contents.

View saved version →

---
name: deepnote-data-execution
description: Use when running Deepnote notebooks, inspecting notebook inputs, reviewing integration references and cached table structure, listing run history, or interpreting run status and snapshot outputs through the Deepnote app tools.
---

# Deepnote Data And Execution

## Available Context

Use the connected Deepnote app tools for the execution and context they currently expose:

- `get_notebook` for notebook blocks, input variables, last-run metadata, and integration references visible in blocks.
- `list_integrations` for workspace integration names and types.
- `get_integration` for integration details and cached table structure, optionally filtered by `databaseName`, `schemaName`, or exact `tableName`.
- `list_integration_project_usages`, `list_integration_notebook_usages`, and `list_integration_block_usages` for direct integration usage mapping.
- `create_run` to start full-notebook execution, optionally with input values.
- `list_notebook_runs` for historical notebook runs, newest first, with `pageSize` and `pageToken` pagination.
- `get_run` for run status, errors, completion time, and run snapshots. When `snapshotDelivery` is omitted, it returns a short-lived `snapshotDownloadUrl` when a snapshot is available; this is equivalent to `snapshotDelivery: "downloadUrl"`. Request `snapshotDelivery: "inline"` only when you need `snapshotContent` in the tool response.
- `get_me` for the authenticated workspace, connected user, and caller access level when execution permissions or workspace identity matter.

Use `get_integration` for cached table and column structure when the user asks about integration schemas, tables, columns, or whether a table exists. Do not claim live database introspection, table previews, query previews, file metadata, or environment configuration unless a current Deepnote app tool explicitly exposes that data.

## Execution Workflow

1. Read the notebook context first with `get_notebook`.
2. Identify whether the user needs a fresh run, a specific run status, or notebook run history.
3. If the notebook has inputs and the user supplied values, map values to the exact input `name` fields returned by `get_notebook`.
4. Check whether execution may mutate data, call external services, trigger schedules, or consume significant compute.
5. Use `create_run` only for full-notebook execution by `notebookId`; the Deepnote app does not currently expose single-block execution.
6. If `create_run` returns a tool error, report that error and stop; do not call `get_run` unless a run ID was returned.
7. Use `get_run` to inspect status, errors, completion time, and snapshot availability before reporting results. For routine status checks, omit `snapshotDelivery` so the default download URL delivery is used; request `snapshotDelivery: "inline"` when you need to inspect notebook outputs, snapshot errors, or result details.

Before starting a run, inspect the notebook for cells that print environment variables, secrets, credentials, or entire configuration objects. If found, warn the user and get explicit confirmation before running. Also warn before running notebooks that start servers, send bulk requests, call external services, or mutate data.

## Run History

Use `list_notebook_runs` when the user asks about recent runs, failed runs, run history, or anything older than the latest run metadata returned by `get_notebook`. The tool returns runs newest first with `runId`, `notebookId`, `status`, `createdAt`, `completedAt`, and `pagination`.

For short history requests, call `list_notebook_runs` with the default `pageSize` of 20. For broader audits, use `pageSize: 100` and follow `pagination.nextPageToken` while `pagination.hasMore` is true, stopping once you have enough evidence for the user's question.

Use `get_run` only after selecting a specific run that needs detail, snapshot availability, output inspection, or failure debugging. If the user asks "why did the last run fail?" and no 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: deepnote-links
description: Use when a task asks for Deepnote URLs, links, project links, notebook links, workspace links, share links, UTM/campaign links, or when a Deepnote response should include clickable links built from Deepnote app project, notebook, or workspace data.
---

# Deepnote Links

Use this skill to build user-facing Deepnote web links from Deepnote app tool data. Prefer links grounded in `get_me`, `list_projects`, `search`, and `get_notebook` responses instead of guessing from names alone. Every project and notebook link built from Deepnote app data must include the UTM parameters below.

## Inputs To Resolve

1. Call `get_me` when workspace-aware links are useful. Use `workspace.id` and `workspace.slug`; do not use OAuth tokens, user email, or other auth details in links or summaries.
2. Resolve the project with `list_projects` or `search`. Use the project `id`, `name`, and `slug` if the app response exposes one.
3. Resolve notebook links with `get_notebook` when possible. Use the notebook `id`, `name`, and parent project data.
4. If the exact project or notebook is ambiguous, ask a short clarification or provide a compact candidate list with links only for unambiguous matches.

## Creation Link Rules

When linking after a creation workflow, use the resource IDs returned by the write tools as the source of truth:

- If `create_notebook` returned a notebook, build the notebook link for that returned notebook ID. Do not substitute the first notebook on the project or the default notebook created by `create_project`.
- If `create_project` created a project and no separate `create_notebook` call was made, use the default notebook created with the project only when a notebook link is needed for that active notebook.
- If both the project default notebook and a later `create_notebook` result are present, the later `create_notebook` result is the notebook to link unless the user explicitly asks for the default notebook.
- If parent project data is missing for the created notebook, call `get_notebook` for the target notebook ID or use the known project ID from the creation workflow before constructing the link.

## URL Shapes

Use the production web origin `https://deepnote.com` for Deepnote app links. Do not derive the web origin from API or tool hosts.

Prefer workspace-scoped links when `get_me` returns both `workspace.slug` and `workspace.id`:

```text
workspaceSlugWithId = {workspace.slug}-{workspace.id}
workspace link = {origin}/workspace/{workspaceSlugWithId}
project link = {origin}/workspace/{workspaceSlugWithId}/project/{projectSegment}
notebook link = {origin}/workspace/{workspaceSlugWithId}/project/{projectSegment}/notebook/{notebookSegment}
```

If workspace data is not available, use the non-workspace project route:

```text
project link = {origin}/project/{projectSegment}
notebook link = {origin}/project/{projectSegment}/notebook/{notebookSegment}
```

## Slug Segments

Use the most canonical segment available:

1. If the app response exposes a `slug`, use it.
2. Otherwise, for simple names, build a readable segment as `{slugifiedName}-{id}`.
3. If exact slugification is uncertain, the name is missing, or the name has unusual characters, use the ID alone.

Deepnote project routing accepts UUID-only project segments, so `{project.id}` is the safest fallback. Notebook routing uses ID-only segments when a notebook name is not available, so `{notebook.id}` is the safest notebook fallback.

Deepnote's readable slugs are created with strict slugification: spaces become hyphens, `/` becomes `-`, unsafe characters are stripped or normalized, and case is preserved. Examples:

```text
Subject Tracker + 0508fc64-b2c8-4982-b6a0-2590c94b6000
=> Subject-Tracker-0508fc64-b2c8-4982-b6a0-2590c94b6000

folder/notebook 10% + a1b2c3d4
=> folder-notebook-10percent-a1b2c3d4
```

## Optional Suffixes

- File paths, when exposed and requested, append after the project segment as `/{encodeURIComponent(filePath)}`.
- 

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: deepnote-notebook-editing
description: Use when creating Deepnote projects or notebooks, adding or updating blocks or cells, moving existing blocks, scaffolding notebook content, inserting SQL/code/markdown/input blocks, or otherwise editing notebook structure through the Deepnote app tools.
---

# Deepnote Notebook Editing

## When To Use

Use this skill when the user asks to create a Deepnote project, create a notebook, add a block or cell, update an existing block or cell, move or reorder existing blocks, scaffold starter notebook content, insert code, SQL, markdown, or input blocks, or make a structural notebook edit supported by the current Deepnote app write tools.

This workflow requires the connected Deepnote app to expose the write tools needed for the requested edit. Use `create_project`, `create_notebook`, and `create_block` for creation workflows; use `update_block` for changing existing block content or SQL integration; use `reorder_notebook_blocks` for moving existing blocks. If the required tool is not visible in the current session, do not claim editing support; explain which app tool is missing.

The editing surface covered by this skill is:

- `create_project`: create a new project. Requires `name`; accepts optional `folderId`.
- `create_notebook`: create an empty notebook in a project. Requires `projectId`; accepts optional `name`.
- `create_block`: create a block in a notebook. Requires `notebookId` and `type`; accepts optional `content`, `metadata`, `position`, `includeNotebookBlockIds`, and SQL-only `integrationId`.
- `update_block`: update an existing block. Requires `blockId`; accepts `content`, SQL-only `integrationId`, or both. At least one of `content` or `integrationId` is required.
- `reorder_notebook_blocks`: move one or more existing blocks in a notebook. Requires `notebookId`, non-empty unique `blockIds` in the desired moved-block order, and `placement`.

## Editing Workflow

1. Resolve ambiguous names and IDs before writing. Use `get_me` for workspace identity, `search` or `list_projects` for projects/notebooks, `get_notebook` for current block order, and `list_integrations` for SQL connections.
2. Treat `create_project`, `create_notebook`, and `create_block` as non-idempotent. Repeating the same call creates another resource.
3. Use `create_project` only when the user wants a new project. A created project includes a default empty notebook; if the workflow later calls `create_notebook`, the new `create_notebook` result becomes the active notebook for blocks, verification, links, and run prompts.
4. Use `create_notebook` only when adding an empty notebook to a project. It does not accept starter blocks; capture the returned notebook ID and create blocks afterward with `create_block` in that exact notebook.
5. Use `create_block` for each new block. Omit `position` to append, or pass a zero-based `position` when placement matters.
6. Use `update_block` when changing an existing block. It updates content and/or SQL integration in place; it does not create a new block.
7. Pass `includeNotebookBlockIds: true` when the final block order matters, especially for ordered inserts or multi-block scaffolds.
8. Use `reorder_notebook_blocks` when moving existing blocks. It preserves the relative order of blocks omitted from `blockIds` and returns the final active block order.
9. Verify meaningful edits with `get_notebook` after block creation, block update, or block reordering when order, integration attachment, or multi-block content matters.
10. Do not run the notebook after editing unless the user explicitly asks for execution or confirms a final run prompt. After creating or scaffolding a notebook, ask whether to run that exact notebook in Deepnote.

## Creation Target Tracking

For creation workflows, keep one active target notebook:

- If only `create_project` is called, use the default notebook created with the project as the active notebook when blocks or a notebook link are needed.
- If `c

Preview of the first 4,000 characters. Read full instructions →

View saved version →

---
name: deepnote-notebooks
description: Use when reading, reviewing, inspecting, or reasoning about hosted Deepnote notebooks, blocks, inputs, SQL, Python, or notebook outputs through the Deepnote app tools.
---

# Deepnote Notebooks

## Notebook Inspection Workflow

1. Resolve the target notebook with `search` or project context before using `get_notebook`.
2. Read the notebook with `get_notebook` before answering questions about structure, inputs, blocks, or latest run state.
3. Preserve distinctions between block types, notebook inputs, code, SQL, markdown, and metadata in your reasoning.
4. When reporting inputs, include the input `name`, `type`, current `value`, and `label` when useful.
5. When SQL connection usage matters, use `list_integrations` and the integration usage tools to confirm project, notebook, or block references instead of inferring solely from names. When table, schema, or column context matters, use `get_integration` for cached structure.
6. When asked to review or explain a notebook, ground the answer in specific notebook/block names or IDs when useful.
7. If the user asks to create a project, create a notebook, add blocks/cells, update existing blocks/cells, or scaffold notebook content, use the `deepnote-notebook-editing` skill.
8. If the user asks for recent runs, failed runs, or run history, use `list_notebook_runs` before selecting a run for `get_run`.

## Notebook Inspection Output

Great notebook-inspection output should help the user decide what the notebook does, whether it is safe to run, and what to do next. Prefer this structure:

Keep notebook inspection brief and high signal by default. Lead with the answer, then include only the tables or cautions that materially help the user. Omit exhaustive block listings, raw code, and long outputs unless the user asks for more detail.

1. Start with a one-sentence brief: `Notebook "Name" in project "Project" has 12 blocks, 2 inputs, 1 visible connection, and last ran successfully on YYYY-MM-DD HH:MM UTC.`
1. Show a compact status table:

| Field | Value |
| --- | --- |
| Project | `Project name` |
| Notebook | `Notebook name` |
| Notebook ID | `notebook-id` |
| Scheduled | `Yes` or `No` |
| Last Run | `status/date/run id` or `No run visible` |
| Visible Connections | `Integration name (type)` or `None visible via app tools` |

1. If inputs exist, add an inputs table:

| Input | Type | Current Value | Label |
| --- | --- | --- | --- |
| `input_name` | `text` | `safe summary or value` | `Human label` |

1. Add a block map when useful, especially for reviews and debugging:

| Order | Type | Purpose | Connection / Output |
| --- | --- | --- | --- |
| `1` | `sql` | `SELECT demo.gapminder sample` | `Clickhouse (clickhouse)` |

1. Add `Cautions` only when actionable: cells that print environment variables, hard-coded credentials, mutating external calls, long-running servers, large dataset dumps, missing inputs, failed/pending last runs, SQL blocks whose integration is not visible, or integration usage that was not checked when it matters.
1. End with `Useful Next Actions` only when it helps, such as run notebook, inspect latest run, list recent runs, map integrations, summarize outputs, or review risky cells.

When the Deepnote app tools do not expose a detail, say `Not visible via app tools` rather than inferring from names. Keep raw code excerpts short; summarize large cells and mention block IDs when useful.

## Code And Output Handling

- Before suggesting code changes, inspect nearby blocks for imports, shared variables, SQL connections, inputs, and upstream assumptions.
- Prefer deterministic notebook code. Avoid hidden global state, implicit external files, or hard-coded credentials.
- Do not claim an edit was applied unless a write-capable tool is available and reports success. For project, notebook, block creation, and existing block updates, use `deepnote-notebook-editing`.
- If you run a notebook, pass requested input values through `create_ru

Preview of the first 4,000 characters. Read full instructions →