Skip to main content

Use skills with dbt Wizard in the dbt platform Beta

Skills are reusable instructions that help dbt Wizard follow your team's SQL conventions, naming rules, modeling patterns, and workflows without repeating them in every prompt.

dbt Wizard also includes built-in skills from dbt Agent skills, maintained by dbt Labs. These are always available, no setup needed.

For general project context (AGENTS.md, CLAUDE.md), refer to Migrate to dbt Wizard — dbt Wizard reads those instruction files out of the box.

How skills work​

At the start of every session, dbt Wizard scans for repo-level skills in the .agents/skills/ directory in your dbt project root:

.agents/
  skills/
    your-skill-name/
      SKILL.md

Custom skills use the Agent Skills format, the same format used by dbt Agent Skills on GitHub. A skill file contains YAML frontmatter (name, description) and a Markdown body with instructions.

If a custom skill and a built-in skill share the same name, the custom skill takes precedence.

Create a skill​

In Studio IDE, use the file explorer to create the skill directory and file:

  1. Create a folder at .agents/skills/SKILL_NAME/ in your project root.
  2. Add a SKILL.md file inside it. A typical SKILL.md includes:
    • YAML frontmatter with at minimum name and description.
    • A Markdown body with sections for when to use the skill, workflow steps, and conventions.
    • Optional references/ files for extra detail the agent can load when needed.
  3. Optionally add supporting files under .agents/skills/SKILL_NAME/references/ (for example, references/naming-conventions.md) that the agent can read when the skill is active.
  4. Start a new dbt Wizard chat — skills are discovered at session start, so mid-session changes won't be picked up until you start a new chat.

Skill file format​

A skill file has two required parts: YAML frontmatter and a Markdown body.

  • Frontmatter: Includes at minimum, name and description. The description is especially important: it's how dbt Wizard decides when to apply the skill automatically.
  • Body: Markdown sections explaining when to use the skill, what it does, and any conventions or constraints.
  • References (optional): Supporting .md files in a references/ subfolder for detail that would make SKILL.md too long.

Example skill file​

If you're new to skills, start with a small SKILL.md like the following example, then grow it over time:

---
name: my-team-style
description: Apply Santi Corp's modeling conventions when editing or creating dbt models. Use when the user asks for refactors, new models, or YAML in this project.
---

# My team style

## When to use

Use this skill whenever you are changing SQL or YAML under `models/` and the user did not override these rules.

## Conventions

- Staging models use prefix `stg_` and live in `models/staging/`.
- Facts and dimensions use `fct_` and `dim_` prefixes respectively.
- Document new columns in the same PR as the model change.

For a full production-style example, refer to dbt's adding-dbt-unit-test skill.

Use a skill​

In the dbt Wizard chat panel:

  1. Prompt the agent and reference the skill by name — for example: Use my-team-style to refactor this model and update related YAML.
  2. If needed, use @ mentions to point to the skill file or supporting .md files directly.
  3. Review and approve proposed changes as usual in the dbt Wizard panel.

Built-in dbt skills​

dbt Wizard ships with skills from dbt Agent Skills, maintained by dbt Labs and the community. These capture analytics engineering knowledge for common workflows and are always available. The agent loads the relevant skill automatically when your prompt matches its use case.

For the latest catalog, refer to the dbt Agent Skills repository.

Tips​

  • Keep SKILL.md focused. One skill per concern (style guide, testing conventions, deployment workflow). Smaller skills are loaded more reliably than large monolithic ones.
  • Use description to control when dbt Wizard activates the skill. A precise description ("Use when creating or editing models in models/marts/") means the skill fires when relevant, not on every prompt.
  • Start a new session after adding or editing a skill. Skills are discovered at session start — mid-session changes aren't picked up until you start a new chat.
  • Cross-project sharing isn't supported yet. To reuse a skill in another repo, copy the skill files manually.

Was this page helpful?

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

0
Loading