Claude CodeにFiftyOneのスキルを入れ、画像データセットを検証する

FiftyOneのスキルを入れると、Claude Codeが画像データセットの重複検出や品質チェックを、FiftyOneの手順どおりに進められるようになります。FiftyOneはVoxel51が公開しているコンピュータビジョン向けのオープンソースのデータセット管理ツールで、スキルはその操作手順を書いた指示書です。

ただし、スキルだけでは何も動きません。実際にデータセットを読み書きするのは別に用意するFiftyOne MCPサーバーです。この記事では、両方を入れる手順と、重複検出のあとに待っている「サンプルの削除」を安全に扱う権限設定をまとめます。

FiftyOneのスキルとMCPサーバーの役割分担

FiftyOneのスキルは、SKILL.mdという指示書の集まりです。リポジトリのREADMEでは、データセットの取り込み、書き出し、重複検出、推論の実行、モデル評価、埋め込みの可視化、データセット全体のキュレーションなどが「スキル」として並んでいます。各スキルの表には「MCP」列があり、YesのものはFiftyOne MCPサーバーを必要とします。

役割は次のように分かれます。

MCPサーバー側のREADMEによると、ツールは45以上あり、データセット管理、App操作、演算子の実行、プラグイン管理、集計、サンプル操作、スキーマ操作などに分類されています。ツールにはリスクの区分も付いていて、LOWは読み取りやUI状態の変更で自動実行しても安全なもの、OPERATORはFiftyOneの演算子を包んでいて実行前に演算子側の重大度を確かめるべきものです。この区分は、後半の権限設計の根拠になります。

スキルの数が資料によって違う

導入前に知っておきたい点が1つあります。GitHubのリポジトリのREADMEには18行の表があり、取り込み、書き出し、重複検出、推論、モデル評価、埋め込み可視化、プラグイン開発、デザイン、コードスタイル、ノートブック作成、Issueの仕分け、キュレーション、トラブルシュート、プラグイン評価、モデル追加、Data Lensコネクタ生成、App操作の自動化、SDKガイダンスまでが並びます。一方、Claudeのマーケットプレイスのfiftyoneプラグインのページは「13の専門スキル」と説明しています。

両者の差は、プラグインの版やスキルの追加時期の違いによるものと考えられますが、ページ上に理由の記載はありません。入れたあとに実際に読み込まれているスキルを確かめる手順は、導入のあとで扱います。

導入手順: MCPサーバーを先に、スキルは後から

導入は3段階です。MCPサーバーを入れてClaude Codeに登録し、スキルを入れ、最後にスキルが見えているか確かめます。

MCPサーバーを入れて登録する

サーバーはPyPIのパッケージです。登録はClaude Code向けにREADMEが推奨している書き方に従います。

pip install fiftyone-mcp-server
claude mcp add fiftyone -- fiftyone-mcp

ここで注意したいのは、fiftyone-mcpコマンドが見つかるPython環境です。READMEは、仮想環境やcondaに入れた場合は、同じ環境を有効にするか実行ファイルをフルパスで指定するよう警告しています。環境を有効にしないままClaude Codeを起動すると、MCPサーバーが立ち上がらず、ツールが並びません。

スキルを入れる

READMEのClaude Code向けの手順は、マーケットプレイスの登録とスキル単位のインストールです。

/plugin marketplace add voxel51/fiftyone-skills
/plugin install fiftyone-find-duplicates@fiftyone-skills

スキルは1つずつ選んで入れます。重複検出だけを使うならfiftyone-find-duplicatesで足ります。データセット全体の点検まで任せるなら、キュレーション用のスキル(fiftyone-dataset-curation)も入れます。

Claudeのマーケットプレイスのfiftyoneページには、プラグインをまとめて入れる「Install in Claude Code」ボタンがあります。このボタンは、Claude Codeのドキュメントによるとclaude plugin install <name>@claude-plugins-officialの形のコマンドをコピーします。ボタンが貼るコマンドをそのまま使うのが確実です。入れたあとの反映は、新しいセッションを開くか、/reload-pluginsで行います。プラグインがコンテキストをどれだけ使うかは、claude plugin detailsでの測り方で数値にできます。

読み込まれたか確かめる

セッション内で/mcpを開き、fiftyoneが接続済みであることを見ます。スキルはClaudeに「使えるFiftyOneのスキルを列挙して」と頼んで名前を確かめます。ここで見えたスキルの数が、先ほどの「13か、READMEの表の数か」の答えになります。見えないスキルを前提にした依頼は、Claudeが手順書なしで進めることになるので避けます。

重複検出の流れ: スキルが決めている順序

重複検出のスキルは、手順を8ステップで定めています。Claudeに「データセットmy-datasetの重複画像を探して」と頼んだときに従う順序は、スキルの記載によると次のとおりです。

スキルは、launch_appのあとに5〜10秒待ってから演算子を実行するよう定めています。ブレイン演算子はAppのエグゼキューターを経由するためです。

しきい値の目安

find_near_duplicatesのしきい値は距離で指定し、小さいほど似ています。スキルの目安は次のとおりです。

この演算子は、サンプルにnear_dup_idというフィールドを付け、同じ値を持つサンプルが互いの重複です。あわせてnear duplicatesとrepresentatives of near duplicatesという2つの保存済みビューが作られます。削除の前にset_view(exists=["near_dup_id"])で重複の候補だけを表示して、Appで目視できます。

完全に同一のファイルだけを消したいなら、類似度を計算する必要はありません。スキルにはfind_exact_duplicatesとdeduplicate_exact_duplicatesの組が用意されています。まず完全一致を片付けてから近い重複に進むと、埋め込みの計算量を減らせます。

処理時間の目安

類似度の計算は画像の枚数に比例します。スキルの目安は、1,000枚で1〜2分、1万枚で10〜15分、10万枚で1〜2時間です。遅いときは軽いモデルmobilenet-v2-imagenet-torchを使い、GPUがあれば使います。

削除を伴う操作を確認に回す権限設計

重複検出の最後の2ステップは、データセットからサンプルを消す操作です。スキルの表でも、deduplicate_near_duplicatesは「重複を削除して代表を残す」、deduplicate_exact_duplicatesは「完全な重複を削除する」と説明されています。

ここで権限の組み立てに癖が出ます。スキルは削除も含めて、execute_operatorというツールにoperator_uriを渡す形で呼びます。つまり、ツール名の上では、読み取り専用のcompute_uniquenessも削除するdeduplicate_near_duplicatesも同じexecute_operatorです。

Claude Codeの権限ルールでは、MCPツールのルールに括弧で引数条件を付ける書き方はできません。mcp__で始まる括弧付きのルールは、設定ファイルの読み込み時に読み飛ばされます。引数の中身で出し分けられない以上、execute_operatorは一律に確認へ回すのが安全です。権限は「deny、ask、allow」の順に評価され、最初に当たったものが結果を決めます。次のように書きます。引数で出し分けるルールの書き方はAgent(model:opus)の例にあり、組み込みツール向けです。

{
  "permissions": {
    "allow": [
      "mcp__fiftyone__list_datasets",
      "mcp__fiftyone__dataset_summary",
      "mcp__fiftyone__get_field_schema",
      "mcp__fiftyone__set_context",
      "mcp__fiftyone__set_view",
      "mcp__fiftyone__clear_view",
      "mcp__fiftyone__count_values",
      "mcp__fiftyone__bounds"
    ],
    "ask": [
      "mcp__fiftyone__execute_operator",
      "mcp__fiftyone__tag_samples",
      "mcp__fiftyone__untag_samples"
    ]
  }
}

サーバー名はclaude mcp addで付けたfiftyoneに合わせ、mcp__fiftyone__<ツール名>の形で書きます。ツール名はスキルの記載に従っています。実際の名前は、/mcpでツール一覧を開いて確かめてから書き写してください。名前が違うルールは何も効きません。

allowの側でmcp__fiftyone__*とまとめて許可すると、askが優先されるのでexecute_operatorは確認に回ります。ただ、ツールを個別に並べたほうが、新しいツールが追加されたときに意図せず許可される事態を避けられます。権限ルールの全体像はClaude Codeのffmpegの権限設計でも、読み取りは許可し、書き込みは確認に回す同じ考え方で説明しています。

CLAUDE.mdに書く運用ルール

権限は関所を作るだけで、Claudeの進め方までは決めません。削除の前にすることは、プロジェクトのCLAUDE.mdに書いておきます。

## FiftyOne(データセット検証)
- 変更を伴う操作(deduplicate_*、タグ付け、フィールド追加)の前に、
  対象の枚数と代表サンプルをAppで見せて承認を取る
- 削除の前に、対象ビューを `view.clone(name="<dataset>_backup")` で複製する案を出す
- 重複のしきい値は0.3から始め、結果の枚数を報告してから変える
- フィールド名は決め打ちせず、get_field_schema の結果から取る

1行目の考え方は、スキル自身の指示と同じ向きです。キュレーション用のスキルには「タグ付け、フィールド追加、削除の前に、結果をユーザーに見せて確認を取る」という指示があり、フィールド名を決め打ちせずスキーマから読む指示もあります。CLAUDE.mdに同じことを書いておくと、スキルが読み込まれていない場面でも同じ運用になります。

複製の案は、スキルの「保存と複製」の節にあるview.cloneの記述を借りたものです。複製したビューが永続化されるかなど細部はFiftyOneのドキュメントで確かめてから使ってください。

データセット全体の検証: キュレーションのスキル

重複だけでなく、データセット全体の品質を点検するならfiftyone-dataset-curationを使います。このスキルは、実行前に計画を提示することを義務にしています。

計画のフェーズは、スキーマの確認、品質監査、近い重複の検出、クラス分布の不均衡分析、埋め込みの探索、アノテーションの監査、きれいな部分集合と分割の作成、データへの質問の8つです。予測のフィールドが無いデータセットでは、アノテーション監査のフェーズをスキップし、先に推論のスキルを実行するよう案内します。

品質監査は既存のプラグインに任せる

品質監査では、メタデータの計算で破損ファイルを見つけ、解像度、ファイルサイズ、アスペクト比の分布を集計します。ぼやけや明るさの問題の検出は、自作のコードではなくjacobmarks/image-quality-issuesのプラグインを使うとスキルが定めています。プラグインの名前は、list_pluginsの出力から正確な名前を取って使うよう書かれていて、記憶にある名前で呼ばないための指示です。

最後に、品質フィルターを組み合わせたclean_<データセット名>のビューを作り、除外した枚数と残った枚数を報告します。学習用の分割にはrandom_splitを使う案がスキルに載っていて、FiftyOneのSDKを読む手順として案内されます。

つまずきやすい点

スキルのトラブルシュートの節から、実際に出会いやすいものを拾います。

missing_dependencyの応答にはmissing_packageとinstall_commandが入り、スキルはそのコマンドの実行を提案するよう定めています。ここでもインストール先は、MCPサーバーが動いているPython環境です。別の環境に入れても解決しません。

No executor availableが出る演算子にはfind_near_duplicatesとdeduplicate_near_duplicatesが含まれます。これは、ターミナルからのやり取りだけでは完結しない場合があるという意味で、重複検出の最後の確認は人がAppで行う前提と考えてください。

まとめ

FiftyOneのスキルは手順書、MCPサーバーは実行手段で、両方がそろって初めて動きます。導入そのものは数コマンドで済みますが、手間をかけるべきは権限です。deduplicate_*の削除もexecute_operatorの呼び出しなので、ツール名では見分けられず、一律に確認へ回す設計になります。読み取りは許可、実行と書き込みは確認、削除前の複製と目視はCLAUDE.mdに書く。この3層を先に決めておけば、数万枚のデータセットでも検証をClaudeに渡せます。