Skip to content

potato-skill：使用程式設計智慧體快速入門

把需要標註的內容描述給 Claude Code、Codex 或 Cursor，potato-skill 就會設計這項標註研究，用 Potato 構建出來，並檢查頁面是否真的渲染。它自己定下量表點數和條目順序，把標註單位和每個條目的標註者人數交回給你確認。

開始一個 Potato 項目有兩種方式。你可以按快速入門自己編寫任務，也可以把研究描述給程式設計智慧體，讓 potato-skill 來設計和構建。 本頁介紹第二種。兩條路的終點相同，都是一個可以執行、修改和分享的 Potato 標註任務。

技能決定什麼

potato-skill 是一個智慧體技能，也就是一組說明和輔助指令碼，程式設計智慧體在請求需要時載入它們。它附帶 28 份參考檔案和九個輔助指令碼，既覆蓋研究的設計，也覆蓋構建：

  • 向標註者提什麼問題，用什麼量表
  • 每個條目需要幾名標註者
  • 如何培訓標註者並檢查他們的工作
  • 標註者看到的介面
  • 以下一步所需的格式匯出結果

其中一部分它自己定下來，另一部分交還給你。它遵循的規則是，一個決定如果做錯了改起來很便宜，就在本地定；如果做錯了代價高昂、不可逆，或者本來就不該由智慧體來定，就交回給你。它自己採用 5 點量表且每個點都帶標籤、在標籤數不超過九個的問題上啟用鍵盤快捷鍵、條目順序隨機並固定 random_seed，以及所有問題必填。它會來問你的是標註單位、需要報告一致性時每個條目的標註者人數、知情同意的措辭，以及任何沒有"不確定"選項的標籤集。

它構建的任務執行在 Potato 上，因此自帶 Potato 已有的能力：每位標註者單獨登入、每個條目由多名標註者標註、一致性統計、Prolific 和 MTurk 整合，以及匯出為下游工具可讀的格式。

前提條件

智慧體在哪裡執行命令，Potato 就必須裝在哪裡，因為技能的輔助指令碼會匯入 Potato 的登錄檔並呼叫 potato 命令：

bash
pip install potato-annotation

你還需要一個程式設計智慧體。這個技能是為 Claude Code 編寫的，也可以安裝到 Codex 和 Cursor 中。

安裝這個技能

在 Claude Code 中，從外掛市場安裝它：

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

Codex 或 Cursor 的安裝包含什麼

skills CLI 會寫出 .agents/skills/potato-skill/，其中包含 SKILL.md、全部 28 份參考檔案和全部九個指令碼，所以 Codex 或 Cursor 項目拿到的材料與 Claude Code 安裝拿到的相同。它不會改動 AGENTS.md 和 .cursor/rules，而各個工具如何發現該目錄下的技能，由工具自己決定。

倉庫根目錄還帶有一個 AGENTS.md，Codex 和 Cursor 按檔名讀取它，不需要任何安裝步驟。相對於參考檔案合計約 79,000 詞的內容，這個檔案是一份簡短的摘要，而且它指向的參考檔案和指令碼只有完整安裝才會落到磁碟上。如果你希望智慧體拿到"交付前先檢查"的迴圈和那些真正起作用的規則，就用它；如果你還想要這些規則背後的參考材料，就用 skills CLI。

描述研究

說明需要標註什麼、由誰來標註，以及標註結果用於何處。你不需要了解 Potato 的標註類型，也不需要了解它的配置格式。一條請求可以短到這樣：

我想讓三名標註者分別對 200 條推文按 5 點量表標註情感傾向，並加上一個知情同意頁面和兩道注意力檢查題。構建好並啟動它。

技能會確定問題措辭、量表、條目如何分配，以及如何檢查標註者。它不會因為還有問題要確認就停下來等你。它會說明自己的假設，構建任務，驗證它，並在你已經可以點開試用的東西旁邊提出這些問題。

智慧體交付前執行的檢查

配置通過校驗，說明伺服器能啟動，但完全說明不了人能不能完成這項工作。技能要求智慧體把任務渲染出來，然後去看它：

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

--strict 把無法識別的配置鍵從警告變成失敗，這能抓住原本會讓某項功能悄悄關閉的拼寫錯誤。--screenshot 會啟動一個真實的 Potato 伺服器，用無頭 Playwright 驅動它，記錄控制台錯誤、未捕獲的頁面異常，以及 400 及以上的 HTTP 響應。只有這三份列表都為空時它才以 0 退出。

九個輔助腳本里有三個，把可以測量而非需要判斷的部分自動化了。check_ui.py 測量即時佈局，報告落到首屏以下的標註方案或"下一個"按鈕、空的媒體控制元件，以及重複的快捷鍵。boot_and_check.py 報告每一項配置了卻什麼都沒載入的功能。walk_task.py 像標註者那樣走一遍正在執行的任務，並報告它停在哪裡。

在邀請其他人之前，先自己在瀏覽器裡開啟任務，標幾個條目。

它產出的任務

一個 Potato 任務就是一個項目資料夾，裡面放著任務的配置、資料和說明。快速入門裡的所有內容都適用於它。你用 potato start config.yaml 啟動它，手動編輯它，新增標註者，並匯出標籤。

因為結果是一個 Potato 任務資料夾，其他人也能用。同事可以在新資料上運行同一項研究，你明年可以再跑一次，也可以隨用到它的論文一起釋出。展示區收錄的就是以這種方式分享、取自已發表論文的任務。

已有的設計和標註

  • 已發表的設計。 技能可以從 440 個取自已發表論文的標註設計之一開始，沿用它們的標籤集、問題措辭和說明。你可以在展示區瀏覽它們，find_design.py 會在其中搜索與你描述接近的設計。
  • 其他工具的標註。 potato import 能讀 20 種格式，包括 Labelbox、CVAT 和 COCO，所以做到一半的項目可以在 Potato 中繼續。
  • 已經在執行的研究。 study_status.py 報告每位標註者的進度和每個問題的一致性，技能還會說明哪些修改在研究進行中是安全的，哪些會破壞已經收集到的資料。

Potato 的 MCP 伺服器

智慧體可以通過 MCP 而不是 shell 拿到同樣的答案。potato mcp serve --root . 暴露 12 個創作工具，它們讀取的登錄檔和 CLI 一樣，其中包括 render_task_screenshot，它把渲染好的頁面作為圖片返回。potato mcp connect 橋接一項正在執行的研究，再加上 12 個即時工具，涵蓋狀態、進度、標註者、一致性、任務分配和匯出。這個橋接需要配置裡有一個 mcp 塊來列出要暴露的工具，還需要一個由 potato mcp issue-token 簽發的令牌。

針對 Potato 登錄檔的測試

一個看著合理卻是錯的識別符號，比沒有文件更糟，因為智慧體真的會去用它。28 份參考檔案裡有三份是由 Potato 自己的登錄檔生成的，不會與伺服器實際執行的內容產生偏差：全部 61 種標註類型，每一種都配有從真實項目裡取來的完整示例；有文件記載的頂層配置鍵；以及有文件記載的子鍵。

CI 覆蓋這個技能的核心檔案，檢查其中提到的每一種標註類型、展示類型、配置鍵、運算子、策略名和命令在 Potato 中確實存在。每一段 YAML 示例都會被拼進一份可用的配置，交給 Potato 真正的驗證器執行，完整示例還會啟動一個真實的伺服器。

它的參考材料釋出在 davidjurgens.github.io/potato-skill，不裝任何東西就能讀。Anthropic 建議先審閱任何技能再安裝。

兩條路的對比

兩條路的區別在起點，不在終點：

自己編寫任務描述給程式設計智慧體
你的起點一份 YAML 配置一段平實語言的描述
適合學習 Potato、小型任務新研究、帶培訓和檢查的眾包研究、你沒用過的標註類型
你的終點一個 Potato 任務一個 Potato 任務

你隨時可以換一條路。智慧體可以修改你自己寫的任務，你也可以編輯智慧體構建的任務。

常見問題

下面的問題涉及如何在程式設計智慧體中配置 potato-skill，以及在哪裡找到它的原始碼。

如何配合程式設計智慧體使用 Potato？

在智慧體執行命令的地方安裝 Potato 和 potato-skill，然後用平實的語言向智慧體描述研究。pip install potato-annotation 用於安裝 Potato。在 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，因此你可以在安裝之前讀到這個技能會對智慧體說些什麼。

後續步驟