16 added, 61 removed. Audit A to A.
---
name: motherduck-build-dashboard
- description: Build a live MotherDuck dashboard as a Dive. Use when composing one shareable KPI, trend, and breakdown story over existing MotherDuck data, especially when the result should stay a saved workspace artifact rather than a full application.
+ description: Build a MotherDuck dashboard as a Dive, choosing the analytical story, metrics, and section queries.
license: MIT
---
# Build an Analytics Dashboard
- Use this skill when the user wants a multi-section Dive-backed dashboard with a clear analytical story, not just a single chart.
-
- This is a use-case skill. It orchestrates `motherduck-explore`, `motherduck-query`, `motherduck-manage-guides`, `motherduck-create-dive`, and `motherduck-design-dive`; use `motherduck-duckdb-sql` as supporting reference when exact syntax matters.
-
## Start Here: Is a MotherDuck Server Active?
- - If a **remote MotherDuck MCP server** or **local MotherDuck server** is active, use it.
- - Discover the target database or workspace from the active context. Ask only when multiple plausible targets remain and the choice would materially change the dashboard.
- - Explore the live data model before choosing the dashboard structure:
- - available tables and views
- - business grain
- - key metrics
- - key dimensions
- - date columns
- - likely joins
-
- The discovered data model should determine the dashboard story and sections.
-
- If no server is active, use any supplied schema or table context. For planning work, proceed with explicit assumptions when safe; ask for missing schema details only when they block a reliable result.
+ Use an active remote MotherDuck MCP server or local MotherDuck server to inspect the in-scope database, schema, grain, keys, and relevant metrics. Reuse known context and narrow discovery to the requested work; do not scan the whole workspace by default. Let the actual data model shape the result.
- For lower-level Dive mechanics, use `motherduck-create-dive`.
+ Resolve the target from the request or active context. Ask only if ambiguity materially affects the result. Without a server, use supplied schema and explicit assumptions for planning; do not imply live validation.
## Dashboard Defaults
- One story per dashboard.
- - One KPI group that stacks and reflows by viewport.
- - One primary trend chart.
- - Zero or one supporting chart.
- - Zero or one detail table.
+ - Start with a responsive KPI group, a primary chart, and supporting detail where it helps the decision. Add sections only when the question or data warrants them; these are defaults, not fixed chart quotas.
- Heavy shaping in SQL, not React.
## Workflow
1. Inspect the available MotherDuck server or supplied schema context.
2. Read relevant root/domain Guides, then explore the real schema and validate the governed metrics.
3. Pick the dashboard story.
4. Write one query per section.
- 5. Apply `motherduck-design-dive`: start at 320 px, reserve the filter surface, use the reusable light/dark token system, and define the desktop reflow.
+ 5. For a new dashboard or layout change, use the responsive and theme guidance in `motherduck-design-dive`; preserve the existing design for a scoped SQL or text edit.
6. Compose the dashboard in a Dive. When MotherDuck MCP is available, call `get_dive_guide` before `save_dive` or `update_dive`.
7. When the request includes creating or updating the Dive, save only after responsive, theme, query-state, and data validation; do not add a second approval gate for the requested in-scope write.
8. Read the saved Dive back. Leave work-in-progress as Draft; promote it to Ready only after the requested delivery is validated. Reuse Endorsed Dives before rebuilding an existing trusted answer.
Match execution to the request: answer, review, or planning work returns the requested dashboard artifacts; build or change work creates or updates the requested in-scope Dive and validates it. Ask before destructive replacement, unrelated external writes, or a material expansion of scope.
When this skill produces a native DuckDB (`md:`) connection, watermark it with `custom_user_agent=agent-skills/2.6.0(harness-<harness>;llm-<llm>)`. If metadata is missing, fall back to `harness-unknown` and `llm-unknown`.
## Output
- The output of this skill should be:
+ For a full engagement, cover the following as relevant to the request:
- the dashboard story
- the section list
- the validated SQL for each section
- the Dive implementation plan
- the save/update path
- If the caller explicitly asks for structured JSON, return raw JSON only with no Markdown fences or prose before/after it.
- This is mainly for automated tests, regression checks, or downstream tooling that needs a stable machine-readable shape. Normal human-facing use of the skill can stay in prose unless JSON is explicitly requested.
-
- Use this exact top-level shape when JSON is requested:
-
- ```json
- {
- "summary": {},
- "assumptions": [],
- "implementation_plan": [],
- "validation_plan": [],
- "risks": []
- }
- ```
+ For explicit structured JSON requests, read [the output contract](references/EXECUTION_REFERENCE.md#structured-output). Otherwise use the format that fits the requested deliverable.
## References
- - `references/DASHBOARD_IMPLEMENTATION_GUIDE.md` -- preserved detailed workflow and layout guidance that used to live in this skill
- - `references/DASHBOARD_PATTERNS.md` -- example dashboard compositions and reusable sections
-
- ## Runnable Artifact
-
- - `artifacts/dashboard_story_example.py` -- MotherDuck-backed Python example that produces KPI, trend, breakdown, and detail outputs for one dashboard story
- - `artifacts/dashboard_story_example.ts` -- TypeScript companion artifact with the same dashboard output contract
-
- Run it with:
-
- ```bash
- uv run --with duckdb python skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py
- ```
+ Read only the sections relevant to the task; these are guidance, not a mandatory itinerary.
- Run the same artifact against a temporary MotherDuck database:
+ - `references/DASHBOARD_IMPLEMENTATION_GUIDE.md` -- section-to-SQL mapping, TSX composition, and validation examples
+ - `references/DASHBOARD_PATTERNS.md` -- example dashboard compositions and reusable sections
- ```bash
- MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
- uv run --with duckdb python skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py
- ```
+ ## Examples
- Validate the TypeScript companion artifact:
+ Read [the execution reference](references/EXECUTION_REFERENCE.md) only to run the bundled examples or reproduce their validation.
- ```bash
- uv run scripts/test_typescript_artifacts.py
- ```
+ - [dashboard_story_example.py](artifacts/dashboard_story_example.py)
+ - [dashboard_story_example.ts](artifacts/dashboard_story_example.ts)
## Related Skills
+
+ Load related skills only for missing capabilities; reuse established context.
- `motherduck-explore` -- inspect the actual database before deciding the dashboard sections
- `motherduck-query` -- validate each dashboard query
- `motherduck-create-dive` -- useSQLQuery, theming, preview/save, loading, and visual mechanics
- `motherduck-design-dive` -- responsive layout, filter capacity, light/dark tokens, reusable components, and visual QA
- `motherduck-duckdb-sql` -- resolve syntax and function questions