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 和 SONA 集成，以及导出为下游工具可读的格式。

前提条件

智能体在哪里运行命令，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，因此你可以在安装之前读到这个技能会对智能体说些什么。

后续步骤