Skip to main content
skill CX Codex

dbt-expert — Claude Code skill: what it does, how to install

dbt-expert — a dbt skill for building models, tests, documentation, macros, and Jinja templates. Use it for analytics engineering and SQL transformation work.

Apache-2.0 180 installs ★ 45 updated 2026-10-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add personamanagmentlayer/pcl --skill dbt-expert -a claude-code
Open on GitHub

What dbt-expert does

dbt-expert guides dbt project design across staging, intermediate, and mart layers. It covers model materializations, source and staging models, intermediate and mart models, incremental loading, macros, and Jinja templates. It also recommends connecting models with ref instead of direct table references.

The skill addresses primary and foreign key checks, unique and not_null tests, custom business-logic tests, source freshness, and model documentation with column descriptions. Its declared tools can read, write, and edit files, search project contents, and run shell commands. The setup requires dbt-core version 1.7.0 or later.

Detailed guidance for project structure, sources, incremental models, tests, macros, snapshots, and documentation is available in references/CORE_CONCEPTS.md when needed. The skill also flags patterns such as oversized CTE chains, hardcoded values, direct table references, and models without tests.

What it helps with

  • organize a dbt project into staging, intermediate, and mart layers
  • set up an incremental model for a large fact table
  • add primary-key and foreign-key tests
  • document dbt models and their columns
  • replace direct table references with ref calls

Example prompts for the agent

  • Organize this dbt project into staging, intermediate, and mart layers and suggest the model structure.
  • Review the models for primary-key, foreign-key, uniqueness, and not_null tests.
  • Set up an incremental event model and move repeated logic into a Jinja macro.

How to install dbt-expert

1Skills CLI (Vercel)

npx skills add personamanagmentlayer/pcl --skill dbt-expert -a claude-code

2Manually: put the files in place

~/.claude/skills/dbt-expert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/dbt-expert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about dbt-expert

How do I install dbt-expert in Claude Code?

Run npx skills add personamanagmentlayer/pcl --skill dbt-expert -a claude-code, then check ~/.claude/skills/dbt-expert/SKILL.md.

What does the dbt-expert skill do?

It supports dbt models, sources, tests, documentation, incremental models, macros, and Jinja. It also guides model structure and points out direct table references and untested models.

Which dbt version does dbt-expert require?

The skill requires dbt-core version 1.7.0 or later.

Source text

SKILL.md · Apache-2.0
---
name: dbt-expert
version: 1.1.0
description: >-
  Expert-level dbt (data build tool), models, tests, documentation, incremental models,
  macros, and Jinja templating. Use when the user mentions analytics engineering, SQL, data
  transformation, Jinja, or testing, or when the task involves Project Structure and
  Configuration, Sources and Staging Models, Intermediate and Mart Models, or Incremental
  Models.
category: data
author: PCL Team
license: Apache-2.0
tags:
  - dbt
  - analytics-engineering
  - sql
  - data-transformation
  - jinja
  - testing
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
requirements:
  dbt-core: '>=1.7.0'
---

# dbt Expert

You are an expert in dbt (data build tool) with deep knowledge of data modeling, testing, documentation, incremental models, macros, Jinja templating, and analytics engineering best practices. You design maintainable, tested, and documented data transformation pipelines.

## Best Practices

### 1. Project Organization

- Follow medallion architecture: staging -> intermediate -> marts
- Use clear naming conventions (stg*, int*, fct*, dim*)
- Keep models focused and single-purpose
- Document all models and columns
- Use consistent column naming across models

### 2. Model Configuration

- Use appropriate materializations (view, table, incremental, ephemeral)
- Implement incremental models for large fact tables
- Add tests to all primary keys and foreign keys
- Use schemas to organize models by business domain
- Set appropriate freshness checks on sources

### 3. Performance

- Materialize large intermediate models as tables
- Use ephemeral for simple transformations
- Implement incremental loading for event data
- Create appropriate indexes in post-hooks
- Monitor model run times

### 4. Testing

- Test uniqueness and not_null on all primary keys
- Test relationships between fact and dimension tables
- Add custom tests for business logic
- Test data quality expectations
- Run tests in CI/CD pipeline

### 5. Documentation

- Document model purpose and grain
- Add column descriptions
- Include examples and usage notes
- Generate and publish documentation
- Keep documentation up to date

## Anti-Patterns

### 1. Complex CTEs

```sql
-- Bad: Many nested CTEs
with cte1 as (...), cte2 as (...), cte3 as (...)
-- 20 more CTEs
select * from cte23

-- Good: Break into intermediate models
select * from {{ ref('int_cleaned_data') }}
```

### 2. Not Using refs

```sql
-- Bad: Direct table reference
select * from analytics.staging.stg_orders

-- Good: Use ref
select * from {{ ref('stg_orders') }}
```

### 3. No Tests

```sql
-- Bad: No tests
-- Good: Always test PKs and FKs
columns:
  - name: id
    tests: [unique, not_null]
```

### 4. Hardcoded Values

```sql
-- Bad: Hardcoded date
where created_at >= '2024-01-01'

-- Good: Use variables
where created_at >= '{{ var("start_date") }}'
```

## Reference Documentation

Detailed material lives alongside this skill and is read on demand:

- [Core Expertise](references/CORE_CONCEPTS.md) — Project Structure and Configuration, Sources and Staging Models, Intermediate and Mart Models, Incremental Models, Tests, Macros, Snapshots (SCD Type 2), Documentation

## Resources

- [dbt Documentation](https://docs.getdbt.com/)
- [dbt Best Practices](https://docs.getdbt.com/guides/best-practices)
- [dbt Discourse Community](https://discourse.getdbt.com/)
- [dbt Package Hub](https://hub.getdbt.com/)
- [dbt Learn](https://learn.getdbt.com/)
- [Analytics Engineering Guide](https://www.getdbt.com/analytics-engineering/)
- [dbt Style Guide](https://github.com/dbt-labs/corp/blob/main/dbt_style_guide.md)

© PCL Team · Apache-2.0 · personamanagmentlayer/pcl

Similar skills

All skills for Data and databases →
dbt-data-transformation manutej dbt-data-transformation — a dbt skill for analytics engineering: models, tests, docs, incremental builds, macros and packages. Useful when your warehouse SQL needs structure. CX Codex +1 443installs running-dbt-commands dbt-labs running-dbt-commands — a skill for Claude Code, Codex, Cursor and other platforms that formats and executes dbt CLI commands. Picks the right dbt executable and structures parameters for build, run, test, show. CX Codex +1 1,100installs using-dbt-state dbt-labs using-dbt-state — a Claude Code skill that teaches the agent how dbt State works: a server-backed reuse mechanism that skips or clones nodes instead of rebuilding them. Covers setup, config, debugging and billing. CX Codex +1 591installs analytics-engineer borghei analytics-engineer — a skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode that builds dbt transformations and dimensional schemas. Triggered when you need SQL models, tests, incremental fact tables or metrics. CX Codex +1 207installs dbt Analytics Project taste f dbt Analytics Project taste — a prompt for ChatGPT sets conventions for dbt models, tests, documentation, and CI. Use it while shaping an analytics project or revising its model structure. GP ChatGPT ★ 178,201repo stars dbt-transformation-patterns Seth Hobson dbt-transformation-patterns — a skill for Claude, Claude and Cursor that tells the agent how to layer dbt models, write data tests and set up incremental marts. CX Codex +1 11,000installs

From the same set104

The whole set →
media-expert media-expert — a skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode that gives the agent deep knowledge of media production, streaming, and broadcasting. CX Codex +1 182installs microservices-expert microservices-expert — a skill for microservices architecture, service communication, and distributed workflows. Use it when a task involves service mesh, failure handling, or system design. CX Codex +1 181installs api-design-expert api-design-expert walks your agent through HTTP API design: REST resources, GraphQL against gRPC, versioning schemes, one error shape. Handy before the first endpoint gets written. CX Codex +1 180installs azure-expert azure-expert is a Claude Code skill for Microsoft Azure architecture, Azure Functions code, Cosmos DB queries, and Azure CLI commands. CX Codex +1 180installs rust-expert rust-expert — a skill that turns a coding agent into a Rust reviewer: borrowing rules, lifetimes, async tasks, error types. Useful when the borrow checker blocks a refactor. CX Codex +1 179installs design-expert design-expert equips your agent with system design patterns, distributed architecture principles, and Python reference code. CX Codex +1 178installs airflow-expert airflow-expert guides Apache Airflow DAG design, task dependencies, operators, sensors, and scheduling. Use it when building or reviewing data workflows. CX Codex +1 174installs cloudflare-expert cloudflare-expert is a Claude Code skill for Cloudflare Workers, CDN, edge computing, and security services. It activates for tasks involving WAF, Cloudflare products, or developer tools. CX Codex +1 174installs

Project sponsors

Companies that keep this analytics open