Replies: 17 comments 12 replies
Example skillFor reference, here is a simple definition for ---
name: list-fqn
description: List fully qualified database relation names (`database.schema.identifier`) for selected dbt nodes.
---
Run `dbt ls --select "<selector>" --output json --output-keys "name database schema alias"`. For each JSON row, print one line per node: `name` plus `<database>.<schema>.<alias>`.It can sit within a folder named $ tree .
.
└── skills
└── list_fqn
└── SKILL.mdIf you use Claude Code, and the skills folder is located at 
|
|
💡 💡 💡 Brainstorming optionsBelow is a completely non-exhaustive brainstorm of various options. Please share any other ideas you have! Skills locationThere’s a discussion here regarding standardizing where skills should live by default, regardless of vendor. In the meantime, we’d still need to make a decision on the standard installation location dbt would default to. Option 1: Top-level $ tree .
.
├── dbt_project.yml
└── skills
├── building-dbt-semantic-layer
│ ├── references
│ │ └── time-spine.md
│ └── SKILL.md
└── some-other-skill
└── SKILL.mdPotentially able to be configured as # dbt_project.yml
skills-paths: [".claude/skills", ".cursor/skills", ...] # just top-level `skills/` by defaultOption 2: Vendor-conventional folders inside the project ( $ tree .
.
├── .claude
│ └── skills
│ ├── building-dbt-semantic-layer
│ │ ├── references
│ │ │ └── time-spine.md
│ │ └── SKILL.md
│ └── some-other-skill
│ └── SKILL.md
└── dbt_project.yml Expressing dependenciesOption 1: New # dependencies.yml
skills:
# GitHub URL (which is not a dbt project)
- git: "https://github.com/dbt-labs/dbt-agent-skills.git"
revision: 0.9.2 # git tag, branch name, or SHA (40-character hash)Option 2: Auto-detect skills inside existing package entries in ConfigurationOption 1: No ability to configure skills within dbt. Option 2: Configure skills under a # dbt_project.yml
skills:
<resource-path>:
+enabled: true | false
+meta: {<dictionary>}
+tags: <string> | [<string>]
+scope: project | global
+agents: <string> | [<string>]
+paths: <string> | [<string>]# _properties.yml
skills:
- name: skill_name
description: <string>
config:
+enabled: true | false
+meta: {<dictionary>}
+tags: <string> | [<string>]Installable contentSkills are standardized across vendors. But some vendors bundle other components together with skills into a “plugin”. For example, Claude plugins also includes custom agents, hooks, MCP servers, and LSP servers. Here’s some options: Option 1: Only install skills (and nothing else) Option 2: Install skills and also the other items (like custom agents, hooks, MCP servers, and LSP servers, etc) Installation locationThere’s not a standardized location where all vendors look for agent skills. In fact, it’s just the opposite — every vendor has a specific location where they look for skills that is separate from other vendors. So dbt would need to know which vendor(s) to install each skill for (and which to not). It would also need to know the scope of the installation (global, user, project, etc). Here’s some options: Option 1: Only install for a single vendor product (i.e. just Copilot or Codex, etc) Option 2: Install for several of the biggest vendor products (Claude, Cursor, Copilot, and Codex) Option 3: Install for every vendor under the sun (Everything! Everywhere! All at once!) Installation behaviorOption 1: Install automatically on Option 2: New dbt flag(s) (like dbt deps --agents claude codexOption 3: New subcommand (like Option 4: No installation by dbt - use something like Vercel skills CLI instead (technically an option but this discussion mainly pre-supposed installation by dbt somehow) Jinja templatingPrefect's Colin enables templating for skills. I’m guessing that we would be adverse to allowing Jinja within skills, but is there any potential value or use-cases we would be cutting off by not allowing it? Option 1: dbt does no rendering of Jinja templates found within Option 2: dbt looks for Jinja within Template: ---
name: deployment-process
description: How to deploy code to staging and production
---
# Deployment
{{ some_dbt_macro('acme/platform', 'docs/DEPLOY.md') }}Output: ---
name: deployment-process
description: How to deploy code to staging and production
---
# Deployment
All changes ship through CI. Push to main, wait for checks, then promote:
1. Open a PR against `main`
2. CI runs tests, linting, and builds a preview
3. Get approval from a code owner |
|
My simplified takes:
To me feels important that when one installs a Skill that is then run by an LLM there is no "active" code that goes to the LLM, while it's fine to have "plugins" that deliver capabilities like templates and common queries, that I now need to place in or treat like Analyses to be runnable, but not being picked up by |
|
❓❓❓ Open questionsWe've got a lot of open questions we're curious about -- also interested if there's anything not on this list that's on your mind!
|
|
+1 to the second last open question on overriding defaults. It would be very helpful to keep agent skills up to date based on dbt best practices etc, however, being able to override those and customize the dbt development workflow for the specific org would be immensely useful. I was working on creating an agent specific rules files for these and that can still be the way to configure those - so keeping dbt agent skills separate from the overrides and specify how I want the agents to interact with skills, in the rules file. Curious how the community is thinking about this. |
|
To the package-lock.json point, check out this discussion about skill packaging generally: agentskills/agentskills#198 - would probably be good to track with the centralized spec on this |
|
Great discussion. I've been building an agent-driven dbt project (~485 models, 10 source systems, energy domain) and have spent the last few months iterating on exactly this problem — how to make agents effective at real dbt work, not just simple tasks. A few things I've learned that might be useful as you think about the spec. Three tiers, not two The discussion frames skills as community ("how to do the thing") vs. project-specific ("how we do things here"). In practice I've found there are actually three distinct layers:
The first two are about building models correctly. The third is about building the right models. Community skills handle tier 1. Project skills handle tier 2. But the hardest problem — building gold-layer models that accurately represent business logic — requires tier 3, and no community skill can provide that. For any spec work, I think this matters because skills should be designed to reference project context, not embed it. A community skill says "load the source context for this table." The project provides the actual context. That separation is what makes skills composable across projects. Skills without enforcement are just documentation We had well-documented staging conventions in markdown. Agents read them. We still had 56% non-compliance across our staging models — the agents would pattern-match against whatever existing model they happened to read first, which was often an older model that predated the conventions. What actually moved the needle was building a structural validator (a Python script) that checks every staging model for the required CTE pattern, tag schema, surrogate keys, and explicit column lists — and returns agent-readable error messages with specific remediation instructions pointing back to the convention docs. The agent runs this as part of its workflow, reads the structured errors, fixes them, reruns until clean. We went from 56% to 100% compliance on the sources we've applied it to. The insight: skills need to be able to include or reference executable validation, not just instructions. A skill that says "build it this way" is useful. A skill that says "build it this way, then run this validator, and here's what the errors mean" is dramatically more effective. If the spec supports a Context assembly is the hard problem The discussion is mostly about distribution — how to install and manage skills via A project might have 20 installed skills plus hundreds of context files. Without a routing mechanism, the agent either loads everything (blows the context window) or guesses (gets it wrong). We solved this with a decision table pattern — a file that maps request types to deterministic action sequences specifying exactly which files to load in what order: This is progressive disclosure — the agent loads a lightweight router first, then task-specific instructions, then data. Maximum two hops to any piece of information. Token-efficient and deterministic. I don't think dbt needs to solve context assembly in the spec, but it's worth acknowledging that distribution without assembly guidance leaves the hardest part to every individual project. Even a convention for how skills can declare their dependencies on other skills or project context files would go a long way. On @gwenwindflower's point about project scope Strongly agree. The unique value here is dbt managing skills inside dbt projects. Our most valuable skills are deeply project-specific — they reference our source systems, our conventions, our validator scripts, our business entity definitions. Those belong in the repo, versioned with the code they describe. Community skills from One thing I'd add to the |
|
Completely agree with this, and the emphasis on composition+progressive disclosure especially. The default patterns do not really encourage best practices here, you have to do what @rstover-fo described somewhat manually — model providers are not terribly incentivized to help you maximize context efficiency. Also, given how early all these constructs are, the composition and reference patterns are likely to evolve even further. It might not be possible to handle all of this, but I think digging into this area could be another potential advantage here: dbt-managed skill creators could focus on the content, while dbt implements the current best practices for access and composition. If those evolve, the The decision-tree level is probably too deep/specific, but some of the space below that is more generic: see this pattern in how Vercel implements their web-design-guidelines and vercel skills https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals (I believe the skills are linked in there in addition to the context on why they use this approach, but essentially it's: make a bunch of reference material available and then give the agent a compressed index of it). This kind of thing. "You bring the content, we'll give you the best composition pattern, and evolve it as research progresses" is very compelling, particularly if patterns specific to the most effective data modeling context emerge. |
|
It is definitely a work in progress - will report back - unless things change by the time I get to really experiment. Even with some of this implemented, my context windows rapidly close (outside of playing around with the new 1M context windows) |
To me, the ✨unique advantage✨ of dbt-managed skills is based on dbt's ability to serve both deeply technical and less technical users equally. The latter are less likely to spend lots of time thinking about their skill library and agent configs, so your points around onboarding/setup feel the strongest to me: this creates a way for the former to provide easy, accessible consistency for the latter — trés dbt! With that in mind, here are my thoughts on how I would want to see it work, based on some of your questions:
One interesting way to manage this would be a installing dbt skills into a global store (like My impression of the vibes is that users are yearning for more unity/stability/simplicity in the rapidly shifting world of agent configs, so adding another potential source to the mix that works outside the project and requires more config files and overrides feels more complex, while a simple system that works inside the world of dbt projects based on a new deps YAML key and does not require users to think about the gnarly web of agent configs is appealing. Essentially — dbt managing skills in dbt projects feels good, but dbt managing skills outside of dbt projects feels like it doesn't add unique advantage and does add complexity and surface for problems (to me). |
|
Y'all should name this "cbt": Context Build Tool |
|
At last a single acronym we could adopt with no potential for confusion |
Can you please elaborate on how you made the jump from "quickly onboard agents" to "agent skills"? |
|
Great question. Other options considered:
Agents.md is great for single repos, but the lack of composability and progressive disclosure more or less makes it a no go for this since we're going to need to include much more context than we can reasonably put in an agents.md. Building a dbt first context management spec was compelling. Could this just live in existing dbt constructs? Could we have something lightweight (text only dbt models that can get chained together to build the prompts). But cross compatibility is critical here. We need to make it so that the context you build and use in dbt is accessible to other agents. In that world, skills look like the best pick. There's also a lot of great discussion happening around how to extend agent skills - most of the things we'd want to see (versioning, reffing etc) are already being discussed by the team maintaining skills. Anything else on your mind that we should be looking at? |
|
Maybe it's the examples provided, but this version of dbt skills doesn't feel compelling to me. I've found Claude Code to be very good at well-defined tasks. Example skills I'd write:
Put another way, I see skills as the mise en place to let Claude cook. |
|
Similar setup to @rstover-fo — ~230 models, 5 source systems, solo, Cursor, 17 skills and 16 rules. File-pattern routing for context assembly. @rstover-fo's decision table maps request types to action sequences ("build staging model for X" → load these files). I use a complementary approach — routing by which file the agent is touching:
The agent doesn't need to know what kind of task it's doing. If it's editing a file in Both patterns are useful. Request-type routing handles explicit tasks ("build me a staging model"). File-pattern routing handles ambient context ("I'm working in the staging layer, so these conventions apply"). If the spec supports a way for skills to declare "when does this apply?" — whether by request type, file pattern, or both — that would make context assembly much less manual. Cursor has Convention rules > skills for getting started. Naming prefixes, column patterns, SQL formatting, header blocks. Before I had them, every generated model needed reformatting. After, output matched the project first try. Most of mine started as dbt's own best practices docs rewritten as rule files — community knowledge that could ship as Project-scoped only. +1 @gwenwindflower — skills should live in the repo, not in user-level configs. In my setup, skills and rules don't just contain text instructions — they reference dbt macros and call shell scripts directly. A That raises a question for the spec: if Feature requests from building 17 skills:
Happy to share examples if useful. |
|
Something to keep in mind for the “Structured test failure output” point: this might involve shipping rows of data off to an LLM provider like Anthropic or OpenAI. A whole different data security consideration than sending over schema information not sure how the opt-in and sign-off flow would work for this, but I’d want to at least make the user aware that what they’re about to do is that |
Fair. |
|
As an additional thought, this is how I’m thinking about it: I feel like this might be getting framed at the wrong layer. Distributing “skills” is definitely useful, but on their own they’re pretty stateless. They don’t really capture the context of a dbt project. The semantic layer helps with meaning (metrics, dimensions), but if an agent is actually working on pipelines, it also needs structure. Things like lineage, dependencies, tests, and conventions. That context already lives in the dbt project. So to me, the opportunity isn’t just distributing skills, it’s more about dbt as the Agent Context Layer. Without that, skills stay generic. With it, agents can actually work safely and correctly on real projects. |
|
The "skills as structured instructions" framing here resonates. Once you have many skills interacting, the hard problem becomes authoring them consistently, not just distributing them. One thing that helps: treating each skill as a set of typed semantic blocks rather than free-form prose. Role, objective, constraints, examples, output format. Each block has a different job and different failure modes. When a skill produces unexpected agent behavior, knowing which block to fix is faster than rereading the whole text. I built flompt for exactly this, a visual prompt builder that decomposes instructions into 12 typed blocks and compiles to Claude-optimized XML. Open-source: github.com/Nyrok/flompt If dbt adds native skill support, a schema that separates "what the agent must do" from "how it should behave" from "what it cannot do" would scale a lot better than flat markdown. |
|
At first I was skeptical of this proposal, because I thought existing distribution mechanisms would be superior or preferred to a dbt-native way to distribute skills. But now as I think through the problem of packaging and distributing skills in large enterprises who have adopted dbt, I believe that Skill distribution is a significant hurdle with big architectural implications. Skills are going to really enhance the ways that dbt project evolves, and enterprise platform teams will want to provide skill-based capabilities to various teams. Providing them a similar way to maintain and distribute these skills (as compared to dbt packages), I think, will help skill adoption and overall make data teams move faster. |
|
@dbeatty10 -> Another open question. If I remember correctly, |
|
I think the idea is that skills defined in private repositories would work in the dbt platform (similar to native private packages). But the git token method would not work because The consequences would be that:
|
|
This is a really exciting direction. Packaging and distributing agent skills via dbt deps makes a lot of sense. One thing I’ve been thinking about while experimenting with AI-assisted analytics workflows is where the boundary should be between what dbt standardizes vs what teams define themselves. In practice, the hardest part hasn’t been generating models, it’s everything around them:
Those pieces are highly organization and domain-specific. So I wonder if the long-term opportunity here isn’t to standardize the interfaces around workflows rather than the workflows themselves. For example:
That would allow skills to be distributed and reused, while still letting teams encode how their business actually works. In that model, AI workflows start to look a lot like dbt projects themselves (modular, version-controlled, and domain-owned). Curious if others are seeing similar challenges, especially around validation and semantic alignment becoming the real bottlenecks rather than model generation. |
|
Really valuable thread. From building rules files for dbt-heavy projects, a few patterns that have made the biggest difference: The rules that eliminate the most drift: On skills location: the project-level CLAUDE.md / AGENTS.md is the right level for the conventions above. A dbt-specific "framework skill" (like the dbt agent skills repo) handles the API knowledge (ref(), source(), macro syntax). The project file handles team conventions that the framework skill cannot know (naming patterns, layer boundaries, test requirements). Both layers together produce much more consistent output than either alone — the framework skill stops API hallucinations, the project file stops architectural drift. On open questions: the "where do skills live?" question has a practical answer today — alongside the We have been publishing free CLAUDE.md starters per stack. No dbt-specific one yet, but the pattern above is what we have found works: https://gist.github.com/oliviacraft |
|
The strongest argument for dbt-native skill support is that dbt already understands project structure, lineage, contracts, sources, exposures, and package boundaries. Generic agent skills can tell an agent how dbt usually works; dbt-managed skills can tell it how this project works. I would separate three layers:
For safety, skills should not only contain instructions. They should declare applicability: paths, resource types, dbt versions, adapters, and whether the skill is advisory or required. That lets an agent load a small, relevant context set instead of reading every rule file. A useful v1 could focus on discovery and packaging: |
|
When you work in an enterprise with dozens of projects or as a consultant you end up having pretty much the same structure, macros and everything over and over, as that simplifies moving across projects and onboarding of people across projects. In my case I have created the Pragmatic Data Platform (PDP) that is used by multiple enterprises on multiple projects each with many internal and consulting colleagues working on them. With my new book Building a Pragmatic Data Platform with dbt and Snowflake published earlier this month I expanded the scope and automated much of the work, so I am distributing a PDP dbt Package with the macros to quickly start building. Now I have created also a Skill explaining and directing AI agents to use these macros to build the full pipelines exploring the data (like files to be ingested and landing tables) and connecting the dots. My colleagues are already using the Skill in dbt Platform, but we have to copy it in every repo and the same is for updating. I see the same distribution need that is now discussed for Skills also for other enterprise level objects like conventions, instructions not worth to be bundled as a Skill, TEMPLATES and common queries (like the SQL to get from SF the expressions to ingest a Parquet file). We could make everything into a skill, but TEMPLATES and common queries are dbt What I see is that at the most general level there are some objects that must be available inside of the dbt project, but they do not follow the code lifecycle. They are not committed or changed inside the repo, they are changed in some other place and get into the repo as a new version. I see these as Pluggable extensions (plug-ins) pretty much as packages are. This along with a way to specify where you want it to be "plugged-in" would be a quite generic and powerful mechanism, that along with the ability to specify paths in Another useful point is the transitive behavior of packages bringing in Skills or any of these plug-ins. My concern here is a balance between automation that would be served by allowing a package to bring in a Skill or other plug-ins and the easy of discovery / understanding by the user. If I have 3 skills, a bunch of templates and handy queries deep inside |
|
@RobMcZag I am speaking with a dbt client and they feel the exact same way as you do. Thanks for this clear explanation. |
|
@rstover-fo 485 models, agent-driven, 10 sources. Skills teach the agent the workflow. They don't stop it shipping SQL that runs clean and returns the wrong number. That's the gap we kept hitting on our own pipelines. So we built SignalPilot: open-source building blocks that add verification on top of the agent you already run. Same Claude model went 39.5% to 96.9% on ADE-bench. How are you catching wrong-but-clean output at that scale? |
Uh oh!
There was an error while loading. Please reload this page.
Background
Agents are increasingly being used alongside dbt to build, test, and manage data projects. Agent skills are increasingly being used to transform generalist coding agents into agents with real depth of expertise into dbt (see dbt agent skills). Skills are instructions that tell agents how to do something. Since they're text-based with minimal syntax requirements, anyone on a team can author them. Once written, those skills can be picked up by tools like Claude Code, Cursor, Copilot, Codex, and others.
Some of these skills are very dbt-specific, teaching agents the ins and outs of the dbt framework and language, capabilities like "how to add a unit test" or "how to troubleshoot a failing build". Others are more general but still essential to doing dbt work effectively. This includes things like understanding the data context surrounding a dbt project, knowing team development conventions, or navigating the structure of an org-wide mesh deployment. In practice, we expect people to accumulate skills that range from tightly coupled to the dbt framework to broader development workflows.
We believe this is going to accelerate. Over the coming months, more and more people will be using agents with dbt, and those agents will rely on multiple interacting skills — some for one specific dbt project, some shared across an organization, some published to the community.
👉 The question we're exploring here is whether dbt itself should provide a native way to manage these skills. 👈
dbt could facilitate using agent skills and sharing amongst dbt practitioners by extending the dbt language spec, dbt Package Hub, and dbt commands to be aware of Agent Skills. The rest of this Discussion explores different ideas of how we could do that.
Why dbt? Why not just use existing skill distribution tools?
This is the most important question to address up front.
Skill installers like the Vercel Skills CLI and Tessl already exist. If those are strictly superior for our use case, dbt should probably stay out of it. So what could dbt offer beyond what's already available?
The short hypothesis is making skills feel native and organic to dbt.
A few things we think matter:
dependencies.ymlthe same way you declare packages, anddbt depswould handle the rest.dbt depsand get everything they need — packages and skills. No separate orchestration step, no additional tooling to learn. That's a meaningful reduction in friction. (Note: you'd still need to install your coding agent separately —dbt depswould give you the skills half, not the agent half.)If, after reading all of this, your reaction is "NPX skills are plenty good enough and dbt shouldn't bother" — that's a completely valid outcome of this discussion. We want to hear if that's the case!
A note on pace
Historically, the dbt language spec has evolved deliberately, and there's been a high bar to add new features.
But today's technologies are moving faster than at any time in history. Even though skills as a concept is only a few months old, we are already seeing significant adoption among our user base. If we wait for the kind of certainty we'd normally want before changing the language spec, we risk leaving friction in the workflows people are already adopting.
We're thinking it may be worth adding skills support so we can iterate and learn (possibly experimentally, or behind a feature flag). We're not fully convinced yet, but we think we're closer than we expected to be. This discussion is a big part of how we figure that out, together.
Problems to solve for
For agent skills that are specific to dbt:
Ultimately the question boils down to two questions:
Potential solution
Today, dbt packages are shareable, discoverable, and installable via the dbt Package Hub at hub.getdbt.com. We could solve all three problems above by extending the dbt language spec, dbt Package Hub, and dbt commands to be aware of Agent Skills.
dbt could:
Details to consider
Potential spec
Here’s a potential spec to add a new
skills:top level key intodependencies.yml:A simple example:
More examples with different skill locations and install methods
To install skills:
To disable installation of skills:
Conclusion
It’s a real open question how (and if!) we should natively support skills as part of the dbt language spec. We’re looking forward to hearing from the Community and integrating your thoughts into the ultimate decision.
All reactions