お知らせ16分で読めます

potato-skill：Claude Code、Codex、Cursor でアノテーション研究を構築する

potato-skill はコーディングエージェントに Potato の参考資料 28 件を渡し、アノテーション研究の設計、インターフェースの構築、そして正しく描画されるかの確認までを行わせます。

Potato Team2026年9月12日

potato-skill は、アノテーション研究の平易な説明を、そのまま動く Potato タスクに変えます。参考資料 28 件と補助スクリプト 9 件を同梱し、設定を書く前の設計上の判断、アノテーターが実際に見るインターフェース、そして検証は通るのに動かないタスクを捕まえるチェックまでを扱います。Claude Code、Codex、Cursor にインストールでき、GPL-3.0-or-later で公開されています。

スキルのインストール

Claude Code では、プラグインマーケットプレイスから 2 つのコマンドでインストールします。

text

/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potato

Codex と Cursor では skills CLI を使います。作業中のプロジェクトにスキルをコピーします。

bash

npx skills add davidjurgens/potato-skill --agent codex cursor

Potato 本体は、エージェントがコマンドを実行する場所にインストールしておく必要があります。9 件の補助スクリプトが Potato のレジストリをインポートし、potato コマンドを呼び出すためです。

bash

pip install potato-annotation

Codex や Cursor へのインストールに含まれるもの

skills CLI は .agents/skills/potato-skill/ に SKILL.md、28 件の参考資料すべて、9 件のスクリプトすべてを書き出します。Codex や Cursor のプロジェクトにも、Claude Code へのインストールと同じ材料が入るということです。AGENTS.md と .cursor/rules には手を加えません。そのディレクトリに置かれたスキルを各ツールがどう見つけるかは、ツール側に委ねられています。

リポジトリのルートには AGENTS.md も置いてあり、Codex と Cursor はインストール手順なしでファイル名から読み取ります。このファイルは参考資料全体のおよそ 79,000 語に対する短い要約で、完全にインストールしたときにだけディスクに置かれる参考資料やスクリプトを指し示します。引き渡し前のチェックの流れと実際に効く規則をエージェントに持たせたいときはこれを、その背後にある参考資料まで必要なときは skills CLI を使ってください。

スキルが確認せずに決めるデフォルト

間違っても直すのが安く済むことはその場で決め、間違いが高くつくこと、取り返しがつかないこと、エージェントが決めるべきでないことは研究者に返します。キーボードショートカットの変更にコストはありませんが、アノテーションの単位を取り違えて 5,000 件をやり直せば、研究の予算がそれで消えます。スキルが取るデフォルトは次のとおりで、タスクを引き渡すときにはいずれも前提として明示されます。

判断	デフォルト
尺度の段階数	数を指定しない限り 5 段階で、全段階にラベルを付ける
キーボードショートカット	ラベルが 9 個以下の質問すべてに設定する
質問の順序	振り分けとなる質問を先頭に、後続の質問は `display_logic` の裏に置く
項目の順序	ランダム。`random_seed` は固定する
必須項目	すべて必須。加えて `require_fully_annotated: true`
指示ページ	説明から書き起こした草案。草案であると明記する

研究者に返す判断

5 つの判断は 1 通のメッセージにまとめて研究者へ返されます。いずれにも案が添えてあるので、一言で承認できます。

アノテーションの単位。データからは決まらない場合です。段落単位のファイルなのに問いが本当は文についてのものであれば、そこは研究の分岐点で、どちらを選んでもやり直しになりえます。
1 項目あたりのアノテーター数。一致度を報告する予定がある場合です。3 人は 1 人の 3 倍かかるので、スキルは予算を勝手に使わず、理由を添えて人数を提案します。
同意文の文面。説明の内容から草案を作り、その草案は倫理審査委員会が承認した文面に差し替える必要があることをはっきり伝えます。
難しい事例の行き場がないラベル集合。「不明」も「該当なし」もない 3 つのラベルは、たいてい見落としです。アノテーターは本当に曖昧な項目をどこか適当な場所に入れてしまい、後段の処理からはそれが起きたことすら見えません。スキルは、行き場がないと判断した項目を名指しします。
ユーザー名、顔、位置情報をアノテーターに見せるものすべて。

これらが構築を止めることはありません。スキルは前提を明示してタスクを構築し、動作を確認したうえで、すでにクリックして試せるものと一緒に質問を出します。

引き渡し前のチェック

設定が検証を通ってわかるのはサーバーが起動することだけで、人がその作業をこなせるかどうかは何もわかりません。そこでスキルは、タスクを実際に描画して目で見るようエージェントに指示します。

bash

potato validate config.yaml --strict
potato preview config.yaml --screenshot shot-01.png

--strict を付けると、認識できない設定キーが警告ではなくエラーになります。付けなければタイプミスはそのまま受け入れられて無視され、有効にしたつもりの機能はオフのままです。読む分には正しいのに何も起きない設定は、たいていこれが原因です。

--screenshot は実際の Potato サーバーを起動し、ヘッドレスの Playwright で操作しながら、コンソールエラー、捕捉されなかったページ例外、400 以上の HTTP レスポンスを記録します。3 つのリストがすべて空のときだけ終了コード 0 になります。アノテーションインターフェースの大部分は HTML が届いた後に JavaScript が組み立てるので、この手順は検証では捕まえられないものを捕まえます。典型は表示されないラジオボタンで、ラベルの文字だけは描画されるため、ひと目見た限りでは質問は正しく見えます。

この 2 つのコマンドを回す流れは、自動化ではなく手引きです。参考資料はエージェントに、1 周につき変更は 1 つだけにすること、描画結果は毎回新しいファイル名で保存して 2 枚を並べれば変更の効果がわかるようにすること、独自レイアウトなら 3〜4 周かかると見込むことを指示します。さらに、display_logic の裏にあるものは最初の描画には現れず、現れないこと自体は何の証拠にもならないので、条件をコメントアウトして描画し、元に戻すようにも指示しています。

9 件の補助スクリプトのうち 3 件は、判断ではなく測定で済む部分を自動化します。check_ui.py は 1280x900 で実際のレイアウトを測り、画面外に出ているスキームや Next ボタン、中身が空のメディアウィジェット、重複したショートカットを報告します。boot_and_check.py はサーバーを起動し、設定されているのに何も読み込まれていない機能を報告します。トレーニングラウンドが訓練項目を 1 件も読み込んでいない場合などです。walk_task.py は動作中のタスクをアノテーターと同じようにたどり、どこで止まるかを報告します。

アノテーター開始後の、安全な変更と危険な変更

アノテーション研究で起きる問題の多くは、アノテーターが作業を始めた後に起きます。しかも重大な失敗ほどエラーメッセージを出しません。スキルはそのうち 2 つを扱います。

いちばん厄介なのは、研究の途中で質問の名前を変えることです。エラーは出ず、3 つの画面が 3 つの別々のことを報告します。管理画面の概要は研究が 100% 完了したと表示し、一致度レポートはそのスキームの項目数を 0 と表示し、CSV エクスポートには古い列名が入ります。エクスポートは設定ではなく保存済みの内容に従うからです。安全網は起動ログの WARNING 1 行だけです。質問の追加にも、同じ問題の目立たない版があります。Potato は完了状況を項目単位でのみ追跡し、質問単位では追跡しないため、後から追加した質問は、すでにコーパスを終えた人には届きません。

2 つ目は認証です。既定のバックエンドはアカウントをメモリ上に置くので、サーバーを止めるとアノテーターのログイン情報がすべて失われます。アノテーション自体はディスクに安全に残ります。アノテーターが戻ってきて同じユーザー名で登録し直せば自分の作業に再接続されるため、問題は表に出ません。誰かが違うユーザー名を打ち込み、別人としてコーパスを最初からやり直すまでは気づけないのです。authentication.user_config_path を設定すると、アカウントはソルト付きハッシュで書き出されます。Render や Hugging Face Spaces はコンテナを自動で再起動するので、いちばん忘れやすい場所ほどこの設定が効きます。

すでに進行中の研究には study_status.py があり、管理用のルートから進捗、アノテーターごとの作業速度、質問ごとの一致度、注意力チェックに落ちている人、放棄した項目を抱えたままの人を読み取ります。そのうえでスキルは、まだ安全な修正と、すでに対価を払った回答を壊してしまう修正を区別して示します。

Potato の MCP サーバー

Potato には MCP サーバーが 2 つ付属していて、シェルを介さずに同じ答えをエージェントへ返します。potato mcp serve --root . は、CLI と同じレジストリを読む作成用ツールを 12 個公開します。描画したページを画像として返す render_task_screenshot もその 1 つです。potato mcp connect は動作中の研究に橋渡しをし、状態、進捗、アノテーター、一致度、割り当て、エクスポートをカバーするライブツールを 12 個追加します。この橋渡しには、公開するツールを列挙した mcp ブロックを設定に書くことと、potato mcp issue-token で発行したトークンが必要です。

手書きのラベル付けツールとその代償

数百件の項目にラベルを付けるとき、よく取られる方法は、コーディングエージェントに簡単なラベル付けツールを書かせることです。項目を 1 件ずつ表示し、回答を CSV に追記していく Streamlit や Flask のページなどです。1 人が午後の数時間分のデータに一度ラベルを付けるだけなら、それは妥当な作りです。代償が出てくるのは、研究にアノテーターごとのログイン、1 項目あたり 3 人のアノテーターと各項目を適切な人へ振り分ける仕組み、トレーニングラウンドと注意力チェック、一致度の統計、Prolific の完了コード、次のスクリプトが期待する形式でのエクスポート、あるいは翌月に同じように動く 2 つ目の研究が必要になったときです。どれも、1 つの研究のために作られたツールの中で誰かが書き、テストし、デバッグする機能であり、Potato にはすでにそのすべてがあります。

研究が終わった後に何が残るかも違います。手書きのラベル付けツールは、たいてい 1 つのリポジトリの 1 つのデータセットに結びついています。Potato のタスクは設定とデータを収めたフォルダで、Potato さえあれば誰でも起動できます。ショーケースにはそうしたタスクが 400 以上あり、その多くは公開論文から取られています。find_design.py はその中から、説明した内容に近い設計を検索します。

スキルが組み立てる研究

扱える範囲は次の 5 例でわかります。いずれも短い説明から始まり、実行できるタスクで終わります。

クラウドワーカーによるスタンスのラベル付け。1 投稿につき 3 人のアノテーター、トレーニングラウンド、注意力チェック、Prolific の完了コード、そしてラベルが揃った後の一致度。クラウドソーシングのスタディの実施とアノテーター間一致度の測定を参照してください。
2 つのチャットボット応答の比較。選好尺度と自由記述の理由欄を備えた並列レイアウト。ペアワイズモデル比較と RLHF 選好データを参照してください。
エージェントのトレースで失敗したステップをマークする。トレースは 1 ステップずつ表示され、タスクはアノテーターがマークしたステップとその説明を記録します。エージェント軌跡のアノテーションを参照してください。
CVAT プロジェクトの引き継ぎ。potato import は 20 形式を読めるので、既存のボックスはラベルごと取り込まれ、研究の結果は COCO として書き出されます。バウンディングボックスの一致度の測定を参照してください。
2 人のコーダーとコードブック。コードブックがそのままコーディングのインターフェースになり、2 人のコーダーの両方にすべての回答が割り当てられ、裁定ステップが不一致を処理します。裁定と不一致を参照してください。

Potato のレジストリに対するテスト

もっともらしいのに間違っている識別子は、ドキュメントがないことより悪い結果になります。エージェントがそれを使ってしまうからです。そこで 28 件の参考資料のうち 3 件は Potato 自身のレジストリから生成され、サーバーが実際に適用する内容からずれないようにしてあります。61 種類のアノテーション形式すべて（それぞれ実プロジェクトから取った実例付き）、文書化されたトップレベルの設定キー、文書化されたサブキーです。

CI はスキルの中核ファイルを対象に、そこで名前が挙がるアノテーション形式、表示形式、設定キー、演算子、ストラテジー名、コマンドのすべてが Potato に存在することを確認します。YAML のサンプルはどれも動く設定に組み込まれて Potato 本来のバリデーターにかけられ、実例では実際のサーバーが起動して、そこで有効にした機能はいずれもログに 0 でない件数を報告しなければなりません。

参考資料は davidjurgens.github.io/potato-skill で公開されているので、インストールする前に、スキルがエージェントに何を伝えるのかを読めます。Anthropic は、どのスキルについても事前に内容を確認することを推奨しています。

よくある質問

ここでは、potato-skill と手作りのラベル付けツールのどちらを選ぶか、引き渡し前にスキルが何をチェックするか、スキルが構築したインターフェースをどう変更するかを取り上げます。

コーディングエージェントには独自のアノテーションツールを作らせるべきですか、それとも既存のツールを使わせるべきですか？

独自のツールを作るのは、1 人が数百件の項目に一度だけラベルを付ける場合に限られます。項目を 1 件ずつ表示し、回答を CSV に追記していく Streamlit や Flask のページがあれば、その用途には足ります。研究に 1 項目あたり複数のアノテーター、トレーニングラウンド、注意力チェック、一致度の統計、Prolific の完了コードのいずれかが必要になると、そのそれぞれを 1 つの研究のために作られたツールの中で書いてテストしなければなりませんが、Potato にはすでにそのすべてがあります。potato-skill が Potato の上に構築されているのはそのためで、potato-skill が作るタスクは、Potato さえあれば誰でも再実行できるフォルダです。

potato-skill はタスクを引き渡す前に何を検証しますか？

potato-skill は、タスクを返す前にエージェントに 2 つの Potato コマンドを実行させ、さらに補助スクリプトのうち 3 件で、それらのコマンドでは捕まえられないものをチェックします。potato validate config.yaml --strict は、認識できない設定キーが 1 つでもあれば失敗します。potato preview config.yaml --screenshot はヘッドレスの Playwright で実際のサーバーを起動し、ページがコンソールエラーも、捕捉されなかった例外も、400 以上の HTTP レスポンスも出さなかったときだけ終了コード 0 を返します。check_ui.py は画面外に出ているアノテーションの質問や Next ボタンを報告し、boot_and_check.py は設定されているのに何も読み込まれていない機能を報告し、walk_task.py はタスクをアノテーターと同じようにたどって、どこで止まるかを報告します。

potato-skill が構築したインターフェースはカスタマイズできますか？

はい。タスクは通常の Potato の設定なので、レイアウトを手で編集することも、エージェントに変更を頼むこともできます。独自レイアウトの場合、potato-skill はエージェントに、1 周につき変更は 1 つだけにすること、描画結果は毎回新しいスクリーンショットファイルに保存して連続する描画を見比べれば変更の効果がわかるようにすること、3〜4 周かかると見込むことを指示します。display_logic の裏にあるものは最初の描画には現れないため、エージェントは条件をコメントアウトして描画し、元に戻します。

さらに読む

コーディングエージェントでクイックスタート。セットアップをより詳しく扱っています
GitHub 上の potato-skill。現在 v1.0.1
スキルの参考資料
ショーケース。研究に近い設計を探すために

参考文献

David Jurgens, Michael Chen, and Lina Iyer (2026). Potato 2.0: A Comprehensive Annotation Platform with AI-in-the-Loop Support. Proceedings of the 64th Annual Meeting of the Association for Computational Linguistics (Volume 3: System Demonstrations). https://aclanthology.org/2026.acl-demo.37/