# motherduck-build-dashboard
> Build a MotherDuck dashboard as a Dive, choosing the analytical story, metrics, and section queries.
Build a MotherDuck dashboard as a Dive, choosing the analytical story, metrics, and section queries.

[Use-case skill](/sql-reference/agent-skills/#use-case-skills) · [View source on GitHub](https://github.com/motherduckdb/agent-skills/tree/v3.0.0/skills/motherduck-build-dashboard)

:::info

This page shows the skill's `SKILL.md`: the instructions a coding agent loads when a task matches the description above. To install every MotherDuck skill in Claude Code, Codex, Cursor, or Gemini CLI, see [Install MotherDuck Skills](/key-tasks/ai-and-motherduck/agent-skills/). To install only this skill with the [Skills CLI](https://github.com/vercel-labs/skills), run:

```bash
npx -y skills add motherduckdb/agent-skills --skill motherduck-build-dashboard --yes --global
```

This skill relies on [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/), [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/), [`motherduck-create-dive`](/sql-reference/agent-skills/motherduck-create-dive/), and [`motherduck-manage-guides`](/sql-reference/agent-skills/motherduck-manage-guides/). Install those too, or install the full catalog.

:::

## Start here: Is a MotherDuck server active?

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.

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.
- 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.
- When the dashboard should trigger an action (approve, refresh, submit), add a write-back button that runs a Flight; see [`motherduck-create-dive`](/sql-reference/agent-skills/motherduck-create-dive/).
- Viewers can ask follow-up questions through the Dive's AI Chat, so name sections and metrics in business terms.

## 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. For a new dashboard or layout change, use the design defaults and responsive references in [`motherduck-create-dive`](/sql-reference/agent-skills/motherduck-create-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 writing Dive code and before every `save_dive`, `update_dive`, or `edit_dive_content`.
7. When the request includes creating or updating the Dive, save only after responsive, theme, query-state, and data validation. Before `save_dive` or `update_dive`, follow the review step that `get_dive_guide` sets for your client: when it asks you to show the final source or preview and get the user's go-ahead, do that once, unless the user already said to save without review.
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/3.0.0(harness-<harness>;llm-<llm>)`. If metadata is missing, fall back to `harness-unknown` and `llm-unknown`.

## Output

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

For explicit structured JSON requests, read [the output contract](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/EXECUTION_REFERENCE.md#structured-output). Otherwise use the format that fits the requested deliverable.

## References

Read only the sections relevant to the task; these are guidance, not a mandatory itinerary.

- [`references/DASHBOARD_IMPLEMENTATION_GUIDE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/DASHBOARD_IMPLEMENTATION_GUIDE.md) -- section-to-SQL mapping, TSX composition, and validation examples
- [`references/DASHBOARD_PATTERNS.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/DASHBOARD_PATTERNS.md) -- example dashboard compositions and reusable sections

## Examples

Read [the execution reference](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/EXECUTION_REFERENCE.md) only to run the bundled examples or reproduce their validation.

- [dashboard_story_example.py](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py)
- [dashboard_story_example.ts](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/artifacts/dashboard_story_example.ts)

## Related skills

Load related skills only for missing capabilities; reuse established context.

- [`motherduck-explore`](/sql-reference/agent-skills/motherduck-explore/) -- inspect the actual database before deciding the dashboard sections
- [`motherduck-query`](/sql-reference/agent-skills/motherduck-query/) -- validate each dashboard query
- [`motherduck-create-dive`](/sql-reference/agent-skills/motherduck-create-dive/) -- useSQLQuery, design defaults, responsive layout, theming, preview/save, and visual QA
- [`motherduck-duckdb-sql`](/sql-reference/agent-skills/motherduck-duckdb-sql/) -- resolve syntax and function questions

## Files in this skill

The agent reads these files when the instructions above point to them.

- [`artifacts/dashboard_story_example.py`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py)
- [`artifacts/dashboard_story_example.ts`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/artifacts/dashboard_story_example.ts)
- [`references/DASHBOARD_IMPLEMENTATION_GUIDE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/DASHBOARD_IMPLEMENTATION_GUIDE.md)
- [`references/DASHBOARD_PATTERNS.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/DASHBOARD_PATTERNS.md)
- [`references/EXECUTION_REFERENCE.md`](https://github.com/motherduckdb/agent-skills/blob/v3.0.0/skills/motherduck-build-dashboard/references/EXECUTION_REFERENCE.md)

## Docs this skill draws on

- [Creating Visualizations with Dives](https://motherduck.com/docs/key-tasks/dives/)
- [Theming and styling your Dives](https://motherduck.com/docs/key-tasks/dives/theming-and-styling-dives/)
- [Manage Dives as code](https://motherduck.com/docs/key-tasks/dives/managing-dives-as-code/)
- [Dive statuses](https://motherduck.com/docs/key-tasks/dives/dive-statuses/)
- [Using Guides to improve AI query accuracy and personalize agents](https://motherduck.com/docs/key-tasks/guides/)
- [motherduck.com/dive-gallery](https://motherduck.com/dive-gallery/)


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

URL-encode query parameter values and send a GET request:

```text
GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fsql-reference%2Fagent-skills%2Fmotherduck-build-dashboard%2F&page_title=motherduck-build-dashboard&text=<url-encoded user feedback, max 2000 characters>
```

Optionally append `&source=<url-encoded interface identifier>` such as `claude.ai` or `chatgpt`.

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed query parameters, and `429` when rate-limited.
