# dbt Agent Skills: teaching coding agents to write dbt models

> dbt-labs/dbt-agent-skills is a curated set of Agent Skills that load automatically when a prompt touches dbt work. It is aimed at teams already running dbt who want their coding agent to follow dbt conventions instead of guessing.

**dbt-labs/dbt-agent-skills** — A curated collection of Agent Skills for working with dbt, to help AI agents understand and execute dbt workflows more effectively.

- Repository: https://github.com/dbt-labs/dbt-agent-skills
- Stars: 718 · Forks: 62
- Language: Python
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/dbt-labs-dbt-agent-skills

## The problem: an agent that writes SQL but not dbt

A general-purpose coding agent can write a SELECT statement. What it usually cannot do is write one that matches how a dbt project is organised: which models are staging, which are marts, where sources are declared, how tests are named, whether contracts are enforced. Left alone, the agent invents a layout, and the reviewer spends the session correcting structure rather than logic.

dbt Agent Skills targets that gap. The repository describes itself as "a curated collection of Agent Skills for working with dbt" whose purpose is to help AI agents "understand and execute dbt workflows more effectively." The audience is narrow on purpose: teams that already run dbt, have a dbt_project.yml, and are comfortable with models, tests and sources. The README states most skills assume exactly that. Two exceptions are named, fetching-dbt-docs and configuring-dbt-mcp-server, which the README says can be used without an existing project.

## Skills load on their own, they are not slash commands

The mechanism is the part worth understanding before installing anything. The README is explicit that these skills are "not slash commands or user-invoked actions." Once installed, the agent loads the relevant skill when your prompt matches its use case. You describe the task in natural language and the agent decides which skill applies. The README links to Claude's documentation on skill invocation control for the details of who can invoke a skill.

That design has a consequence. There is no command you type to force a skill, so behaviour depends on the agent recognising the match. The repository ships an evals/ directory, and pyproject.toml points to evals/README.md as an A/B testing tool for comparing skill variations. That tells you the project treats skill wording as something to measure rather than assume.

The skills themselves are grouped. Ten sit under the dbt group: using-dbt-for-analytics-engineering, adding-dbt-unit-test, maintaining-dbt-documentation, building-dbt-semantic-layer, answering-natural-language-questions-with-dbt, working-with-dbt-mesh, troubleshooting-dbt-job-errors, configuring-dbt-mcp-server, fetching-dbt-docs and running-dbt-commands. Three more sit under dbt-migration: migrating-dbt-core-to-v2, migrating-dbt-project-across-platforms and upgrading-dbt-core. The README flags the migration set as "typically used once during a migration project rather than in every agent session," which is why it installs as a separate plugin.

## Installing the dbt skills in Claude Code

Claude Code gets a marketplace route. The README gives three commands: add the marketplace, install the dbt skills, and optionally install the migration skills.

```bash
# Add the marketplace
/plugin marketplace add dbt-labs/dbt-agent-skills

# Install the dbt skills (analytics engineering, semantic layer, testing, etc.)
/plugin install dbt@dbt-agent-marketplace

# Install the migration skills (typically a one-off, not needed for every session)
/plugin install dbt-migration@dbt-agent-marketplace
```

After the second command the agent should have the ten dbt skills available. The third is separate because migration work is not a per-session concern. There is no configuration file to edit and no environment variable to set in the README's instructions; the plugin install is the whole setup.

For a first real use, the README's own framing is the test: describe what you need in natural language and see whether the agent picks up the right skill. A prompt about adding a unit test should pull in adding-dbt-unit-test; a prompt about a failing platform job should pull in troubleshooting-dbt-job-errors. If the agent answers as a generic SQL assistant instead, the skill did not load, and that is the signal to check the installation rather than the prompt.

## Vercel Skills CLI and Tessl for other agents

Claude Code is not the only client. The README documents the Vercel Skills CLI, which it says supports 30+ AI agents including Cursor, Cline and GitHub Copilot, and Tessl, described as a package manager for agent skills.

The Vercel CLI can list before installing, which is the safer first step:

```bash
# Preview available skills
npx skills add dbt-labs/dbt-agent-skills --list

# Install only the dbt skills (analytics engineering, semantic layer, etc.)
npx skills add dbt-labs/dbt-agent-skills/skills/dbt

# Install a specific skill
npx skills add dbt-labs/dbt-agent-skills --skill using-dbt-for-analytics-engineering
```

The path-based install is the one to notice. Installing the whole repository brings in the migration skills too; pointing at skills/dbt keeps the migration set out of every session, which matches the README's own advice that migration skills are a one-off. The CLI also has --global for storing skills in ~/.<agent>/skills/ so they are available across projects, plus npx skills check and npx skills update for maintenance.

Tessl takes a similar shape with a different command surface:

```bash
tessl install dbt-labs/dbt-agent-skills
tessl install dbt-labs/dbt-agent-skills --skill using-dbt-for-analytics-engineering
tessl install github:dbt-labs/dbt-agent-skills
```

The README also links a Tessl registry tile. Whichever route you take, the repository states that all skills follow the Agent Skills specification, so portability across products is the design intent rather than a per-client fork.

## What the packaging tells you about runtime cost

pyproject.toml is worth reading because it exposes a deliberate scoping decision. The package data for skills includes markdown and shell files, and then one narrow exception: dbt-migration/skills/upgrading-dbt-core/references/*.json. The comment in the file explains that these precompiled issue bundles are "the only non-doc resource an agent loads at runtime," and that each bundle is self-contained, carrying its own action, automation_type, and detection and fixing context. The kb/ YAML corpus they are generated from is therefore not shipped. The comment also notes that a blanket **/*.json would pull in unrelated files from every other skill.

That is a real constraint, not packaging trivia. The resources an agent loads at runtime are the ones that consume context, and the project is spending effort keeping that set small. The same file pins Python at >=3.11 and carries a single runtime dependency, pyyaml>=6.0, with a comment that frontmatter validation in scripts/validate_repo.py parses real YAML rather than approximating it. The build backend is setuptools>=82.0.1. For a repository whose payload is mostly markdown, the tooling exists to validate structure, not to run anything at inference time.

## Where it will not help you

The first limitation is the obvious one. If there is no dbt project, most of the collection is inert. The README names only two skills that work without one, so a team evaluating this as a general SQL assistant aid will find most of the payload unreachable.

The second is client support. The repository states the skills work with AI agents that support the Agent Skills format. That is a compatibility requirement, not a feature. An agent product outside that set has no documented path here, and the README does not describe a fallback.

The third is subtler. Because skills load on prompt match rather than explicit invocation, a skill that does not fire produces no error. You get a plausible answer built on the agent's own assumptions, and nothing in the transcript says a skill was skipped. The repository's eval tooling exists precisely because that failure is hard to see by reading output.

A fourth point is scope honesty: the README does not document rollback or an uninstall procedure for any of the three install routes. Removal is left to whatever the client's plugin or skills mechanism provides, which the README does not describe.

## Alternatives: dbt MCP server and hand-written instructions

The nearest alternative inside the same ecosystem is the dbt MCP server. It is not a competitor in the same slot, and the difference matters. A skill is a folder of instructions, scripts and resources that the agent reads to decide how to act; the README says so directly. An MCP server exposes tools the agent calls. One shapes reasoning, the other supplies capability. The repository acknowledges the split by shipping configuring-dbt-mcp-server as a skill whose job is to set up the MCP server for Claude, Cursor or VS Code. If your problem is that the agent cannot reach the dbt platform at all, the MCP server is the missing piece; if the problem is that it reaches the platform and then writes models that ignore your conventions, that is what the skills address.

The other alternative is the one most teams already have: a CLAUDE.md or equivalent instructions file in the repository. The trade-off is granularity. A single instructions file is loaded wholesale and applies to every prompt, so it grows until it competes with the task for context. Skills are split by use case and loaded on match, which is the reason the README can keep the migration set in a separate plugin. The cost of that split is the silent-miss problem described above: a monolithic instructions file always applies, a skill only applies when it fires.

## Licence, maintenance and what to verify

The repository is Apache-2.0, and the README's licence section only points at the LICENSE file rather than restating terms. Apache-2.0 is a permissive licence with an explicit patent grant and requires attribution and notice retention when you redistribute. If you fork the skills and ship them inside a product, read LICENSE and CONTRIBUTING.md rather than treating this paragraph as guidance; nothing here is legal advice.

On maintenance: the repository is not archived, and the last push was on 2026-09-10. There are no retrieved releases, so versioning is not visible from the outside. The presence of .changie.yaml and a CHANGELOG.md suggests changes are tracked, and RELEASING.md implies a documented release process, but the repository does not show a version you can pin.

Upgrade cost is low by construction. The payload is markdown and a handful of JSON reference bundles, and the Vercel CLI offers npx skills check and npx skills update. The real cost is not the upgrade, it is re-validating that skills still fire after the agent product changes how it matches prompts. The evals/ directory and its A/B tooling are the place to look for how the project measures that.

## Conclusion

Adopt dbt Agent Skills if your team already runs dbt and your agent keeps producing models that ignore your project's conventions; the ten dbt skills cover analytics engineering, the semantic layer, Mesh governance and job troubleshooting, and the three migration skills are meant to be installed once rather than kept in every session. Skip it if you have no dbt project, since the README states most skills assume dbt is installed and a dbt_project.yml exists, or if your agent product does not implement the Agent Skills format. Before rolling it out, check that your client can load skills from the marketplace or the Vercel Skills CLI, and read evals/README.md to see how the repository's own A/B comparison tool judges a skill variation against the baseline.

## FAQ

### What are Agent Skills in dbt Agent Skills?

The README describes Agent Skills as folders of instructions, scripts and resources that agents can discover and use to do things more accurately and efficiently. In this repository they are grouped into a dbt set of ten skills and a dbt-migration set of three.

### Are dbt Agent Skills slash commands?

No. The README states they are not slash commands or user-invoked actions, and that once installed the agent automatically loads the relevant skill when your prompt matches its use case.

### How do I install dbt Agent Skills in Claude Code?

Add the marketplace with /plugin marketplace add dbt-labs/dbt-agent-skills, then run /plugin install dbt@dbt-agent-marketplace. The migration skills install separately with /plugin install dbt-migration@dbt-agent-marketplace.

### Can I use dbt Agent Skills with Cursor or GitHub Copilot?

The README documents the Vercel Skills CLI as supporting 30+ AI agents including Cursor, Cline and GitHub Copilot. It also states the skills work with agents that support the Agent Skills format.

### Do dbt Agent Skills need an existing dbt project?

The README says most skills assume dbt is installed, a dbt_project.yml exists, and you know basic dbt concepts. It names fetching-dbt-docs and configuring-dbt-mcp-server as usable without an existing project.

## Sources

- [dbt-labs/dbt-agent-skills on GitHub](https://github.com/dbt-labs/dbt-agent-skills)
- [Issues](https://github.com/dbt-labs/dbt-agent-skills/issues)
- [License: Apache-2.0](https://github.com/dbt-labs/dbt-agent-skills/blob/main/LICENSE)
- [README](https://github.com/dbt-labs/dbt-agent-skills/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/dbt-labs-dbt-agent-skills