Stats
Actions
Tags
From dbt
Guides creation and modification of dbt Semantic Layer YAML configs for semantic models, metrics, dimensions, entities, and time spines in latest or legacy specs.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dbt:building-dbt-semantic-layerThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill guides the creation and modification of dbt Semantic Layer components: semantic models, entities, dimensions, and metrics.
This skill guides the creation and modification of dbt Semantic Layer components: semantic models, entities, dimensions, and metrics.
There are two versions of the Semantic Layer YAML spec:
Look for existing semantic layer configuration in the project:
semantic_models: key in YAML files → legacy specsemantic_model: block nested under a model → latest specIf semantic layer already exists:
uvx dbt-autofix deprecations --semantic-layer or the migration guide. They don't have to upgrade; continuing with legacy is fine.If no semantic layer exists:
Once you know which spec to use, follow the corresponding guide's implementation workflow (Steps 1-4) for all YAML authoring. The guides are self-contained with full examples.
Users may ask questions related to building metrics with the semantic layer in a few different ways. Here are the common entry points to look out for:
When the user describes a metric or analysis need (e.g., "I need to track customer lifetime value by segment"):
When the user specifies a model to expose (e.g., "Add semantic layer to customers model"):
Both paths converge on the same implementation workflow.
User asks to build the semantic layer for a project or models that are not specified. ("Build the semantic layer for my project")
Both specs support these metric types. For YAML syntax, see the spec-specific guides.
Directly aggregate a single column expression. The most common metric type and the building block for all others.
metrics: on the model with type: simple, agg, and exprmetrics: referencing a measure via type_params.measureCombine multiple metrics using a mathematical expression. Use for calculations like profit (revenue - cost) or growth rates (period-over-period with offset_window).
Aggregate a metric over a running window or grain-to-date period. Requires a time spine. Use for running totals, trailing windows (e.g., 7-day rolling average), or period-to-date (MTD, YTD).
Note: window and grain_to_date cannot be used together on the same cumulative metric.
Create a ratio between two metrics (numerator / denominator). Use for conversion rates, percentages, and proportions. Both numerator and denominator can have optional filters.
Measure how often one event leads to another for a specific entity within a time window. Use for funnel analysis (e.g., visit-to-purchase conversion rate). Supports constant_properties to ensure the same dimension value across both events.
Filters can be added to simple metrics or metric inputs to advanced metrics. Use Jinja template syntax:
filter: |
{{ Entity('entity_name') }} = 'value'
filter: |
{{ Dimension('primary_entity__dimension_name') }} > 100
filter: |
{{ TimeDimension('time_dimension', 'granularity') }} > '2026-01-01'
filter: |
{{ Metric('metric_name', group_by=['entity_name']) }} > 100
Important: Filter expressions can only reference columns that are declared as dimensions or entities in the semantic model. Raw table columns that aren't defined as dimensions cannot be used in filters — even if they appear in a measure's expr.
This skill references dbt-autofix, a first-party tool maintained by dbt Labs for automating deprecation fixes and package updates.
After writing YAML, validate in two stages:
dbt parse (or dbtf parse for Fusion) to confirm YAML syntax and referencesdbt sl validate (dbt Cloud CLI or Fusion CLI when using the dbt platform)mf validate-configs (MetricFlow CLI)Important: mf validate-configs reads from the compiled manifest, not directly from YAML files. If you've edited YAML since the last parse, you must run dbt parse (or dbtf parse) again before mf validate-configs will see the changes.
Note: When using Fusion with MetricFlow locally (without the dbt platform), dbtf parse will show warning: dbt1005: Skipping semantic manifest validation due to: No dbt_cloud.yml config. This is expected — use mf validate-configs for semantic layer validation in this setup.
Do not consider work complete until both validations pass.
When modifying existing semantic layer config:
| Pitfall | Fix |
|---|---|
| Missing time dimension | Every semantic model with metrics/measures needs a default time dimension |
Using window and grain_to_date together | Cumulative metrics can only have one |
| Mixing spec syntax | Don't use type_params in latest spec or direct keys in legacy spec |
| Filtering on non-dimension columns | Filter expressions can only use declared dimensions/entities, not raw columns |
mf validate-configs shows stale results | Re-run dbt parse / dbtf parse first to regenerate the manifest |
MetricFlow install breaks dbt-semantic-interfaces | Install dbt-metricflow (not bare metricflow) to get compatible dependency versions |
npx claudepluginhub dbt-labs/dbt-agent-skills --plugin dbtAnswers business questions on analytics, metrics, KPIs by generating/executing SQL via dbt Semantic Layer, compiled SQL mods, or model analysis against data warehouse.
Provides patterns for building dbt models, adding tests, and designing data models including dimensional modeling, staging/intermediate/marts organization, naming conventions, and testing strategies.
Provides production-ready patterns for dbt including model organization, testing, documentation, and incremental processing for analytics engineering.