Skip to content

rbutinar/ade-ops / .agents/skills/fabric-notebook-deploy

fabric-notebook-deploy

Verified

Deploy a Notebook to a Fabric Workspace

/fabric-notebook-deploy — Deploy a Notebook to a Fabric Workspace

You are deploying a Python notebook (Databricks-style .py or plain .ipynb) to a Microsoft Fabric workspace.

This skill is the Fabric counterpart of /databricks-deploy.

Command (start here)

The framework ships this as a runnable command — convert + create/update in one call, no MCP needed (Fabric auth from az login or a service principal in credentials.yaml):

python -m core.cli fabric-notebook-deploy path/to/nb.py --env dev
python -m core.cli fabric-notebook-deploy path/to/nb.py --workspace {ws_id} --name MyNotebook
python -m core.cli fabric-notebook-deploy --workspace {ws_id} --list     # read-only listing

It resolves the workspace (--workspace > overlay power_bi.workspace_id > platforms.fabric.workspace_id), converts a Databricks-style .py via the in-repo databricks_to_ipynb parser (.ipynb passes through), confirms before writing, then creates or updates the Fabric Notebook item and logs to ops.log. Structural conversion only — semantic rewrites (dbutils.fs → mssparkutils.fs, Unity Catalog → Lakehouse) belong to /migration-assess.

The steps below document what the command does end-to-end (and the building blocks — read_and_convert, FabricConnector) for when you need to extend it (e.g. the optional move-to-folder step the CLI does not yet cover).

Prerequisites

  • FabricConnector credentials configured in credentials.yaml (see core/connectors/fabric.py docstring)
  • az login --allow-no-subscriptions to the target tenant, or service principal in credentials.yaml under fabric.{client_id, client_secret, tenant_id}
  • For .py Databricks-style sources: the in-repo converter core/parsers/databricks_to_ipynb.py (no external dependency)
  • Contributor access on the target workspace

Usage

/fabric-notebook-deploy {local_path} --env {env}               # deploy to env's workspace
/fabric-notebook-deploy {local_path} --workspace {ws_id}       # explicit workspace override
/fabric-notebook-deploy {local_path} --env {env} --folder {f}  # place under a workspace folder
/fabric-notebook-deploy --list --env {env}                     # list notebooks in workspace

Arguments via $ARGUMENTS:

  • positional local_path — .py (Databricks-style or plain) or .ipynb
  • --env {env} — resolves workspace from overlay.power_bi.workspace_id or env_config
  • --workspace {ws_id} — override workspace
  • --folder {name} — place under a workspace folder (Fabric requires create-in-root-then-move)
  • --list — read-only listing of notebooks already in the workspace
  • --name {display_name} — override display name (defaults to source filename)

Behavior

Step 1: Resolve Project & Workspace

Same pattern as /powerbi-publish:

overlay.power_bi.workspace_id            # preferred
environments.{env}.platforms.fabric.workspace_id  # fallback

Step 2: Read & Convert Source

read_and_convert handles both formats — .py Databricks-style sources are converted, .ipynb files pass through unchanged:

from core.parsers.databricks_to_ipynb import read_and_convert
notebook_content = read_and_convert(local_path)

What the converter does:

  • # Databricks notebook source header → stripped
  • # COMMAND ---------- → cell boundary
  • # MAGIC %md → markdown cell
  • # MAGIC %sql → %%sql code cell; %pip / %run / etc. preserved as magics
  • a plain .py with no Databricks markers → a single code cell
  • an .ipynb source → passed through unchanged

Structural translation only — semantic rewrites (dbutils.fs → mssparkutils.fs, Unity Catalog → Lakehouse paths) are out of scope and belong to /migration-assess.

Step 3: Check Existing

from core.connectors.fabric import FabricConnector
connector = FabricConnector.from_credentials(load_credentials(project_root))
items = connector.client.list_items(workspace_id, item_type="Notebook")
existing = next((i for i in items if i["displayName"] == display_name), None)

Step 4: Build Fabric Definition

import base64, json
parts = [
    {
        "path": "notebook-content.ipynb",
        "payload": base64.b64encode(json.dumps(notebook_content).encode()).decode(),
        "payloadType": "InlineBase64",
    },
    # Fabric Notebook items also require .platform metadata:
    {
        "path": ".platform",
        "payload": base64.b64encode(json.dumps({
            "$schema": ".../platformProperties/2.0.0/schema.json",
            "metadata": {"type": "Notebook", "displayName": display_name},
            "config": {"version": "2.0", "logicalId": "00000000-0000-0000-0000-000000000000"},
        }).encode()).decode(),
        "payloadType": "InlineBase64",
    },
]
definition = {"format": "ipynb", "parts": parts}

Step 5: Confirmation Gate

Before pushing to cert or prod, show:

Notebook deploy — {env}:

  • Source: {local_path}
  • Target: {workspace_id}{/folder}
  • Action: {Create | Update existing {item_id}}

Proceed? (yes/no — prod requires double-confirm)

Step 6: Deploy

Create:

result = connector.client.create_item(
    workspace_id, display_name=display_name, item_type="Notebook", definition=definition,
)
notebook_id = result["id"]

Update:

connector.client.update_item_definition(workspace_id, existing["id"], definition)
notebook_id = existing["id"]

Poll the LRO on 202.

Step 7: Move to Folder (Optional)

Fabric API doesn't support creating items directly inside folders with a definition — must create in root, then move:

POST /v1/workspaces/{ws_id}/items/{notebook_id}/move
{"folderId": "{folder_id}"}

Resolve folder_id via GET /v1/workspaces/{ws_id}/folders (filter by displayName).

Step 8: Log

{ISO_timestamp} | {role} | FABRIC-NB-DEPLOY | {env} | {local_path} -> {workspace_id}/{folder}: {created|updated} {notebook_id} | {ok|fail}

Error Handling

ErrorCauseFix
401 after az loginToken cache staleForce-refresh via connector.auth.get_token(force_refresh=True)
403 on workspaceLacks Contributor roleRequest access from workspace admin
409 LockConflictConcurrent operation on the notebookWait 30s and retry
Invalid notebook formatSource doesn't match expected formatUse Databricks-style or .ipynb
Folder not foundFolder hasn't been created yetCreate via Fabric portal or extend skill to create folders

Notes

  • Fabric Notebook items support format: ipynb (canonical) and format: py (Spark Python). The converter currently always produces ipynb.
  • Token cache (when using MSAL device-code) lives at ~/.ade/fabric_token_cache.json once msal_cache is ported.
  • For Git-integrated workspaces, deployed notebooks will also sync to the Git repo on the next sync cycle.
  • Large notebooks may take longer (base64 encoding overhead). The Fabric API timeout is 100s — for very large notebooks consider splitting cells.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 321kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 197kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall