はじめに

dbt agent skillsが2026年2月に公開されました。

「AIエージェントにdbt開発を任せられる」という触れ込みでしたが、正直なところ「本当に使えるの？」という気持ちが先でした。

というのも、AIにコードを書かせて痛い目を見た経験が何度かあります。検証なしで動かしたら別のエラーが出た、既存モデルを確認せずに重複した実装をした、dbt parseが通ったからOKと判断したらdbt testでデータ品質の問題が出た——こういう失敗を繰り返してきました。

だから今回は「試してみた」で終わらせるつもりはありませんでした。Skillsあり／なしで同じ指示を出して、挙動の差分を記録する。そして両方に共通する限界も正直に書く。それがこの記事の目的です。

この記事でわかること

dbt agent skillsの実体と、インストール方法
Skillsあり／なしで同じ指示を出したときの挙動の差（シナリオ2つ）
両エージェント共通の限界（dbt testまで実行しない問題）
エラーの種類ごとに「どのコマンドで検出できるか」の整理

動作環境

技術	バージョン
Claude Code	最新版（2026年3月時点）
dbt-core	1.11.0-b4
dbt-duckdb	1.10.1
DuckDB	1.5.0
OS	Windows 11

実験はDuckDB環境で行っています。元々個人プロジェクトとして、BigQueryで構築したdbtプロジェクトをDuckDB用に移植して使いました。BigQueryでもSkillsの挙動は同様のはずです。

dbt agent skillsとは

dbt agent skillsは、AIエージェント（Claude Code）にdbtプロジェクトへの知識を持たせるためのSkillセットです。

実体はMarkdownファイル（SKILL.md）です。構造化されたプロンプト集であり、エージェントがタスクに応じて動的に読み込みます。

よく混同されるMCPとの違いはこうです。

	役割
MCP	ツールへのアクセス手段（認証・接続）
Skills	そのツールをどう使うかの知識

どちらか一方だけでも価値があり、補完関係にあります。

インストール済みのSkillは8つあります。

using-dbt-for-analytics-engineering
running-dbt-commands
troubleshooting-dbt-job-errors
adding-dbt-unit-test
answering-natural-language-questions-with-dbt
building-dbt-semantic-layer
configuring-dbt-mcp-server
fetching-dbt-docs

インストール方法

Claude Codeのチャット画面で以下を実行します。

/plugin marketplace add dbt-labs/dbt-agent-skills
/plugin install dbt@dbt-agent-marketplace

インストール後、/reload-plugins を実行してから新セッションを開く必要があります。この3ステップを踏まないと反映されないので注意です。

/plugin enable や /plugin disable はClaude Codeのチャット画面内で使うコマンドです。Windowsターミナルに入力すると「コマンドが認識されません」エラーになります（私はやりました）。

実験設計

実験のルールは1つだけです。

同じ指示をSkillsなし→ありの順で実行し、エージェントの挙動を記録する。

Skillsのオン／オフは /plugin disable と /plugin enable で切り替えました。また、Skillsの有無による先入観が入らないよう、毎回新セッションで実験しています。

実験したシナリオは2つです。

シナリオ	対応するSkill
① martsモデルの追加	`using-dbt-for-analytics-engineering`
② YAMLエラーの修正	`troubleshooting-dbt-job-errors`

実験に使ったdbtプロジェクトは、incrementalモデル・RFM分析・多粒度UNION ALL・カスタムテスト（positive_values、valid_date_range）まで実装した、それなりに複雑な構成のものです。

シナリオ①：martsモデルの追加

指示文

marts層に新しいモデルを追加してください。チャネル別の月次売上を集計するモデルです。

Skillsなしの挙動

ファイルを3つ読んだあと、即座にSQLを作成しようとしました。

int_sales_by_month にすでに channel カラムがあるので、それを参照して martsモデルを作ります。

dbt show は実行していません。既存のmartsモデルに同様の集計が含まれていないかも確認していません。新モデルが本当に必要かどうかも問いませんでした。

Skillsありの挙動

最初のアクションが全く違いました。

まず既存のmartsモデルを確認して、本当に新規モデルが必要か判断します。

既存モデルを読んだあと、カバレッジのギャップを分析してこう提案しました。

fct_sales_multi_grain：channel列はあるが年/週/日データが混在している
fct_sales_multidimensional：channelディメンション自体がない
→ 新規モデルは妥当。ただし既存モデルの拡張も可能。どちらを好みますか？

その後、dbt show を2回実行しました。

# 1回目：カラム構成の確認
dbt show --select int_sales_by_month --limit 10

# 2回目：チャネルの値を確認
dbt show --inline "SELECT DISTINCT channel FROM {{ ref('int_sales_by_month') }} ORDER BY 1" --limit 20

dbt show --inline は今回初めて見た使い方でした。ref() が使えるので、プロジェクト内のモデルを参照したアドホッククエリが実行できます。SKILL.mdに記載されているパターンがそのまま出てきました。

チャネル値が online と store の2種類と判明したあと、SQLを作成。schema.yaml へのテスト・ドキュメントの追加も自動で行い、accepted_values: ['online', 'store'] を実データに基づいた値で設定しました。

比較まとめ

観点	Skillsなし	Skillsあり
最初のアクション	即SQL作成	既存モデルの確認
新モデルの必要性	問わない	自発的に分析・提案
`dbt show` 使用	なし	2回（構造確認＋値確認）
ユーザーへの確認	なし	「新規 or 既存拡張？」
schema.yaml更新	なし	テスト・ドキュメント自動追加
accepted_valuesの精度	設定なし	実データに基づいた値

シナリオ②：YAMLエラーの修正

仕込んだ4つのエラー

marts/schema.yaml に意図的に4つのエラーを注入しました。

#	エラー内容	検出難易度
❶	`accepted_values` に実在しない値 `'mobile'` を追加	高（実データを見ないとわからない）
❷	`not_null` → `not-null`（typo）	低
❸	`tests:` のインデントミス（columnと同列になっている）	低
❹	`ref('int_sales_by_monthhh')`（存在しないモデル名）	低

指示文

dbt_learning_duckdb プロジェクトの marts/schema.yaml にエラーがあります。dbt parse が失敗しています。エラーを特定して修正してください。

Skillsなしの挙動

ファイルを読んで静的分析し、以下の4箇所を発見・修正しました。

行23: not-null → not_null（ハイフン→アンダースコア）
行26: tests: のインデントずれ
行32: int_sales_by_monthhh → int_sales_by_month（タイポ）
行43-46, 58-62, 71-75: relationships テストで無効な arguments: キーを使用

修正前に dbt parse は実行しませんでした。 修正後に1回だけ実行して「エラーなし」を確認し、完了と判断しています。

❶（'mobile'）は未発見でした。実データを確認しないとわからないエラーなので、YAMLを読むだけでは検出できません。

relationships テストの arguments: 修正はSkillsなしも検出しています。ただし「静的分析で発見した」のか「dbt parse の出力から診断した」のかはログ上では不明確です。

Skillsありの挙動

最初のアクションが全く違いました。指示を受けた直後に dbt parse を実行しました。

その後、3段階で深掘りしていきました。

# 1段階目
dbt parse 2>&1
→ WARNING: MissingArgumentsPropertyInGenericTestDeprecation

# 2段階目
dbt parse --no-partial-parse 2>&1
→ 警告の詳細を確認

# 3段階目
dbt parse --no-partial-parse --show-all-deprecations 2>&1
→ dbt 1.11の新構文に対応するため、ジェネリックテストの引数を
  arguments プロパティ下にネストする必要があると診断

Skillsなしが dbt parse を「確認ツール（1回）」として使ったのに対し、Skillsありは「診断ツール（3段階）」として使っていました。この違いが running-dbt-commands Skillの効果として最も明確に出た部分です。

修正後、予想していなかった提案が来ました。

なお、staging/schema.yml と intermediate/schema.yml にも同様の警告が6件残っています。修正しますか？

依頼されていないのに、プロジェクト全体の健全性まで目が届いていました。

比較まとめ

観点	Skillsなし	Skillsあり
最初のアクション	ファイルを静的分析	`dbt parse` を即実行
`dbt parse` の使い方	確認ツール（修正後に1回）	診断ツール（修正前から3段階）
修正箇所数	4箇所（❷❸❹＋`relationships`）	4箇所（❷❸❹＋`relationships`）
追加提案	なし	他ファイルへの波及（6件）を提案

両エージェント共通の限界

正直に書きます。

❶（accepted_values: ['mobile']）はSkillsあり・なし、両方とも未検出でした。

なぜ dbt test を実行しなかったのか

指示が「dbt parse が失敗しています」だったからです。両エージェントとも dbt parse が通った時点でゴールと判断し、dbt test まで進みませんでした。これはSkillsの有無の問題ではなく、指示の問題です。「dbt test が失敗しています」という指示を出せば結果は変わると思います。機会があれば検証して記事にしたいと思っています。

なぜ❶は dbt parse で検出できないのか

'mobile' が実在しない値かどうかは、YAMLを読むだけではわかりません。実データと照合して初めてわかるエラーです。検出するには dbt test の実行が必要で、dbt parse がどれだけ通っても発見できません。

エラーの検出タイミング整理

この実験を通じて、エラーの種類ごとに検出できるコマンドが違うことを改めて整理できました。

エラー種別	検出コマンド	今回の実験
構文エラー（typo・インデントミス）	`dbt parse`	✅ 両方検出
存在しないモデル参照	`dbt parse`	✅ 両方検出
ロジックエラー（実在しない値）	`dbt test`	❌ 両方とも未検出

「CIで dbt parse だけ走らせていれば安全」は間違いです。dbt test まで含めて初めてデータ品質が担保されます。これはAIエージェントを使うかどうかに関係なく、dbtを運用するうえで重要な観点だと思っています。

まとめ

Skillsありが明確に優れていた点を3つ挙げます。

1. 最初のアクションが違う
Skillsなしは「依頼されたことをすぐ実行」、Skillsありは「本当にそれが必要かを先に確認」します。モデル追加のシナリオで最も差が出た部分です。

2. コマンドを診断ツールとして使う
dbt parse を1回で終わらせず、オプションを変えながら段階的に深掘りしていきました。このアプローチはSKILL.mdのパターンがそのまま出てきたものです。

3. 依頼範囲を超えた提案をする
修正完了後に「他のファイルにも同様の警告が6件残っています。修正しますか？」と提案しました。依頼されていないのに、プロジェクト全体の健全性まで目が届いています。

一方で、dbt test まで実行しないという限界は両方共通です。 Skillsは万能ではありません。どのコマンドで何が検出できるかを理解した上で、適切な指示を出すことが必要です。

おわりに

次回はdbt agent skillsとFusionエンジンの組み合わせ実験を書く予定です。

この記事が、dbtプロジェクトにAIエージェントを導入しようとしている方の参考になれば嬉しいです。

著者について

データエンジニア（経験2年）。BigQuery・Treasure Data CDPを使ったデータ基盤構築を担当しています。

X（Twitter）：@sato_ml_journey
GitHub Pages（ポートフォリオ）：sato1046.github.io/docs/dbt/

参考リンク