gabrielmoreira Metric Semantic Layer Skill
"Active users" means three different things in three dashboards — that's the problem a semantic layer solves: define each metric once, precisely, and every tool reads the same definition. This skill writes that definition — the exact formula, base measure, allowed dimensions, default filters, and the edge cases that usually cause drift — in a tool-ready form (dbt MetricFlow / Cube / LookML).
Required Inputs
Ask for these only if they aren't already provided:
- The metric — its name and the business question it answers.
- The base data — the model/table and the column(s) it's computed from.
- The aggregation — sum, count, count distinct, average, ratio.
- Dimensions & filters — how it can be sliced, and any default filters (exclude test accounts, internal users, refunds).
- Tool — dbt MetricFlow, Cube, LookML, or tool-agnostic.
Output Format
Metric: [metric_name]
1. Definition (plain English) — one sentence a non-analyst understands, and the precise version ("count of distinct user_ids with ≥1 qualifying event in the period, excluding internal/test accounts").
2. Formula — the exact calculation: base measure · aggregation · numerator/denominator (for ratios).
3. Grain & time — the time grain it's reported at, the date column it's anchored to, and how partial periods are handled.
4. Dimensions — the dimensions it can be sliced by (and any it must not be — non-additive metrics break when summed across the wrong dimension).
5. Default filters — what's always excluded (test/internal/refunds) so every consumer gets the same number.
6. Edge cases — null handling, late-arriving data, deduplication, currency/timezone, and additivity (can it be summed across days? across segments?). This section is where metric drift is prevented.
7. Tool-ready spec — the YAML/LookML for the chosen tool (MetricFlow metrics: / Cube measures: / LookML measure:), ready to commit.
Quality Checks
- Has both a plain-English and an exact definition
- States the base measure, aggregation, and (for ratios) numerator/denominator
- Default filters are explicit, so every tool returns the same number
- Additivity is addressed (which dimensions it can/can't be summed across)
- Edge cases (nulls, dedup, timezone, late data) are handled
- A tool-ready spec is provided, not just prose
Anti-Patterns
- Do not leave the definition fuzzy — "active users" without the exact rule is how three dashboards disagree
- Do not omit default filters — if one tool counts test accounts and another doesn't, the metric is broken
- Do not ignore additivity — summing a non-additive metric (like a distinct count) across days gives a wrong number
- Do not define metrics in BI tools instead of the semantic layer — that's how definitions fork
- Do not skip timezone/null/dedup edge cases — they cause the subtle, hard-to-find discrepancies
Based On
Semantic-layer / metrics-layer practice (dbt MetricFlow, Cube, LookML) — single-source metric definitions with explicit grain, filters, and additivity.