dbt Model Spec Skill

A dbt model is only trustworthy if its grain is unambiguous, its sources are declared, and it's tested. This skill specs a model the way a good analytics engineer would — naming the grain first, mapping lineage, defining each column, choosing the right materialization, and writing the dbt tests that keep it correct — so the model is reviewable before a line of SQL ships.

Required Inputs

Ask for these only if they aren't already provided:

• What the model represents and its grain (one row per ___ — the single most important decision).
• Layer — staging, intermediate, or mart (dimension/fact). Conventions differ per layer.
• Sources / upstream refs — the raw tables or models it builds on.
• The business logic — joins, filters, aggregations, and any business rules.

Output Format

dbt Model: [model_name]

1. Purpose & grain — what it is, and one row per [grain] stated explicitly. Layer (staging/intermediate/mart).

2. Lineage — source('…') / ref('…') upstreams → this model → likely downstream consumers.

3. Transformation logic — the joins, filters, aggregations, window functions, and business rules, in order. Flag fan-out risks (joins that break the grain).

4. Columns — a table: name · type · description · (key/measure/dimension). The schema contract.

5. Tests (dbt) — unique + notnull on the grain key, relationships for FKs, acceptedvalues for enums, and any custom/dbt_utils tests the logic needs. Tests are the model's guarantees — don't skip them.

6. Materialization — view / table / incremental / ephemeral, with the reasoning (incremental needs a uniquekey + an isincremental() filter).

7. Skeleton — a starting model.sql (CTE-structured: imports → logic → final select) and the schema.yml with tests, ready to fill in.

Quality Checks

• The grain is stated as "one row per ___" and the key is tested unique + not_null
• Sources/refs use source()/ref(), not hard-coded table names
• Every column has a type and description (the schema contract)
• Tests cover the grain key, FKs (relationships), and enum columns
• Materialization is justified; incremental models declare a uniquekey and isincremental() logic
• Fan-out joins that could break the grain are flagged

Anti-Patterns

• Do not leave the grain ambiguous — an untested, unclear grain is how duplicate rows and wrong metrics happen
• Do not hard-code upstream table names — use ref()/source() so lineage and environments work
• Do not ship a model with no tests — untested models silently rot; the grain key at minimum must be tested
• Do not default everything to a table — pick the materialization the use justifies (views for light, incremental for large append-only)
• Do not bury business logic without comments — the next analyst must understand the rules

Based On

dbt / analytics-engineering best practice — explicit grain, ref/source lineage, layered modelling (staging→intermediate→mart), schema tests.