semantic-model-builder
When to use
- A stakeholder asks "how is [metric] calculated?" and no canonical definition exists
- You're setting up dbt Semantic Layer and need YAML metric/dimension/entity definitions
- Multiple teams are using different SQL queries for the same metric — you need to codify the one true definition
- You're building a data catalog entry for a core model and need structured metadata
Process
- Identify the object type — decide whether you're documenting a metric, a dimension, or an entity. Use the frameworks in
references/metric_definition_framework.mdfor metrics andreferences/dimension_hierarchy_patterns.mdfor dimensions. - Gather the definition inputs — collect: calculation logic (SQL or formula), business context, data source(s), grain, edge cases, and known gotchas. Ask the data owner if anything is unclear.
- Generate the YAML template — run
scripts/metric_template_generator.pyto scaffold the initial YAML structure for the object type. Fill in the generated template. - Validate the YAML — run
scripts/model_yaml_validator.pyto check required fields, type constraints, and reference integrity (referenced dimensions exist in the same file). - Add dbt context — if this will be deployed to dbt Semantic Layer, consult
references/dbt_semantic_layer_guide.mdfor the exact field names and constraints for your dbt version. - Save final definitions — save metrics to
assets/metric_definition.yaml, dimensions toassets/dimension_definition.yaml, entities toassets/entity_definition.yaml.
Inputs the skill needs
- Required: the metric name or model name to document
- Required: calculation logic — SQL snippet, formula, or plain-English steps
- Required: business context — who uses it, what decision it informs, what a "good" value looks like
- Optional: data source table(s) and column names
- Optional: target semantic layer framework (dbt Semantic Layer, Cube.js, LookML, etc.)
- Optional: existing YAML to validate
Output
assets/metric_definition.yaml— filled metric YAML definition(s)assets/dimension_definition.yaml— filled dimension YAML definition(s)assets/entity_definition.yaml— filled entity YAML definition(s)- Validation report from
scripts/model_yaml_validator.py(inline output)
More from nimrodfisher/data-analytics-skills
funnel-analysis
Conversion funnel analysis with drop-off investigation. Use when analyzing multi-step processes, identifying conversion bottlenecks, comparing segments through a funnel, or optimizing user journeys.
37metric-reconciliation
Cross-source metric validation and discrepancy investigation. Use when metrics from different sources don't match, investigating data quality issues between systems, or validating data migration accuracy.
31insight-synthesis
Transform data findings into compelling insights. Use when converting analysis results into actionable insights, connecting findings to business impact, or preparing insights for stakeholder communication.
31dashboard-specification
Design specifications for effective dashboards. Use when planning new dashboards, improving existing ones, or documenting dashboard requirements before development starts.
30data-quality-audit
Comprehensive data quality assessment against business rules, schema constraints, and freshness expectations. Activate when validating data pipeline outputs before production use, auditing a dataset against defined business rules, or producing a quality scorecard for a data asset.
30root-cause-investigation
Systematic investigation of metric changes and anomalies. Use when a metric unexpectedly changes, investigating business metric drops, explaining performance variations, or drilling into aggregated metric drivers.
30