building-dbt-semantic-layer_skill

Overview

This skill helps create and modify dbt Semantic Layer components: semantic models, entities, dimensions, metrics, and time spines. It covers choosing the correct YAML spec (latest vs legacy), common metric types (simple, derived, cumulative, ratio, conversion), and validation steps to ensure correctness. Use it to author consistent, validated semantic definitions that work with dbt Core and MetricFlow.

How this skill works

The skill inspects your project YAML and dbt models to detect whether a legacy top-level semantic_models key or a latest nested semantic_model block is present, then routes work to the appropriate authoring guide. It suggests entities and dimensions by analyzing model SQL and column types, builds metrics per spec syntax, and enforces validation steps (dbt parse + mf validate-configs or dbt sl validate). It also checks compatibility with dbt Core versions and offers upgrade guidance when necessary.

When to use it

• Adding or exposing a semantic model for an existing dbt model
• Defining new metrics (simple, derived, cumulative, ratio, conversion) or modifying existing ones
• Setting up or validating a time spine for time-based aggregations
• Migrating between legacy and latest semantic layer specs or confirming dbt Core compatibility
• Running full validation after YAML edits to prevent stale MetricFlow results

Best practices

• Detect which YAML spec is present first and stick to that spec for edits
• Always declare a default time dimension for any model with metrics
• Preserve unrelated YAML content when editing existing semantic components
• Run dbt parse (or dbtf parse for Fusion) before mf validate-configs to avoid stale validation results
• Avoid using window and grain_to_date together on the same cumulative metric

Example use cases

• Expose the customers model with an entity key, time dimension, and basic metrics like customer_count and revenue
• Create a derived metric (profit = revenue - cost) that references existing simple metrics
• Define a cumulative metric (MTD revenue) and configure a time spine for accurate period-to-date results
• Build a conversion metric to measure visit-to-purchase funnels with constant_properties to lock identity fields
• Help decide whether to author using latest spec (Core 1.12+) or stick with legacy spec for older dbt versions