mcpField
S
semantic-model-builder

semantic-model-builder

github.com/nimrodfisherData & databases504222 installsUpdated 5w ago
Repository

About semantic-model-builder

semantic-model-builder is a data skill for defining metrics, dimensions, and entities as structured YAML. It helps data teams standardize business definitions, validate metadata, and prepare definitions for semantic-layer use.

Key features

  1. 01Scaffold metric, dimension, and entity YAML
  2. 02Validate fields, types, and references
  3. 03Consult dbt Semantic Layer guidance
  4. 04Produce definitions and a validation report

Use cases

  1. 01Establishing a canonical definition for a metric
  2. 02Preparing YAML for dbt Semantic Layer
  3. 03Documenting metadata for a core data model
  4. 04Checking existing semantic-model YAML

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/nimrodfisher/data-analytics-skills --skill semantic-model-builder

After installing, type/semantic-model-builderin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/
dimension_definition.yaml
entity_definition.yaml
metric_definition.yaml
references/
dbt_semantic_layer_guide.md
dimension_hierarchy_patterns.md
metric_definition_framework.md
scripts/
metric_template_generator.py
model_yaml_validator.py

Details

From the project README

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)

Comments

Markdown supported