CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

upgrading-dbt

Use when a user wants to upgrade, update, or migrate a dbt project to the latest version — e.g. "upgrade my dbt project," "migrate this off dbt 1.5," "get this project running on the latest dbt," "bump the dbt version." Upgrades a dbt v1 project (on 1.3, 1.4, 1.5, 1.6, or 1.7) all the way to 1.12, applying the required breaking, behavior, and deprecated changes from a data-driven issue corpus. Inputs — starting_version (the project's current dbt minor, one of 1.3/1.4/1.5/1.6/1.7) and adapter_type (snowflake/redshift/bigquery/databricks/spark); both are normally supplied by the caller (e.g. the dbt VS Code extension), with fallbacks described in the skill.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

The canonical home for this skill is dbt-labs/dbt-agent-skills

SKILL.md
Quality
Evals
Security

Quality

Content

77%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An unusually rigorous procedure: mandatory phase order, bounded repair loops, artifact contracts, and a well-executed two-profile progressive-disclosure split with all referenced files verified present. Its weakness is token efficiency — several multi-sentence rationales are stated two or three times and rhetorical framing pads the rules — and one garbled sentence in rule 1 leaves the --target/--profile guidance incomplete.

Suggestions

State each rationale once and cross-reference it: the 'per-issue parse is meaningless' argument appears in 'Validation is deliberately at the end', again in Step 5, and again in Step 7; the human-confirmation rule appears in the automation_type table, rule 4, and Step 6; the dead-config flag warning appears in the intro and Step 5. Cut to one canonical statement plus a pointer.

Repair the fragment in Non-negotiable rule 1 — "`--target`/`--profile` to point somewhere else, and never a warehouse the session was not already connected to" is missing its verb (presumably "Never pass `--target`/`--profile` ..."); as written, the reader must guess the instruction.

Trim persuasive framing ("all of which have been violated in testing", "which makes it the easiest to forget; it is not exempt", "a plausible-looking path you invent turns a warning into a real breakage") — state the rule and its consequence in one clause instead of arguing for it.

DimensionReasoningScore

Conciseness

The core content (steps, schemas, status values) is dense and load-bearing, but whole rationales are repeated: why validation is at the end is explained three times ("Validation is deliberately at the end, not per issue", the Step 5 "do not run the parse gate after each one" paragraph, and Step 7's parse-failure guidance); "never apply a `human` issue without confirmation" appears three times; "a flag for a behavior the project does not use is dead config" appears twice; and persuasive asides ("all of which have been violated in testing", "it makes rule 7 load-bearing") argue for rules rather than state them. This is more than the level-4 anchor's 'minor instances of over-explanation', but well short of the level-2 anchor's pervasive padding.

3 / 5

Actionability

Highly executable: exact operation invocations with verbatim notes ("status-set → preflight = waiting_input, note 'Continue on branch <branch>?'", "ask: 'You are on branch `<branch>` with a clean tree. Continue the migration here?'"), complete JSON artifact schemas, and enumerated legal status values. Falls short of anchor 5 only on a garbled fragment in rule 1 — "`--target`/`--profile` to point somewhere else, and never a warehouse the session was not already connected to" is missing its verb, leaving that instruction's intent to inference.

4 / 5

Workflow Clarity

A mandatory 10-step execution order with per-phase status-set open/close, an ordered verification gate ("dbt parse is mandatory and always first", "Stop at the first one that fails") with bounded feedback loops ("max 5 whole-project attempts", "Max 3 command-loop attempts"), revert-on-failure, a re-detection step confirming fixes held, and explicit end-of-step checklists ("Nothing should remain `detected` ... confirm with `list-issues --status detected,pending`"). This matches the anchor with explicit validation, error-recovery loops, and checklists.

5 / 5

Progressive Disclosure

Clean one-level-deep split, all verified present: rules and invariants in SKILL.md; mechanics in exactly one of two profile files selected by a decision table ([references/exec-local.md], [references/exec-platform.md], "Load **exactly one**"); per-migration data in `references/kb_<FROM>_<ADAPTER>.json` bundles (66 present, matching the documented naming convention) loaded via `load-bundle`. The body correctly does not inline mechanics or the issue corpus, and navigation signals ("no shell means Studio") are explicit.

5 / 5

Total

17

/

20

Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A model trigger description: explicit 'Use when' clause with four quoted user utterances, a concrete third-person statement of scope and mechanism, and enumerated inputs. The only nit is that the version list (1.3–1.7) is stated twice, and the inputs sentence borders on documentation rather than triggering — but no dimension's anchors are better served by trimming it.

DimensionReasoningScore

Specificity

"Upgrades a dbt v1 project (on 1.3, 1.4, 1.5, 1.6, or 1.7) all the way to 1.12, applying the required breaking, behavior, and deprecated changes from a data-driven issue corpus" names multiple concrete actions with enumerated versions, target, and adapters, plus explicit inputs — comprehensive coverage for the domain. Not the level-4 anchor, which expects minor gaps in coverage; none are evident.

5 / 5

Completeness

Both halves are explicit: 'what' is "Upgrades a dbt v1 project ... all the way to 1.12, applying the required breaking, behavior, and deprecated changes" and 'when' opens with "Use when a user wants to upgrade, update, or migrate a dbt project" followed by concrete trigger phrases. This matches the anchor for a clear what AND when with concrete triggers, exceeding the level-4 anchor's "'when' could be more explicit".

5 / 5

Trigger Term Quality

"upgrade, update, or migrate a dbt project to the latest version — e.g. 'upgrade my dbt project,' 'migrate this off dbt 1.5,' 'get this project running on the latest dbt,' 'bump the dbt version'" covers the natural synonym set (upgrade/update/migrate/bump/latest) with four verbatim user utterances. No meaningful file-extension trigger exists for this domain, so the level-4 anchor's 'a few natural terms missing' does not fit better.

5 / 5

Distinctiveness Conflict Risk

Every trigger phrase is anchored on dbt and version migration ("migrate this off dbt 1.5", "bump the dbt version"), giving a clear niche with minimal overlap risk — a generic dependency-upgrade skill would not match these utterances. Third-person voice is used correctly ("Upgrades a dbt v1 project").

5 / 5

Total

20

/

20

Passed

Validation

75%

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 12 / 16 Passed

Validation for skill structure

CriteriaDescriptionResult

skill_md_line_count

SKILL.md is long (705 lines); consider splitting into references/ and linking

Warning

allowed_tools_field

'allowed-tools' contains unusual tool name(s)

Warning

metadata_version

'metadata.version' is missing

Warning

referenced_paths_exist

Referenced path issues: 3 missing

Warning

Total

12

/

16

Passed

Repository

dbt-labs/dbt-agent-skills

Path

skills/dbt-migration/skills/upgrading-dbt/SKILL.md

Reviewed

Table of Contents

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.