Skill v1.0.0
Trusted Publisher100/100version: "1.0.0" 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. Requiresname; accepts optionalfolderId.create_notebook: create an empty notebook in a project. RequiresprojectId; accepts optionalname.create_block: create a block in a notebook. RequiresnotebookIdandtype; accepts optionalcontent,metadata,position,includeNotebookBlockIds, and SQL-onlyintegrationId.update_block: update an existing block. RequiresblockId; acceptscontent, SQL-onlyintegrationId, or both. At least one ofcontentorintegrationIdis required.reorder_notebook_blocks: move one or more existing blocks in a notebook. RequiresnotebookId, non-empty uniqueblockIdsin the desired moved-block order, andplacement.
Editing Workflow
- Resolve ambiguous names and IDs before writing. Use
get_mefor workspace identity,searchorlist_projectsfor projects/notebooks,get_notebookfor current block order, andlist_integrationsfor SQL connections. - Treat
create_project,create_notebook, andcreate_blockas non-idempotent. Repeating the same call creates another resource. - Use
create_projectonly when the user wants a new project. A created project includes a default empty notebook; if the workflow later callscreate_notebook, the newcreate_notebookresult becomes the active notebook for blocks, verification, links, and run prompts. - Use
create_notebookonly when adding an empty notebook to a project. It does not accept starter blocks; capture the returned notebook ID and create blocks afterward withcreate_blockin that exact notebook. - Use
create_blockfor each new block. Omitpositionto append, or pass a zero-basedpositionwhen placement matters. - Use
update_blockwhen changing an existing block. It updates content and/or SQL integration in place; it does not create a new block. - Pass
includeNotebookBlockIds: truewhen the final block order matters, especially for ordered inserts or multi-block scaffolds. - Use
reorder_notebook_blockswhen moving existing blocks. It preserves the relative order of blocks omitted fromblockIdsand returns the final active block order. - Verify meaningful edits with
get_notebookafter block creation, block update, or block reordering when order, integration attachment, or multi-block content matters. - 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_projectis called, use the default notebook created with the project as the active notebook when blocks or a notebook link are needed. - If
create_notebookis called, use the notebook ID returned bycreate_notebookas the active notebook, even when the same project also has an initial default notebook. - Create blocks, verify with
get_notebook, build notebook links, and ask about running against the active notebook ID. Do not link to or run the project's default notebook unless it is the active notebook. - When both a project link and notebook link are useful, label them separately so the notebook link points to the newly created or edited notebook.
Block Creation Guidance
Choose the block type that matches Deepnote's block vocabulary. Common types include code, sql, markdown, input blocks such as input-text, input-select, input-checkbox, and text-cell variants such as text-cell-h1, text-cell-p, and text-cell-callout.
For SQL blocks:
- Resolve the integration first with
list_integrationswhen the user gives a connection name. - Pass the connection as top-level
integrationId. - Do not put
sql_integration_idinsidemetadata. - Do not pass
integrationIdfor non-SQL blocks.
For input blocks, put block-type configuration in metadata and keep content for the visible/default textual content when applicable. Preserve existing notebook naming and variable conventions when adding inputs near related blocks.
Block Update Guidance
Before updating a block, call get_notebook and identify the target block ID, current type, current content, and visible SQL integration when relevant. Ask a clarifying question only when the target block or requested replacement is ambiguous.
Use update_block when the user wants to revise an existing cell or block. Send the full replacement content for the block content you want saved; do not assume partial snippets will be merged unless the user explicitly asks for exactly that replacement. Use create_block only when the user wants an additional new block.
For SQL blocks, update_block can update content, integrationId, or both in a single call. Resolve the integration with list_integrations when the user gives a connection name, then pass the connection as top-level integrationId. Do not put sql_integration_id in metadata.
Do not pass integrationId for non-SQL blocks. The app tools do not expose block type changes, arbitrary metadata updates, deletion, or saved input-default edits through update_block; say so instead of claiming those changes were applied.
Block Reordering Guidance
Before moving blocks, call get_notebook and identify the current ordered block IDs. Ask a clarifying question only when the target block or destination is ambiguous.
Call reorder_notebook_blocks with:
notebookId: the target notebook ID.blockIds: a non-empty list of unique block IDs to move, ordered exactly as they should appear as the moved group.placement:{ "type": "start" },{ "type": "end" }, or{ "type": "after", "blockId": "anchor-block-id" }.
For placement.type: "after", the anchor blockId must be an active block in the same notebook and must not be included in blockIds. Use start or end instead of manufacturing an anchor when the user asks for the beginning or end of the notebook.
After reordering, report the moved block IDs and final order when useful. If the tool returns the same final order, treat it as a no-op rather than an error.
Response Style
After a successful edit, report the created project, active notebook, and block names/IDs when relevant, plus placement or final block order when useful. Include Deepnote links when they can be safely constructed with deepnote-links; for newly created notebooks, the notebook link must use the active notebook ID from create_notebook or the default notebook created by create_project when no separate notebook was created.
If a notebook was created or scaffolded and not already run, end with a short question asking whether to run the active notebook in Deepnote now. Do not call create_run until the user confirms; after confirmation, use deepnote-data-execution and pass the active notebook ID.
If a write tool returns an error, surface the user-facing message concisely and name the likely fix: missing permission, missing target resource, invalid block type, invalid position or placement, duplicate notebook name, suspended project, or incompatible SQL integration.