# Working With Dbt Mesh

Use when changing a dbt model in a way that could break its consumers, renaming...

- Repository: https://github.com/dbt-labs/dbt-agent-skills (750 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-29
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add dbt-labs/dbt-agent-skills --skill working-with-dbt-mesh -g -a claude-code -y`
Codex: `npx skills add dbt-labs/dbt-agent-skills --skill working-with-dbt-mesh -g -a codex -y`
Cursor: `npx skills add dbt-labs/dbt-agent-skills --skill working-with-dbt-mesh -g -a cursor -y`
Gemini CLI: `npx skills add dbt-labs/dbt-agent-skills --skill working-with-dbt-mesh -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add dbt-labs/dbt-agent-skills`

## Description

Use when changing a dbt model in a way that could break its consumers, renaming, removing, or retyping a column, or changing a model that downstream models, exposures, dashboards, or BI tools depend on, to judge whether the change is breaking and who it affects. Also use when versioning a model (model versions, latest_version, latest_version_pointer, deprecation_date, migration windows), enforcing contracts, setting access or groups, or doing multi-project dbt Mesh work (cross-project refs via dependencies.yml, disambiguating similarly-named models, splitting a monolith). Covers single- and multi-project, and planning or advising as well as implementing.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Working with dbt Mesh

**Core principle:** In a mesh project, upstream data comes through `ref()`, not `source()`. Every cross-project reference requires the project name. When in doubt, read `dependencies.yml` first.

## When to Use

- Making a potentially breaking change to a model, renaming, removing, or retyping a column, **especially when other models, exposures, or BI tools depend on it.** Assess the blast radius *before* changing it, and reach for model versions rather than editing in place.
- Versioning a model (`versions:`, `latest_version`, `latest_version_pointer`, `deprecation_date`), this applies in a **single project**, not just multi-project setups
- Working in a dbt project that references models from other dbt projects
- Resolving ambiguity when multiple upstream projects have similarly-named models (e.g. multiple `stg_` models)
- Adding model contracts, access modifiers, or groups
- Setting up cross-project references with `dependencies.yml`
- Splitting a monolithic dbt project into multiple mesh projects

**Do NOT use for:**

- General model building or debugging (use the `using-dbt-for-analytics-engineering` skill)
- Unit testing models (use the `adding-dbt-unit-test` skill)
- Semantic layer work (use the `building-dbt-semantic-layer` skill)

## First: Orient Yourself in a Multi-Project Setup

Before writing or modifying any SQL in a project that uses dbt Mesh, follow these steps:

### 1. Read `dependencies.yml`

This file at the project root tells you which upstream projects exist:

```yaml
# dependencies.yml
projects:
  - name: core_platform
  - name: marketing_platform
```

If this file has a `projects:` key, you are in a multi-project mesh setup. Every model you reference from those upstream projects **must** use cross-project `ref()`.

### 2. Understand how upstream data gets into this project

In a mesh setup, upstream project models replace what would alternatively be sources:

The rest: https://github.com/dbt-labs/dbt-agent-skills/blob/HEAD/skills/dbt/skills/working-with-dbt-mesh/SKILL.md