---
name: metric-semantic-layer
description: "Define a metric in a semantic layer so it means one thing everywhere. Use when asked to define a metric, build a semantic layer / metrics layer entry, stop 'revenue means three things' problems, or write a metric definition for dbt MetricFlow / Cube / LookML. Produces a metric definition — exact formula, the base measure & aggregation, dimensions, filters, grain, edge cases, and a tool-ready spec."
---

# 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.

## Example Trigger Phrases

- "Define a metric."
- "Build a semantic layer / metrics layer entry."
- "Stop 'revenue means three things' problems."
- "Write a metric definition for dbt MetricFlow / Cube / LookML."