跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

migrating-dbt-core-to-fusion

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).

dbt-labs · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add dbt-labs/dbt-agent-skills --skill migrating-dbt-core-to-fusion

技能说明


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

Fusion Migration Triage Assistant

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.

Mandatory execution order

This skill is a strict procedure, not general guidance.

The assistant must follow this order:

  1. Step 0: Ask whether to run dbt debug
  2. Step 1: Run or confirm dbt-autofix, then review its changes
  3. Step 2: Classify remaining issues
  4. Only after Steps 0–2 may the assistant propose or apply manual fixes

Hard rules:

  • Do not inspect project files before Step 0 is completed or explicitly skipped
  • Do not classify issues before Step 1 is complete
  • Do not edit files before presenting the autofix review and classification summary
  • If these rules are violated, acknowledge the violation, state which step was missed, and execute that step now before continuing
  • Focus on errors: For 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.

Additional Resources

  • References Overview — index of all reference material
  • Error Patterns Reference — full catalog of error patterns by category
  • Classification Categories — detailed category definitions with sub-patterns, signals, fixes, and risk notes

Repro Command Behavior

By default this skill uses dbt compile to reproduce and validate errors. The command can be customized:

  • If the user specifies a different command (e.g. dbt build, dbt test --select tag:my_tag), use that instead
  • If a repro_command.txt file exists in the project root, use the command from that file

Step 0: Validate Credentials with dbt debug

Before 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."

If the user agrees:

Run:

dbt debug

What to check in the output:

  • Connection test: Does it say "Connection test: OK"? If not, credentials need fixing first — this is NOT a migration issue
  • profiles.yml found: Is it loading the correct profile/target?
  • Dependencies: Are packages installed?

If dbt debug fails:

  • Connection/auth errors: Help the user fix their profiles.yml and credentials before proceeding. Migration triage can't begin until the connection works.
  • Profile not found: Help locate or configure the correct profile for Fusion
  • Other errors: Note them and proceed — some dbt debug checks may not be relevant to the migration

If dbt debug succeeds:

Confirm the environment is healthy and proceed to Step 1.

If the user skips this step:

That's fine — proceed to Step 1. But if connection errors appear later during classification, circle back and suggest running dbt debug.

Step 1: Run dbt-autofix (REQUIRED FIRST STEP)

Before classifying any errors, ensure the user has run dbt-autofix on their project.

Check if autofix has been run:

  1. Ask user: "Have you run dbt-autofix on this project yet?"
  2. Check git history for recent autofix-related commits
  3. Check for autofix log files

If NOT run yet:

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.

Understand autofix changes (CRITICAL):

Before analyzing any migration errors, you MUST understand what autofix changed:

  1. Review the git diff (if project is in git):

    git diff HEAD~1
    
  2. Read autofix logs (if available):

    • Look for autofix output files
    • Check terminal output saved by user
    • Understand which files were modified and why
  3. Key things to look for:

    • Which patterns did autofix apply?
    • What config keys were moved to meta:?
    • What YAML structures changed?
    • What Jinja modifications were made?
    • Were any package versions updated? (autofix upgrades packages that require it)

Why this matters: Some migration errors may be CAUSED by autofix bugs or incorrect transformations. Understanding what autofix changed helps you:

  • Identify if a current error was introduced by autofix
  • Revert autofix changes if they caused new issues
  • Avoid suggesting fixes that conflict with autofix changes
  • Know which patterns autofix already attempted (don't duplicate)

If autofix caused issues:

  • Document which autofix change caused the problem
  • Consider reverting that specific change
  • Report the autofix bug pattern for future reference

Do not proceed with classification until you understand autofix's changes.

Step 2: Classify Errors

Use the 4-category framework to tr

阅读完整来源 ↗