/building-a-dashboard

name: building-a-dashboard
description: >
  Build a new dashboard, or update an existing one, from a set of insights — the same job the in-app
  assistant does with its upsert-dashboard tool, but over MCP. Use when a user asks to create a dashboard,
  put several metrics/charts together on one page, assemble a dashboard for a topic (product analytics,
  retention, revenue, activation, etc.), or add/remove/replace insights on a dashboard they already have.
  Covers deciding create vs update, reusing existing insights vs creating new ones, and using PostHog's
  vetted dashboard templates as reference for what a strong dashboard on a topic looks like.

Building a dashboard

A dashboard is a collection of insight tiles on one page. Your job is to figure out which insights belong on it, reuse what already exists, create what's missing, and lay them out sensibly — not to blindly generate charts.

When the dashboard needs explanatory text, keep user copy and agent context separate. Use the `writing-user-facing-copy` skill for text that people read. Use `agent_context` for information that an agent needs to maintain the dashboard.

PostHog's Data Catalog is the semantic layer. Store canonical metric definitions there. Never use `agent_context` as a substitute for a Data Catalog metric.

Create vs update

First work out whether you're creating a new dashboard or changing an existing one.

• Search existing dashboards with `dashboards-get-all` (its `search` param does fuzzy name/description matching). If the

user is clearly describing something that already exists, they probably want an update.

• Read a candidate with `dashboard-get` to see its current tiles before you change anything.
• If the request is ambiguous — "get my financial metrics together" could mean build new or add to an existing one —

ask a short clarifying question rather than guessing.

Use templates as reference

PostHog ships vetted dashboard templates for common topics, and orgs can share their own. Consult them before you build — they're a strong signal of which insights pair well on a topic.

1. `dashboard-templates-list` — browse templates (use `search` for a topic, `scope` to narrow to global / team / organization). This returns names, descriptions, and tags only. 2. `dashboard-templates-retrieve` — open the closest template to see its `tiles`: which insights it groups together and how each is queried.

Treat templates as **examples, not a spec**. Take inspiration from the insights and their groupings, but tailor every insight to the user's own events, properties, and intent. Don't copy a template verbatim, and don't force a template onto a request it doesn't fit — a good bespoke dashboard beats a mismatched template every time.

Select the insights

Prefer reusing existing insights over recreating them.

• Search with `insights-list` and read promising ones with `insight-get` to check they match the user's intent and

actually have data. Full-text search misses things named differently, so list broadly before concluding an insight doesn't exist.

• For anything missing, read `querying-posthog-data` before choosing its query method. After Data Catalog routing,

default to typed runners for each supported product-analytics tile: trends (including simple counts, unique users, sums, and breakdowns), funnels, retention, stickiness, paths, and lifecycle. Run the query to verify it, then save its native query node with `insight-create`. Use SQL-backed insights for explicit SQL requests or calculations the typed schemas cannot express, such as custom joins. SQL used to discover events or existing insights does not determine the query type of new tiles. Keep valid existing insights rather than rebuilding them.

• Follow `querying-posthog-data` for presenting verified query results: some harnesses show charts inline, while

others need a separate top-level `render-ui` call with the same query tool and input. Rendering support does not determine the saved insight's query type.

• Keep the set minimal — only the insights the request needs. A focused dashboard is more useful than an exhaustive one.

Use Data Catalog for reusable metrics

Use PostHog's Data Catalog as the source of truth for reusable business and telemetry metrics. Do this before you derive a metric from raw data or copy a definition from an existing dashboard:

1. Call `posthog:metric-list` and follow pagination until you have checked the complete catalog. 2. Call `posthog:metric-describe` for each possible match. Use only an `approved`, non-drifted exact match as a canonical definition. 3. Call `posthog:data-catalog-metric-run` to verify an approved match. Use its definition when you build or update the related dashboard insight. 4. If the dashboard introduces a reusable metric with no governed match, follow the `setting-up-data-catalog` skill and create a proposed metric with `posthog:data-catalog-metric-create`. Use `source_insight_short_id` when the definition comes from an insight. A proposed metric is not canonical until a human approves it.

Do not copy the metric definition into dashboard text or `agent_context`. Store the Data Catalog metric name in `agent_context` only when a future agent needs the reference. If the project has no Data Catalog, label the derived metric as noncanonical and do not claim that `agent_context` makes it governed.

Assemble the dashboard

• New dashboard: `dashboard-create` with a short (3–7 word) name and a concise description, then add the insight tiles.
• Existing dashboard: use `dashboard-update` to add insight tiles or change their layout. Tiles omitted from a PATCH

remain on the dashboard. To remove a tile, find its ID with `dashboard-get`, then use `dashboard-delete-tile`. To replace an insight tile, add the new insight and delete the old tile.

• Description on create and update: it is a short note for people who open the dashboard. Say what the dashboard shows