build-notebook - SKILL.md Agent Skill

name: build-notebook argument-hint: "[spec-path]" description: This skill should be used when the user asks to "build the notebook", "launch the dashboard", "generate the marimo notebook", or when an analysis_plan.md artifact exists and the user wants to assemble or regenerate the dashboard. Reads chart specs with ibis queries and altair code from analysis_plan.md, assembles a marimo Python file, validates, and launches. Do NOT use for exploring data or planning charts (use explore-data), building pipelines (use rest-api-pipeline toolkit), or deploying (use dlthub-platform toolkit).

Build notebook from spec

Read a <date>_<pipeline_name>_analysis_plan.md artifact and assemble a marimo notebook with all charts.

Parse $ARGUMENTS:

spec-path (optional): path to the analysis_plan.md file. If omitted, look for *_analysis_plan.md in the working directory. If multiple found, ask the user and stop.

Step 1: Read analysis_plan.md

Parse the analysis plan file for:

Connection section: pipeline name, dataset name, destination type
Chart N sections: each chart's question, type, SQL code, and altair code
Count the total number of charts to assemble

If the analysis plan file is missing or has no charts, tell the user to run explore-data first and stop.

Step 2: Assemble notebook

Generate <pipeline_name>_dashboard.py. Read references/notebook-patterns.md for the complete notebook structure, cell templates, and naming conventions before generating. Every chart cell must end with _chart on a bare line, then return — without the bare expression line, nothing renders.

Marimo patterns

For general marimo cell structure, reactivity, and best practices, fetch https://github.com/marimo-team/skills/blob/main/skills/marimo-notebook/SKILL.md. For SQL-specific patterns in marimo, fetch https://github.com/marimo-team/skills/blob/main/skills/marimo-notebook/references/SQL.md. For dlt-dashboard-specific templates, see references/notebook-patterns.md.

Step 3: Validate

Run marimo's linter to catch common mistakes:

uvx marimo check <pipeline_name>_dashboard.py

If validation fails:

Read the error output — marimo check reports specific issues (missing returns, variable conflicts, import errors).
Fix the reported issues in the notebook file.
Re-run uvx marimo check until it passes.

Step 4: Ensure dependencies

The notebook requires pandas, numpy, and altair which are not installed by dlt[hub]. In a dlthub workspace (dlthub init) they are already declared in pyproject.toml — running uv sync installs them.

Before launching, check if they are available. If any are missing, ask the user how they want to install them:

If they are declared in pyproject.toml (workspace scaffolded by dlthub init): run uv sync.
Otherwise: run uv add pandas numpy altair to add them to pyproject.toml.

Also add marimo if not already installed, and ibis-framework[duckdb] if any chart uses ibis.

Do NOT install packages without user confirmation.

Step 5: Launch

After validation passes, offer to launch in browser or skip.

If yes:

uv run marimo edit <pipeline_name>_dashboard.py --no-token

Tell the user the notebook is running (default: localhost:2718).

Regeneration

When re-invoked after iteration (see workflow.md): re-read the full analysis_plan.md and regenerate the entire notebook file, then validate and relaunch.

Troubleshooting

marimo check fails with variable conflicts

Two cells export the same variable name. Fix: follow the naming conventions in references/notebook-patterns.md.

marimo check fails with import errors

A dependency is missing from the environment. Install it with uv add <package> and re-check.

Notebook runs but charts are empty

The SQL query returns no rows. Common causes:

Filter is too restrictive — check where clauses.
Column names don't match schema — verify against get_table_schema.
Table is empty — check row_counts.

dlt.attach fails in notebook

Pipeline name is wrong or pipeline hasn't been run. Run dlthub local pipeline info <name> to verify.

Example

Input: 2026-03-10_orders_pipeline_analysis_plan.md with 2 charts (Monthly Revenue Trend + Revenue by Category)

Output: orders_pipeline_dashboard.py with 2 data cells + 2 chart cells, structured per references/notebook-patterns.md.

Validation: uvx marimo check orders_pipeline_dashboard.py → passes Launch: uv run marimo edit orders_pipeline_dashboard.py --no-token