Claude Code × dbtの組み合わせで使うdbt agent skills — 2つのチームの活用パターン

2026.06.04

IT技術

はじめに

今回のペアブログでは、たまたまデータ関連の部署のメンバー同士でペアを組むことになりました。
実際はチームが違うので業務の領域も異なるのですが、dbtをメインで使っているチームと、今回新たに導入するチームにそれぞれ所属しています。
両チームに共通するdbtと、社内でも利用が積極的に推進されているClaude Codeを組み合わせ、dbt agent skillsについて記事を書いてみることにしました。

dbt agent skillsの概要

dbt agent skillsとは

dbt Labsが公式に公開している、Claude Code向けのAgent Skillsセットです。これらのスキルはスラッシュコマンドで呼び出すものではなく、必要なタイミングで暗黙的に呼び出されます。ユーザーは使用したいスキルを指定することなく、プロンプトの内容からClaude Codeが必要なスキルを判断し、自動で読み込んで結果に反映してくれます。

たとえば「このモデルをbuildして」と依頼するとrunning-dbt-commandsが、「incremental設定のオプションを調べたい」と依頼するとfetching-dbt-docsが呼び出されるようなイメージです。

インストール手順

Claude Code上で次のコマンドを実行することでインストールできます。11個のスキルは基本プラグインと移行用プラグインの2つのプラグインに分かれて配布されており、すべて入れたい場合は両方のプラグインをインストールします。移行用プラグインは普段は使わないため、必要に応じて追加します。

1# marketplaceを追加
2/plugin marketplace add dbt-labs/dbt-agent-skills 
3
4# 基本プラグインをインストール
5/plugin install dbt@dbt-agent-marketplace 
6
7# 移行用プラグインをインストール（移行プロジェクトのときだけでOK）
8/plugin install dbt-migration@dbt-agent-marketplace

収録されているスキル

基本的なスキル（9種類）

日常的に発火するスキルで、基本プラグインに同梱されています。

using-dbt-for-analytics-engineering：
　dbtモデルの構築と修正、エラーのデバッグ、データソースの探索、テストの記述を担う
running-dbt-commands：
　dbt CLIコマンドを、正しいフラグ・selector・パラメータ形式で実行する
adding-dbt-unit-test：
　dbtモデル向けのunit testを追加し、テスト駆動開発を実践する
fetching-dbt-docs：
　dbtドキュメントを効率的に参照する」
troubleshooting-dbt-job-errors：
　dbtプラットフォーム上のジョブ失敗を診断し、解決する
building-dbt-semantic-layer：
　MetricFlowでsemantic models、metrics、dimensionsを作成する
answering-natural-language-questions-with-dbt：
　Semantic Layerに問い合わせて、ビジネス上の質問に回答する
working-with-dbt-mesh：
　dbt Meshのガバナンス（contracts、access、groups、versions）と、プロジェクト横断の連携を実装する
configuring-dbt-mcp-serve：
　Claude、Cursor、VS Code向けにdbt MCPサーバーをセットアップする

移行用スキル（2種類）

移行プロジェクト中に一度だけ使用するスキルで、移行用プラグインに同梱されています。

migrating-dbt-project-across-platforms：
　dbtプロジェクトをデータプラットフォーム間で移行する
migrating-dbt-core-to-fusion：
　dbtプロジェクトをdbt CoreからFusionエンジンへ移行する

現場プロジェクトでの活用例

活用例1 —— dbt Cloudジョブの失敗をスキルで調査

こんにちは、林です。私の所属するチームではメインの業務でdbtを利用しています。このスキルを使うのは初めてですが、インストールすればすぐに使えるため、実際の業務で使ってみることにしました。

事前準備: スキルが呼び出されたことを確認する仕組み

dbt agent skillsは暗黙的に呼び出されるため、業務中のどの場面でどのスキルが呼ばれているかを把握する仕組みを先に用意しました。Claude Code自体には公式のスキル呼び出しログ機能はないため、Hooks機能を使って自前のログファイルに書き出す形にしています。

.claude/settings.jsonのhooksにPreToolUseを追加し、Skillツールが呼ばれる直前にログ取得スクリプトを実行します。

1"hooks": {
2  "PreToolUse": [
3    {
4      "matcher": "Skill",
5      "hooks": [
6        { "type": "command", "command": "bash ~/.claude/hooks/log-skill.sh" }
7      ]
8    }
9  ]
10}

log-skill.shは、呼ばれたスキル名・タイムスタンプ・作業ディレクトリ・引数を.claude/skill-usage.logに追記し、画面に「⭐️ Skill: <スキル名>」のシステムメッセージを表示します。
（今回は目立たせたかったので絵文字をつけてみました）

1#!/bin/bash
2input=$(cat)
3skill=$(echo "$input" | jq -r '.tool_input.skill // "unknown"')
4echo "$input" | jq -c --arg ts "$(date -u +%FT%TZ)" \
5  '{ts: $ts, session: .session_id, cwd: .cwd, skill: .tool_input.skill, args: .tool_input.args}' \
6  >> ~/.claude/skill-usage.log
7jq -nc --arg msg "⭐️ Skill: $skill" '{systemMessage: $msg}'

これにより、次の2つができるようになります。

セッション中: Claude Codeの画面に「⭐️ Skill: <スキル名>」が表示される
振り返り: ~/.claude/skill-usage.logに1行JSONで残り、jqで集計できる

実際には以下のような形式で残ります。

1{"ts":"2026-05-24T06:29:35Z","session":"...","cwd":"/Users/name/dbt-project","skill":"dbt:running-dbt-commands","args":"build int__example__some_model --empty"}
2{"ts":"2026-05-24T07:02:05Z","session":"...","cwd":"/Users/name/dbt-project","skill":"dbt:fetching-dbt-docs","args":null}

調査対象

実際の業務で動かしているdbtジョブのランが、incrementalモデルのユニークテストで33件の重複を検出してErrorで終了していました。失敗の原因を調べるため、troubleshooting-dbt-job-errorsに調査を依頼しました。
先述の通り、このスキルはプロンプトの内容に応じて暗黙的に呼び出される仕組みなので、以下のようなプロンプトで発火させてみました。

スキルが特定した原因と対処

対象ランのURLを伝えると、スキルが次の流れで原因と対処を提示してくれました。

失敗テストとモデルを特定し、Data/Test Failureに分類
incrementalモデルの設定が原因で、月が変わるタイミングに同じキーのデータが二重に残ってしまっていることを特定
実際の重複件数（33件）が、原因となる仮説から想定される件数の範囲と一致することを確認
修正方針として、incremental設定を merge + unique_key に変更する案を提示
同系列の別モデルでも同じパターンが潜んでいないかを横展開チェック

エラーログだけでは見えない構造的な原因まで踏み込み、関連モデルの横展開チェックまで自動で行っています。

MCPサーバーがなくても動かせる

このスキルは本来、dbt CloudのMCPサーバー経由でAdmin APIを呼びランのログを自動取得する設計です。MCPサーバーが未設定の場合、初回はスキルが「ログをコピペしてください」とフォールバックします。
今回は、.envにdbt CloudのPersonal Access Tokenを置いていることを伝えたところ、スキルがそのトークンを使って直接dbt Cloud APIへアクセスしました。MCPサーバーを別途設定しなくても、Personal Access Tokenを発行することで、このスキルを使うことも可能です。

実際の業務での使い分け

今回、このスキルの動作を見るためにtroubleshooting-dbt-job-errorsを試してみましたが、日常の業務でランのエラー調査をするときは、プロジェクトメンバーが作成したトラブルシュート用のカスタムスキルを使用しています。プロジェクトの定型レポート（対象ラン情報／対象モデル／分類／原因／修正提案／検証結果／再発防止策）に沿って出力されるなど、業務に合わせてカスタマイズされている分、カスタムスキルの方が使い勝手が良いと感じます。

一方で、カスタムスキルが整備されていないプロジェクトでは、この公式スキルが有力な選択肢になると思います。私がスキルを使い始める以前は、dbt Cloudのログを見ながらBigQueryでテーブルを調べる、といった作業をすべて手で行っていました。そのため、1件のランの調査にかなり時間を要した記憶があります。もしまだ手動でランの調査をされているなら、効率化の観点から積極的に活用していくべきだと思います。

普段使っているカスタムスキルが無い状況でも公式スキルだけで調査を大きく効率化できる、というのを確認できたのが今回の収穫でした。

活用例2 —— dbt未経験チームがスキルを「知識ベース」として使う

こんにちは、かんだむです。僕が所属しているチームはデータレイク基盤の開発・運用を行っています。これまではTerraformでテーブル定義を管理し、TROCCOでETLパイプラインを運用してきました。今年度よりその構成からdbtへの移行を進めている真っ最中です。チームにはこれまでdbtを本番運用してきたエンジニアがおらず、いわば「手探り状態」でのスタートでした。

スキルは「実行可能なエージェント指示」であり「独立した技術リファレンス」でもある

dbt agent skillsのSKILL.mdは、Claude CodeなどのAIエージェントに作業手順を指示するためのファイルです。ただ、実際に中身を読んでみると、これが単なる「プロンプト」ではなく、人間が読んでも非常に有用な技術ドキュメントとして成立していることに気づきます。

例えばadding-dbt-unit-testのSKILL.mdは401行あります。この中には、ユニットテストを「いつ書くべきか」「いつ書くべきでないか」から始まり、具体的なYAMLの書き方、3種類のモックデータ形式（dict / csv / sql）の使い分け、5つのウェアハウス別データ型ガイド、インクリメンタルモデルやephemeralモデルといった特殊ケースへの対応方法までが網羅されています。

これだけの情報が公式によって構造化された状態で提供されるのは、新規の技術スタックを導入する上でとてもありがたいことです！

「何をテストすべきか」の基準が明白で嬉しい

dbtに移行するにあたって、最初に悩んだのがモデルのテストについてです。今までのパイプラインはBigQueryでクエリをシンプルに実行するだけのもので、ほとんどテストは書けていませんでした。dbtはテストの仕組みを標準で備えているため、ぜひテストをバンバン書いていきたいところですが、では何にどのようなテストを行って、何をテストしなくていいのでしょうか？

adding-dbt-unit-testのSKILL.mdは、この問いに非常に明快な答えを用意していました。

ユニットテストを書くべきケースとして挙げられているのは：

正規表現や日付計算を含むロジック
ウィンドウ関数
複数条件のcase when文
複雑なJOIN（自己結合や非自明な結合条件）
バグ報告があったロジック
本番データではまだ発生していないエッジケース

一方で、書くべきでないケースも明示されています：

Built-in functions that are tested extensively by the warehouse provider. If an unexpected issue arises, it's more likely a result of issues in the underlying data rather than the function itself.

つまり、min()やcount()のようなSQL標準関数は、ウェアハウスベンダーが既に徹底的にテストしているので、こちらで重複してテストする必要はない —— と明確に線引きされているのです。

この「やらなくていいこと」については、まあそれはそうだよなという感じですが、書くべきケースをきちんと提示し、それをもとにエージェントがある程度いい感じにやって見せてくれるというのは、新規採用の技術スタックでやっていくにあたって大変心強く感じました。

テスト設計の「型」としてのModel-Inputs-Outputs

SKILL.mdが提示するユニットテストの基本構造は、Model-Inputs-Outputsの3点セットです。

Model: テスト対象のモデル
Given (Inputs): モック化されたupstreamの入力データ
Expect (Output): その入力に対して期待される出力

このパラダイム自体はソフトウェアテストでは古典的ですが、dbtのYAMLで具体的にどう表現するか例示してくれていて嬉しいですね。SKILL.mdにはミニマムな例から実践的な複数inputの例まで掲載されており、テンプレートとしてそのまま流用できます。

1unit_tests:
2  - name: test_order_items_count_drink_items_with_zero_drinks
3    model: order_items_summary
4    given:
5      - input: ref('order_items')
6        rows:
7          - { order_id: 76, order_item_id: 3, is_drink_item: false }
8      - input: ref('stg_orders')
9        rows:
10          - { order_id: 76 }
11    expect:
12      rows:
13        - { order_id: 76, count_drink_items: 0 }

特筆すべきは、モックデータの形式がdict（デフォルト）/ csv / sqlの3種類から選べ、それぞれの使い分け基準が明示されている点です。基本的にはdictで十分だが、ephemeralモデルに依存する場合はsql形式が必須、外部フィクスチャファイルを使いたい場合はcsv形式 —— といった判断基準がテーブルで整理されています。「sql形式は全カラムを指定する必要があるが、dictとcsvは必要なカラムだけでよい」といったトレードオフも明記されており、実際に手を動かすときに躓きそうなポイントが先回りでカバーされています。