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
npx skills add personamanagmentlayer/pcl --skill dbt-expert -a claude-codeWhat 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
refcalls
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_nulltests. - 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-code2Manually: put the files in place
~/.claude/skills/dbt-expert/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/dbt-expert/
1Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill dbt-expert -a codex2Manually: put the files in place
.agents/skills/dbt-expert/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill dbt-expert -a cursor2Manually: put the files in place
.cursor/skills/dbt-expert/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install personamanagmentlayer/pcl stdlib/data/dbt-expert2Manually: put the files in place
.github/skills/dbt-expert/SKILL.md1Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill dbt-expert -a gemini-cli2Platform CLI
gemini skills install https://github.com/personamanagmentlayer/pcl --path stdlib/data/dbt-expertManually: put the files in place
.devin/skills/dbt-expert/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add personamanagmentlayer/pcl --skill dbt-expert -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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