potato-skill：コーディングエージェントでクイックスタート

Potato のプロジェクトを始める方法は二つあります。クイックスタートのように自分でタスクを書くか、研究の内容をコーディングエージェントに説明して potato-skill に設計と構築を任せるかです。 このページでは二つ目の方法を説明します。行き着く先はどちらも同じで、実行・変更・共有ができる Potato のアノテーションタスクです。

スキルが決めること

potato-skill はエージェントスキルです。リクエストに必要になったときにコーディングエージェントが読み込む、指示書と補助スクリプトのパッケージで、参考資料 28 件と補助スクリプト 9 件を同梱しています。構築だけでなく研究の設計も扱います。

• アノテーターに何を、どの尺度で尋ねるか
• 各項目に何人のアノテーターが必要か
• アノテーターをどう訓練し、その作業をどう確認するか
• アノテーターが目にするインターフェース
• 次の工程が必要とする形式で結果をエクスポートすること

このうちいくつかは自分で決め、いくつかは研究者に返します。基準は、間違っても直すのが安く済むならその場で決め、間違いが高くつくとき、取り返しがつかないとき、エージェントが決めるべきでないときは返す、というものです。スキルが取るのは、全段階にラベルを付けた 5 段階尺度、ラベルが 9 個以下の質問へのキーボードショートカット、random_seed を固定したランダムな項目順序、そして全質問を必須にすることです。研究者に尋ねるのは、アノテーションの単位、一致度を報告する予定がある場合の 1 項目あたりのアノテーター数、同意文の文面、そして「不明」の選択肢がないラベル集合です。

構築されたタスクは Potato 上で動くので、Potato がすでに備えているものをそのまま使えます。アノテーターごとのログイン、1 項目あたり複数のアノテーター、一致度の統計、Prolific と MTurk との連携、そして後続のツールが読める形式へのエクスポートです。

必要なもの

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

pip install potato-annotation

コーディングエージェントも必要です。このスキルは Claude Code 向けに書かれており、Codex と Cursor にもインストールできます。

スキルのインストール

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

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

Codex と Cursor では、skills CLI が作業中のプロジェクトにインストールします。

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

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 を使ってください。

研究を説明する

何にラベルを付けるのか、誰がラベルを付けるのか、ラベルを何に使うのかを伝えてください。Potato のアノテーションタイプや設定形式を知っている必要はありません。リクエストはこの程度の短さで構いません。

ツイート 200 件に、5 段階の感情ラベルを 1 件あたり 3 人のアノテーターで付けたい。同意ページと注意力チェック 2 件も入れて。構築して起動して。

スキルは質問の文言、尺度、項目の割り当て方、アノテーターの確認方法を決めます。確認したい質問があっても、そこで作業を止めることはありません。前提を明示してタスクを構築し、動作を確認したうえで、すでにクリックして試せるものと一緒に質問を出します。

引き渡し前にエージェントが行うチェック

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

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

--strict を付けると、認識できない設定キーが警告ではなくエラーになります。付けなければ、機能を黙ってオフのままにしてしまうタイプミスがそのまま通ってしまいます。--screenshot は実際の Potato サーバーを起動し、ヘッドレスの Playwright で操作しながら、コンソールエラー、捕捉されなかったページ例外、400 以上の HTTP レスポンスを記録します。3 つのリストがすべて空のときだけ終了コード 0 になります。

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

誰かを招待する前に、ブラウザでタスクを開いて自分でいくつか項目にラベルを付けてください。

出来上がるタスク

Potato のタスクとは、タスクの設定、データ、説明文をまとめたプロジェクトフォルダーです。クイックスタートの内容はすべてこれに当てはまります。potato start config.yaml で起動し、手で編集し、アノテーターを追加し、ラベルをエクスポートできます。

結果が Potato のタスクフォルダーなので、他の人も使えます。同僚が新しいデータで同じ研究を実行することも、来年もう一度実行することも、それを使った論文と一緒に公開することもできます。ショーケースは、このように共有されたタスクを公開論文から集めたものです。

既存のデザインとアノテーション

• 公開されたデザイン。 スキルは、公開論文から取られた 440 件のアノテーションデザインのいずれかから始められます。ラベル集合、質問の文言、説明文も一緒に引き継ぎます。ショーケースで閲覧でき、find_design.py は説明した内容に近い設計をその中から検索します。
• 他のツールのアノテーション。 potato import は Labelbox、CVAT、COCO を含む 20 形式を読めるので、途中まで進んだプロジェクトを Potato で続けられます。
• すでに実行中の研究。 study_status.py はアノテーターごとの進捗と質問ごとの一致度を報告し、スキルは研究の途中でも安全な修正と、収集済みのデータを壊してしまう修正とを区別して示します。

Potato の MCP サーバー

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

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

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

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

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

二つの方法の比較

二つの方法が違うのは出発点であって、行き着く先ではありません。

途中でいつでも方法を切り替えられます。自分で書いたタスクをエージェントに変更させることも、エージェントが構築したタスクを自分で編集することもできます。

よくある質問

以下の質問では、コーディングエージェントで potato-skill を使えるようにする手順と、そのソースの置き場所を扱います。

コーディングエージェントで Potato を使うにはどうすればよいですか？

エージェントがコマンドを実行する場所に Potato と potato-skill をインストールし、普段の言葉でエージェントに研究を説明します。Potato は pip install potato-annotation でインストールします。スキルは、Claude Code では /plugin marketplace add davidjurgens/potato-skill に続けて /plugin install potato-skill@potato でインストールし、Codex や Cursor では npx skills add davidjurgens/potato-skill --agent codex cursor でインストールします。何にラベルを付けるのか、誰がラベルを付けるのか、ラベルを何に使うのかをエージェントに伝えてください。potato-skill はタスクを構築し、描画して動作することを確認したうえで、研究者の代わりに決めた事項の一覧を返します。

potato-skill は GitHub のどこにありますか？

potato-skill は github.com/davidjurgens/potato-skill にあり、GPL-3.0-or-later で公開されています。参考資料は davidjurgens.github.io/potato-skill で公開されているので、スキルがエージェントに何を指示するのかをインストール前に読めます。

次のステップ

• クイックスタート。タスクを手で書く場合
• 設定の基本
• Prolific と MTurk でのクラウドソーシング
• アノテーター間一致度の測定
• コーディングエージェントが確認できる設定
• GitHub 上の potato-skill