// Use when a user needs help triaging dbt-core to Fusion migration errors. Runs dbt-autofix first, then classifies remaining errors into actionable categories (auto-fixable, guided fixes, needs input, blocked).
| name | migrating-dbt-core-to-fusion |
| description | Use when a user needs help triaging dbt-core to Fusion migration errors. Runs dbt-autofix first, then classifies remaining errors into actionable categories (auto-fixable, guided fixes, needs input, blocked). |
| allowed-tools | Bash(dbt:*), Bash(git:*), Bash(uvx:*), Read, Write, Edit, Glob, Grep, WebFetch(domain:api.github.com) |
| compatibility | dbt Fusion |
| metadata | {"author":"dbt-labs"} |
Help users understand which Fusion migration errors they can fix themselves vs which are blocked on Fusion updates. Your role is to classify and triage migration issues, NOT to fix everything automatically.
Key principle: Not all migration issues are fixable in your project. Some require Fusion updates. Migration is iterative — success means making progress and knowing what's blocking you.
This skill is a strict procedure, not general guidance.
The assistant must follow this order:
dbt debugdbt-autofix, then review its changesHard rules:
dbt1065 package version compatibility warnings specifically (e.g. Package '<package_name>' requires dbt version [>=1.2.0, <2.0.0]) — ignore these. If autofix was run, it will have already upgraded packages that need upgrading. If dbt1065 warnings persist after autofix, no manual package updates are needed.By default this skill uses dbt compile to reproduce and validate errors. The command can be customized:
dbt build, dbt test --select tag:my_tag), use that insteadrepro_command.txt file exists in the project root, use the command from that fileBefore doing anything else, ask the user if they'd like to verify their credentials work on Fusion.
Ask: "Would you like to start by running dbt debug to verify your credentials and connection work on Fusion? This catches environment issues early before we dig into migration errors."
Run:
dbt debug
What to check in the output:
dbt debug fails:profiles.yml and credentials before proceeding. Migration triage can't begin until the connection works.dbt debug checks may not be relevant to the migrationdbt debug succeeds:Confirm the environment is healthy and proceed to Step 1.
That's fine — proceed to Step 1. But if connection errors appear later during classification, circle back and suggest running dbt debug.
Before classifying any errors, ensure the user has run dbt-autofix on their project.
Prompt the user to run dbt-autofix (a first-party tool maintained by dbt Labs that automatically fixes common deprecation patterns):
uvx --from git+https://github.com/dbt-labs/dbt-autofix.git dbt-autofix deprecations
Important: Wait for autofix to complete before proceeding with classification.
Before analyzing any migration errors, you MUST understand what autofix changed:
Review the git diff (if project is in git):
git diff HEAD~1
Read autofix logs (if available):
Key things to look for:
meta:?Why this matters: Some migration errors may be CAUSED by autofix bugs or incorrect transformations. Understanding what autofix changed helps you:
Do not proceed with classification until you understand autofix's changes.
Use the 4-category framework to triage errors. For the full pattern catalog see the Error Patterns Reference. For detailed category definitions see Classification Categories.
Can fix automatically with HIGH confidence
warn_if='{{ "text" }}'analyses/ files (dbt0209, dbt0404, or other codes < 1000) — analyses are optional query files, not production models. The correct fix is to add {{ config(static_analysis='off') }} at the top of the analysis SQL file. Do not rewrite the SQL or remove content — just disable static analysis for that file.Can fix with user approval — show diffs first
config.require('meta').key to config.meta_require('key').meta_get() error (dbt1501) — dict.meta_get() to dict.get()meta:dbt1065 package compatibility warnings (e.g. Package '<package_name>' requires dbt version [>=1.2.0, <2.0.0]) are not errors — autofix handles package upgrades. If dbt1065 warnings persist after autofix, no manual action is needed.static_analysis: off for the model--models/-m, replace with --select/-sSELECT 1 or column listRequires user decision — multiple valid approaches
analyses/ queries — ask if analysis is actively usedRequires Fusion updates — not directly fixable in user code.
When an error is Category D:
Category D signals:
WebFetch with URL https://api.github.com/search/issues?q=repo:dbt-labs/dbt-fusion+<error_code>+<keywords>&type=issues to find existing issues. Don't tell the user to search manually — do it yourself.panic!, internal error, RUST_BACKTRACEnot yet implemented: Adapter::methodWhen classifying errors, check in this order:
site:github.com/dbt-labs/dbt-fusion/issues <error_code> <keywords> — Category D if open issue with no workaroundInclude autofix context at the start of your analysis:
Autofix Review:
- Files changed by autofix: X files
- Key changes: [brief summary]
- Potential autofix issues: [if any detected]
Format your analysis clearly:
Analysis Complete - Found X errors
Category A (Auto-fixable - Safe): Y issues
Static analysis in 3 analyses/ — Can disable automatically
Quote nesting in config — Can fix automatically
Category B (Guided fixes - Need approval): Z issues
config.require('meta') API change (3 files) — I'll show exact diffs
Unused schema entries (2 files) — I'll show what to remove
Source name mismatches (1 file) — Needs alignment with YAML
Category C (Needs your input): W issues
Permission error in model orders — Hardcoded table name - is this a ref or source?
Failing analysis — Is this actively used or can we disable it?
Category D (Blocked - Not fixable in project): V issues
MiniJinja conformance gap — Fusion fix needed (issue #1234)
Recording/replay error — Test framework issue, not a product bug
Recommendation: [What should happen next]
Before fixing anything, ensure you've reviewed autofix changes (see Step 1).
After classification:
Critical validation rule: After EVERY fix, re-run the repro command (see Repro Command Behavior) — NOT just dbt parse.
Handle cascading errors: Fixing one error often reveals another underneath. This is expected. Report new errors and classify them.
Track progress:
Progress Update:
Errors resolved: 5
Static analysis in analyses (auto-fixed)
Config API x2 (guided fixes - you approved)
Pending your input: 2
Permission error in orders
Analysis file decision
Blocked on Fusion: 3
MiniJinja issue (#1234)
Framework error (test infrastructure)
Next: [What to do next]
dbt parse alone for validation: Use the repro command (see Repro Command Behavior)dbt debug first: If you see connection or credential errors during triage, suggest running dbt debug to verify the environmentdbt1065 package version compatibility warnings specifically (e.g. Package '<package_name>' requires dbt version [>=1.2.0, <2.0.0]) — ignore these. Autofix upgrades packages that need it; if dbt1065 warnings remain after autofix, no manual package updates are needed.Formats and executes dbt CLI commands, selects the correct dbt executable, and structures command parameters. Use when running models, tests, builds, compiles, or show queries via dbt CLI. Use when unsure which dbt executable to use or how to format command parameters.
Generates a Mermaid flowchart diagram of dbt model lineage using MCP tools, manifest.json, or direct code parsing as fallbacks. Use when visualizing dbt model lineage and dependencies as a Mermaid diagram in markdown format.
Use when migrating a dbt project from one data platform or data warehouse to another (e.g., Snowflake to Databricks, Databricks to Snowflake) using dbt Fusion's real-time compilation to identify and fix SQL dialect differences.
Creates unit test YAML definitions that mock upstream model inputs and validate expected outputs. Use when adding unit tests for a dbt model or practicing test-driven development (TDD) in dbt.
Use when creating or modifying dbt Semantic Layer components — semantic models, metrics, dimensions, entities, measures, or time spines. Covers MetricFlow configuration, metric types (simple, derived, cumulative, ratio, conversion), and validation for both latest and legacy YAML specs.
Implements dbt Mesh governance features (model contracts, access modifiers, groups, versioning) and multi-project collaboration with cross-project refs. Use when implementing dbt Mesh governance, setting up cross-project refs with dependencies.yml, disambiguating similarly-named models across projects, or splitting a monolithic dbt project into multiple mesh projects.