Claude CodeにMLflow Skillsを入れてエージェントのトレースを評価する
mlflow/skillsのスキル群をClaude Codeに入れ、計装、失敗トレースの原因調査、スコアラー設計、評価実行までを会話で進める手順です。スキル同士の役割分担と、評価結果が黙って消える落とし穴も扱います。
自作のエージェントを評価するとき、手が止まるのは「何を測るか」と「どの順で組むか」です。mlflow/skillsは、この段取りをスキルとしてClaude Codeに持たせるリポジトリです。「このトレースはなぜ失敗したか」「エージェントの精度を評価して」と頼むだけで、トレースの読み取りから評価の実行までを決まった手順で進めます。
この記事では、スキルの入れ方、10本を超えるスキルの役割分担、評価までの流れ、そして手順の中で結果が黙って消える落とし穴を順に説明します。
mlflow/skillsは何を足してくれるのか
mlflow/skillsは、MLflowのトレース(tracing)と評価(evaluation)の使い方を、コーディングエージェント向けのスキルにまとめたリポジトリです。ライセンスはApache-2.0で、Claude CodeのほかCursor、Codex CLI、Gemini CLI、OpenCodeなど、スキルに対応するエージェントで使えます。
READMEの例文は、そのまま依頼文の見本になります。
- 「Add tracing to my LangChain app」でコードに計装を入れる
- 「Why did this trace fail?」でスパンを読み、原因と修正案を出す
- 「Evaluate my agent's accuracy」でデータセット、スコアラー、評価実行までそろえる
- 「Show me token usage trends」で使用量の推移を集計する
動作要件はMLflow 3.8以上です。MLflow MCPサーバーなら3.5.1以上で動くので、手元のバージョンが3.5〜3.7ならMCP側を先に試す順になります。MCPとプラグインの違いはClaudeにMLflow MCPを繋いでトレース調査と評価ループを回すで扱っています。こちらはMCPのツールではなく、手順を書いたスキルに寄せた記事です。
スキルを入れる3つの方法
READMEには、導入の経路が3つ載っています。
# 1. スキルインストーラー
npx skills add mlflow/skills
# 2. ホームのスキルディレクトリへ直接コピー
git clone https://github.com/mlflow/skills.git mlflow-skills
cp -r mlflow-skills/* ~/.claude/skills/
# 3. プロジェクトに置いてチームで共有
cd your-project
git clone https://github.com/mlflow/skills.git .skills/mlflow3つ目は、サブモジュールとして追加する形(git submodule add)もREADMEに書かれています。
選び分けは、誰が使うかで決まります。自分の端末だけなら1か2、チーム全員に同じ手順を持たせたいなら3です。ただし3の.skills/mlflowはClaude Codeの標準の読み込み先ではありません。Claude Codeがスキルを自動で見つけるのは~/.claude/skills/と、プロジェクトの.claude/skills/などのディレクトリです。.skills/mlflowに置くなら、中身を.claude/skills/へ配置するか、シンボリックリンクを張る必要があります。スキルの置き場所と優先順位はClaude Codeのスキル入門にまとめています。
リポジトリには.claude-plugin/plugin.jsonもあり、プラグインとしても読み込めます。そこにはskillsの一覧とhooks/hooks.jsonへの参照、minClaudeCodeVersionとして2.0.0が書かれています。
10本のスキルは何がどう違うのか
READMEの表にあるスキルは10本です。tracing、evaluation、setupの3群に分かれます。
| 群 | スキル | 役割 |
|---|---|---|
| Tracing | スキルinstrumenting-with-mlflow-tracing | 役割PythonとTypeScriptのコードにトレースを組み込む |
| Tracing | スキルanalyze-mlflow-trace | 役割1本のトレースをスパン単位で読み、コードと突き合わせる |
| Tracing | スキルanalyze-mlflow-chat-session | 役割複数ターンの会話を復元し、どこで崩れたかを探す |
| Tracing | スキルretrieving-mlflow-traces | 役割ステータス、セッション、ユーザー、期間などでトレースを検索する |
| Tracing | スキルdebug-agent | 役割既存のトレースから失敗の原因を特定する |
| Evaluation | スキルagent-evaluation | 役割データセット作成からスコアラー選定、実行、結果分析まで |
| Evaluation | スキルbuild-a-scorer | 役割小さくて安いスコアラー群を、ユーザーと対話して設計する |
| Evaluation | スキルquerying-mlflow-metrics | 役割トークン使用量、レイテンシ、エラー率を集計する |
| Setup | スキルmlflow-onboarding | 役割用途(GenAIか従来のML)に合わせてMLflowの導入を案内する |
| Setup | スキルsearching-mlflow-docs | 役割llms.txtの索引を使ってMLflowのドキュメントを引く |
READMEの表に載らないスキルもあります。plugin.jsonのskillsには13個が並び、表にない3つは次のとおりです。
mlflow-agent: MLflow関連の依頼を受けて、他のスキルへ振り分ける窓口fix-agent-issue: 失敗の修正や新しいルールの導入を、テストを先に書く手順で進めるsagemaker-mlflow: 名前がplugin.jsonに載っているだけで、READMEに説明の節はありません
つまり、READMEだけを見て「10本」と数えると、窓口と修正の2本を見落とします。調べ物ではなく修正まで任せたいなら、fix-agent-issueの存在を知っておく価値があります。
窓口スキルは自分で作業をしない
mlflow-agentの指示文は、役割をはっきり絞っています。意図を読み、最大1回だけ確認の質問をして、該当スキルを呼ぶだけです。「自分で作業をしない」が明記されています。
「評価もトレースも」と頼むと、先に計装、次に評価の順で呼びます。すでに計装済みのデバッグ依頼は、計装のセットアップへ戻さないことも書かれています。さらに、このスキルはdisable-model-invocation: trueで、Claudeが自動で呼ぶ対象ではありません。使うなら/mlflow-agentのように自分で呼びます。この仕組みは、スキルの呼び出し主体を絞るフロントマターの標準機能です。
失敗したトレースの原因を調べる
調査の入口は、トレースIDを添えた依頼です。
Analyze trace tr-abc123 — why did it return the wrong answer?READMEは、この依頼でトレースの取得、アセスメント(品質のシグナル)の確認、スパンツリーの探索、コードとの突き合わせ、修正案の提示まで進むと説明しています。
別のスキルとしてdebug-agentが用意されており、こちらは診断に徹します。指示文には次の線引きがあります。
- 既存のトレースがあれば、それをそのまま使う。本番だけで起きる失敗を、手順のために再現しない
- 使えるトレースが無いときだけ、通常の入口から1回だけ再現する
- 報告は、観測した挙動、期待した挙動、トレース上の証拠、原因、確信度、最小の修正案
- 修正を頼まれていなければコードを編集しない。修正は
fix-agent-issueへ渡す
「原因を知りたいだけ」と「直してほしい」を分けて頼むと、勝手に編集される事故を避けられます。
analyze-mlflow-traceには、扱い方の注意があります。トレースは100KBを超えることがあるため、mlflow traces getの出力はパイプに流さず、ファイルへリダイレクトしてjqで読むよう指示されています。パイプで流すと出力が空になることがある、というのが理由です。
mlflow traces get --trace-id <ID> > /tmp/trace.json
jq '.info.state' /tmp/trace.json
jq '.data.spans | length' /tmp/trace.jsonスパンの入出力は、トップレベルのフィールドではなくattributesの中にJSON文字列として入っています。OpenTelemetryなど別のクライアントから来たトレースは属性名が異なることがあるので、空に見えたら生のattributesを確認します。
評価は「スコアラー設計」と「実行」に分かれている
評価の流れで見落としやすいのは、2つのスキルの境界です。agent-evaluationは評価の実行を持ち、スコアラーの設計はbuild-a-scorerの仕事です。指示文にも、この境界が明記されています。
評価を回す順番
- 1
エージェントの目的を3問で聞かれる
agent-evaluationは最初に、エージェントの目的、特に外せない2〜3点、すでに気づいている失敗の型を質問します。ここを飛ばさない指示です。 - 2
基準が曖昧なら build-a-scorer へ回る
回答が「良い答え」「正確であること」のように曖昧だと、スコアラー名を勝手に作らず、
build-a-scorerで基準を決めてから戻ります。 - 3
スコアラーを登録する
組み込みのスコアラー、
@scorerによるコード判定、make_judge()によるLLM判定を、実験に登録します。登録しないとmlflow scorers listに出ず、再利用もできません。 - 4
データセットを探してから作る
既存のデータセットを
list_datasets.pyで調べるのが先です。新規に作るときは、5問の動作確認用と、50〜100問以上の本番用の2段階です。 - 5
3問のドライランを挟む
全件を回す前に、3問で試します。ツールが壊れていないか、応答が空でないか、スコアがすべて0やNoneになっていないかを見ます。
- 6
全件を実行して分析する
mlflow.genai.evaluate()で実行し、結果のCSVをanalyze_results.pyでレポートにします。
このスキルは「MLflowのAPIを使う」ことを強く求めます。独自の評価フレームワークやevaluation/ディレクトリを作らず、mlflow.genai.datasets.create_dataset()、mlflow.genai.evaluate()などを使う指示です。理由として、データセット、スコアラー、トレース、結果がすべて実験に記録されるため、と書かれています。
コマンドはuv runで実行する前提です。MLflowのバージョン確認もuv run mlflow --versionの形になります。MLFLOW_TRACKING_URIとMLFLOW_EXPERIMENT_IDが両方設定済みなら、セットアップ手順を飛ばして計装から始める指示もあります。環境変数を先に渡しておくと、無駄な質問が減ります。
export MLFLOW_TRACKING_URI="http://localhost:5000"
export MLFLOW_EXPERIMENT_ID="<実験のID>"
claudeスコアラー設計の癖を知っておく
build-a-scorerは、いきなりコードを出しません。指示文には次の方針があります。
- 質問は最大3つまでにして、そのあと草案を見せる。ユーザーは草案を直すほうが答えやすい
- スコアラーは3〜5個が上限。1つ足すなら弱いものを1つ外す
- 1つのスコアラーは1つの基準だけを見る。「と」を含む基準は分ける
- 実装は、コードによる判定、組み込み、手書きのLLM判定の順で安いものを選ぶ
- ルール違反を見る層だけでなく、「ユーザーが目的を果たせたか」を見る層を必ず入れる
この順序は、費用に直結します。たとえば「特定の語句を言及したか」はコードで判定でき、LLM判定は曖昧な残りだけに回せます。手書きのLLM判定を選ぶときは、コード判定と組み込みのどちらを、なぜ採らなかったかを書く決まりです。
結果が黙って消える落とし穴
2つのスキルが繰り返し警告する落とし穴があります。LLM判定の戻り値を"pass"や"fail"にすると、エラーも警告も出ないまま、集計から除外されます。
落とし穴
pass / fail で返すと集計から消える
"pass"、"fail"、"correct"、"not_applicable"などの文字列は、集計時にNoneへ変換され、results.metricsに入りません。集計できるのは真偽値、数値、"yes"と"no"です。該当しない場合は、文字列ではなくFeedback(value=True, rationale="not applicable: ...")の形にし、詳細はrationaleへ書きます。
3問のドライランで「スコアがすべて0かNone」を止める条件にしているのは、この罠を早く拾うためです。全件を回してからレポートが空だと気づくより、先に3問で拾うほうが費用も時間も小さく済みます。
もう1つ、検索系の組み込みスコアラー(RetrievalGroundedness、RetrievalRelevance、RetrievalSufficiency)は、RETRIEVER型のスパンを必須とします。Web検索やDB検索をTOOL型で計装していると、これらは使えず、エラーになります。評価の前に、計装がどの型で入っているかを見直す理由になります。
プロンプトに応じてスキルを提案するフックを入れる
READMEには任意の機能として、UserPromptSubmitフックがあります。プロンプトに含まれる語から、使うべきスキルを提案します。hooks/mlflow-suggest-hook.pyの対応は、hooksのREADMEに表で載っています。
| プロンプトの語 | 提案されるスキル |
|---|---|
| trace、tracing、autolog、span、instrument | 提案されるスキルinstrumenting-with-mlflow-tracing |
| evaluat、scorer、judge、dataset | 提案されるスキルagent-evaluation |
| trace id、debug trace、why did | 提案されるスキルanalyze-mlflow-trace |
| debug my agent、agent failure | 提案されるスキルdebug-agent |
| search traces、find traces | 提案されるスキルretrieving-mlflow-traces |
| metrics、token usage、latency、cost | 提案されるスキルquerying-mlflow-metrics |
フックはプロンプトをJSONで標準入力から受け取り、キーワードが当たれば標準出力に提案を書きます。当たらなければ何も出さないので、MLflowと無関係な会話には影響しません。
READMEの設定例は、そのまま貼らない
READMEの設定例は、UserPromptSubmitの直下にtypeとcommandを置く形です。一方、Claude Codeのhooksドキュメントの設定例は、イベント名の下にmatcherを持つグループがあり、その中のhooks配列にフックを並べる形です。UserPromptSubmitはマッチャーに対応しないので省略できますが、hooks配列は残ります。ドキュメントの形に合わせると、次のようになります。
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "python3 ~/.claude/hooks/mlflow-suggest-hook.py"
}
]
}
]
}
}READMEの形で動かなければ、まずこの入れ子を疑います。
もう1つ、挙動の違いがあります。READMEは提案がユーザーの目に触れるように書いていますが、hooksのドキュメントでは、UserPromptSubmitの標準出力はClaudeが見て動けるコンテキストとして追加されます。ユーザー向けの通知ではなく、Claudeへの追加情報として届く、と読むほうが仕様に近い扱いです。
UserPromptSubmitは、実行時間の既定が30秒です。時間切れになると、出力は捨てられ、プロンプトだけがClaudeに届きます。キーワード照合だけの軽いスクリプトなので問題になりにくいものの、重い処理を足さない前提で使います。
使い分けの目安
| やりたいこと | 向く経路 | 理由 |
|---|---|---|
| トレースを検索して一覧で見たい | 向く経路MLflow MCPサーバー | 理由ツールとして生のトレースを引ける |
| 失敗の原因を、手順に沿って突き止めたい | 向く経路本記事のスキル(debug-agent) | 理由診断の線引きが指示文にある |
| 評価基準の設計から実行まで任せたい | 向く経路本記事のスキル(build-a-scorerとagent-evaluation) | 理由設計と実行を分けて進める |
| pytestの形式で評価を残したい | 向く経路DeepEvalプラグイン | 理由テストとして回せる |
| 実験のrunを比べたい | 向く経路MLflowの実験管理 | 理由学習・パラメータの比較向き |
トレース基盤をMLflow以外に置く場合は、Dash0プラグインのようにセッション自体をトレースする選択肢もあります。
導入の前に確かめておくこと
- MLflowのバージョン:
uv run mlflow --versionで3.8以上かを見る - スキル名の揺れ:
analyze-mlflow-traceのフォルダに入っているSKILL.mdのnameはanalyzing-mlflow-traceです。Claude Codeはフロントマターのnameがあればそれをコマンド名にするため、/で出る名前を実際に確かめてから呼びます。mlflow-agentの振り分け表とfix-agent-issueの本文で、呼ぶ名前がanalyze-mlflow-traceとanalyzing-mlflow-traceに分かれています - 評価の費用: 評価は1問ごとにエージェントとLLM判定を1回ずつ呼びます。指示文は、Sonnet級の判定モデルで1問あたり20〜45秒程度、Opus級で45〜90秒程度と見積もっています。件数が多いほど時間も費用も伸びます
- 判定モデルの指定: 判定モデルは
model=で明示する指示です。迷ったら中位のモデルから始め、人手のラベルと食い違うときだけ上げる流れが書かれています
まとめ
mlflow/skillsの価値は、個々のAPIよりも「順番」を持たせる点にあります。計装を先に、基準の設計を実行の前に、3問のドライランを全件の前に置く。この順番が指示文に書かれているので、頼む側はゴールだけ伝えれば済みます。
導入するなら、手元の失敗トレースを1本選び、debug-agentで原因だけ調べる使い方から始めると、コードを触られずに挙動を確かめられます。評価に進むときは、戻り値を"yes"と"no"か真偽値に揃えること。この1点を守るだけで、結果が消える事故の大半を避けられます。