semantic-model-builder

Installation
SKILL.md

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

  1. Identify the object type — decide whether you're documenting a metric, a dimension, or an entity. Use the frameworks in references/metric_definition_framework.md for metrics and references/dimension_hierarchy_patterns.md for dimensions.
  2. 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.
  3. Generate the YAML template — run scripts/metric_template_generator.py to scaffold the initial YAML structure for the object type. Fill in the generated template.
  4. Validate the YAML — run scripts/model_yaml_validator.py to check required fields, type constraints, and reference integrity (referenced dimensions exist in the same file).
  5. Add dbt context — if this will be deployed to dbt Semantic Layer, consult references/dbt_semantic_layer_guide.md for the exact field names and constraints for your dbt version.
  6. Save final definitions — save metrics to assets/metric_definition.yaml, dimensions to assets/dimension_definition.yaml, entities to assets/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)
Related skills
Installs
25
GitHub Stars
54
First Seen
Mar 17, 2026