Back to Details

motherduck-build-dashboard

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
, and 
motherduck-create-dive
; use 
motherduck-duckdb-sql
as supporting reference when exact syntax matters.
当用户需要一个基于Dive的多板块仪表盘，且包含清晰的分析逻辑，而非仅单一图表时，可使用本技能。
这是一个场景化技能，它协调
motherduck-explore
、
motherduck-query
和
motherduck-create-dive
；当需要精确语法时，可参考
motherduck-duckdb-sql
作为辅助。

Start Here: Is a MotherDuck Server Active?

第一步：是否有活跃的MotherDuck服务器？

Always determine this before designing the dashboard.
  • If a remote MotherDuck MCP server or local MotherDuck server is active, use it.
  • If the target database is unclear, ask which database or workspace the dashboard should run against.
  • 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, ask for a table list or schema excerpt and make the assumptions visible.
在设计仪表盘前，务必先确认这一点。
  • 若存在远程MotherDuck MCP服务器或本地MotherDuck服务器处于活跃状态，请直接使用。
  • 若目标数据库不明确，请询问仪表盘应基于哪个数据库或工作空间运行。
  • 在选择仪表盘结构前，先探索实时数据模型：
    • 可用的表和视图
    • 业务粒度
    • 关键指标
    • 关键维度
    • 日期列
    • 可能的关联关系
探索到的数据模型将决定仪表盘的分析逻辑和板块划分。
若没有活跃服务器，请索要表列表或模式片段，并明确说明所做的假设。

Use This Skill When

适用场景

  • The user wants KPIs plus trend and breakdown views in one artifact.
  • The result should be a saved, shareable Dive.
  • The work needs dashboard composition, not just chart mechanics.
  • The result is a workspace analytics surface, not a customer-facing product backend.
For lower-level Dive mechanics, use 
motherduck-create-dive
.
  • 用户需要在一个工件中整合KPI、趋势视图和细分视图。
  • 结果需保存为可共享的Dive。
  • 工作内容为仪表盘组合，而非仅图表制作。
  • 结果是工作空间分析界面，而非面向客户的产品后端。
若需处理更底层的Dive操作，请使用
motherduck-create-dive
。

Dashboard Defaults

仪表盘默认配置

  • One story per dashboard.
  • One KPI row.
  • One primary trend chart.
  • Zero or one supporting chart.
  • Zero or one detail table.
  • Heavy shaping in SQL, not React.
  • 每个仪表盘对应一个分析逻辑。
  • 一个KPI行。
  • 一个主趋势图表。
  • 0或1个辅助图表。
  • 0或1个详情表格。
  • 主要通过SQL进行数据塑形，而非React。

Workflow

工作流程

  1. Confirm whether live MotherDuck discovery is available.
  2. Explore the real schema and metrics first.
  3. Pick the dashboard story.
  4. Write one query per section.
  5. Compose the dashboard in a Dive.
  6. Save only after preview iteration is approved.
When this skill produces a native DuckDB (
md:
) connection, watermark it with 
custom_user_agent=agent-skills/2.2.0(harness-<harness>;llm-<llm>)
. If metadata is missing, fall back to 
harness-unknown
and 
llm-unknown
.
  1. 确认是否可进行实时MotherDuck数据探索。
  2. 先探索实际的数据库模式和指标。
  3. 确定仪表盘的分析逻辑。
  4. 为每个板块编写对应的查询语句。
  5. 在Dive中组合仪表盘。
  6. 仅在预览迭代获得批准后再保存。
当本技能生成原生DuckDB（
md:
）连接时，需添加水印
custom_user_agent=agent-skills/2.2.0(harness-<harness>;llm-<llm>)
。若元数据缺失，则 fallback 为
harness-unknown
和
llm-unknown
。

Output

输出内容

The output of this skill should be:
  • 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": []
}
本技能的输出应包含：
  • 仪表盘分析逻辑
  • 板块列表
  • 各板块经验证的SQL语句
  • Dive实现方案
  • 保存/更新路径
若调用方明确要求结构化JSON，则仅返回原始JSON，无需添加Markdown围栏或前后说明文字。 此要求主要用于自动化测试、回归检查或需要稳定机器可读格式的下游工具。面向普通用户使用本技能时，默认使用 prose 格式，除非明确要求JSON。
当要求返回JSON时，请使用以下顶层结构：
json
{
  "summary": {},
  "assumptions": [],
  "implementation_plan": [],
  "validation_plan": [],
  "risks": []
}

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
  • references/DASHBOARD_IMPLEMENTATION_GUIDE.md
    —— 保留了原属于本技能的详细工作流程和布局指南
  • references/DASHBOARD_PATTERNS.md
    —— 示例仪表盘组合和可复用板块

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
Run the same artifact against a temporary MotherDuck database:
bash
MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py
Validate the TypeScript companion artifact:
bash
uv run scripts/test_typescript_artifacts.py
  • artifacts/dashboard_story_example.py
    —— 基于MotherDuck的Python示例，可生成单个仪表盘分析逻辑对应的KPI、趋势、细分和详情输出
  • artifacts/dashboard_story_example.ts
    —— TypeScript配套工件，具有相同的仪表盘输出约定
运行方式：
bash
uv run --with duckdb python skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py
在临时MotherDuck数据库上运行同一工件：
bash
MOTHERDUCK_ARTIFACT_USE_MOTHERDUCK=1 \
uv run --with duckdb python skills/motherduck-build-dashboard/artifacts/dashboard_story_example.py
验证TypeScript配套工件：
bash
uv run scripts/test_typescript_artifacts.py

Related Skills

相关技能

  • 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-duckdb-sql
    -- resolve syntax and function questions
  • motherduck-explore
    —— 在确定仪表盘板块前检查实际数据库
  • motherduck-query
    —— 验证每个仪表盘查询语句
  • motherduck-create-dive
    —— 使用useSQLQuery、主题设置、预览/保存、加载和可视化操作
  • motherduck-duckdb-sql
    —— 解决语法和函数相关问题