dbt-projects_skill

Overview

This skill codifies dbt project conventions, tests, macros, and CI patterns so teams can scaffold and maintain consistent analytics engineering repositories. It documents YAML structures for models and sources, reusable macros (like cents_to_dollars and generate_schema_name), testing patterns (data, expression, and unit tests), and branch/CI expectations. Use it to align new models, seeds, and deployments with established best practices and to avoid common gotchas.

How this skill works

The skill inspects dbt YAML model files, source definition files, macro usage, and CI workflow rules to verify conventions and suggest actions. It highlights where to place staging, intermediate, and mart models, enforces test patterns and seed handling, and explains schema routing via the generate_schema_name macro. It also summarizes package dependencies and the expected dbt Cloud-centric CI flow.

When to use it

• Onboarding a new data engineer to a dbt repository to learn project conventions and file locations
• Adding a new model, source, or seed and needing explicit checklist steps (staging → intermediate → mart)
• Writing model YAML for documentation, column tests, semantic models, or metrics
• Configuring CI/CD or preparing a PR to run dbt Cloud jobs across Snowflake, BigQuery, or Postgres
• Debugging failing tests or schema-routing issues caused by environment differences

Best practices

• Place source definitions in models/staging/__sources.yml and add loaded_at_field when available
• Run dbt deps before dbt build on fresh clones and include jaffle-data in seed-paths only when seeding
• Keep staging models simple (rename/type-cast only) and reference source() only in staging
• Name intermediate models with verb-style names and restrict them to upstream staging/intermediate models
• Materialize marts as tables by default and include explicit descriptions, column tests, and optional metrics

Example use cases

• Create a new stg_customers model: add stg SQL, source entry, and stg_customers.yml with tests
• Write a model-level expression test validating business math with dbt_utils.expression_is_true
• Add a cents_to_dollars macro call to display monetary values consistently across warehouses
• Implement a unit test that mocks inputs for a complex transform to verify boolean logic
• Troubleshoot schema naming differences by reviewing generate_schema_name behavior for prod vs non-prod