potato-skill: соберите исследование с разметкой в Claude Code, Codex или Cursor

potato-skill превращает обычное описание исследования с разметкой в работающую задачу Potato. В нём 28 справочных файлов и девять вспомогательных скриптов, охватывающих решения по дизайну, которые принимаются до конфигурации, интерфейс, который видит разметчик, и проверки, которые ловят задачу, проходящую валидацию, но не работающую. Он ставится в Claude Code, Codex и Cursor и выпущен под GPL-3.0-or-later.

Установка навыка

Claude Code ставит его из маркетплейса плагинов, двумя командами:

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

Codex и Cursor ставят его через CLI skills, которая копирует навык в проект, где вы работаете:

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

Сам Potato должен быть установлен там, где агент выполняет команды, потому что девять вспомогательных скриптов импортируют его реестры и вызывают команду potato:

pip install potato-annotation

Что входит в установку для Codex или Cursor

CLI skills создаёт .agents/skills/potato-skill/ с SKILL.md, всеми 28 справочными файлами и всеми девятью скриптами, так что проект на Codex или Cursor получает тот же материал, что и установка в Claude Code. AGENTS.md и .cursor/rules она не трогает, а как именно каждый инструмент находит навык в этом каталоге — дело самого инструмента.

В корне репозитория лежит ещё и AGENTS.md, который Codex и Cursor читают по имени файла, без всякой установки. Этот файл — короткая сводка того, что в справочных материалах занимает примерно 79 000 слов, и он ссылается на справочные файлы и скрипты, которые попадают на диск только при полной установке. Берите его, когда хотите дать агенту цикл «проверь перед сдачей» и правила, которые действительно кусаются, и берите CLI skills, когда вам нужен стоящий за ними справочный материал.

Умолчания, которые навык выбирает не спрашивая

Решение принимается на месте, когда ошибку дёшево исправить, и возвращается вам, когда ошибка дорога, необратима или вообще не агенту её принимать. Поменять горячую клавишу не стоит ничего, а перезапустить разметку 5000 объектов из-за неверно выбранной единицы разметки — это бюджет всего исследования. Вот умолчания, которые он берёт, и каждое из них он перечисляет как допущение, когда сдаёт задачу:

Решения, которые он возвращает вам

Пять решений уходят обратно исследователю одним общим сообщением, каждое с предложенным ответом, так что принять его можно одним словом:

• Единица разметки, когда данные её не задают. Файл абзацев, где вопрос на самом деле про предложения, — это развилка исследования, и любой выбор может означать, что размечать придётся заново.
• Число разметчиков на объект, когда вы собираетесь отчитываться о согласованности. Три разметчика стоят втрое дороже одного, поэтому навык предлагает число вместе с обоснованием, а не тратит ваш бюджет за вас.
• Формулировка информированного согласия. Он пишет черновик по вашему описанию и прямо говорит, что черновик нужно заменить текстом, который одобрил ваш этический комитет.
• Набор меток, куда некуда деть сложные случаи. Три метки без «неясно» и без «ничего из перечисленного» — обычно недосмотр: разметчики начинают складывать по-настоящему неоднозначные объекты куда попало, и дальше по конвейеру уже не видно, что так вышло. Навык называет объекты, которым, по его мнению, некуда деться.
• Всё, что показывает разметчикам имена пользователей, лица или места.

Ничто из этого не блокирует сборку. Навык фиксирует свои допущения, собирает задачу, проверяет её и задаёт вопросы рядом с тем, что уже можно покликать.

Проверки перед сдачей

Конфигурация, прошедшая валидацию, говорит вам, что сервер запустится, и ничего не говорит о том, сможет ли человек сделать работу. Поэтому навык велит агенту отрисовать задачу и посмотреть на неё:

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

--strict превращает нераспознанный ключ конфигурации из предупреждения в ошибку. Без него опечатка принимается, игнорируется, и функция, которую вы считали включённой, остаётся выключенной — обычная причина конфигурации, которая читается правильно, но ничего не делает.

--screenshot поднимает настоящий сервер Potato и управляет им в headless-режиме через Playwright, записывая ошибки консоли, неперехваченные исключения страницы и HTTP-ответы с кодом 400 и выше. Он завершается с кодом 0, только когда все три списка пусты. Этот шаг ловит то, что валидация поймать не может, потому что бо́льшую часть интерфейса разметки строит JavaScript уже после прихода HTML. Типичный случай — невидимая радиокнопка: текст метки всё равно отрисовывается, и на беглый взгляд вопрос выглядит правильно.

Цикл вокруг этих двух команд — это рекомендация, а не автоматизация. Справочные материалы велят агенту вносить по одному изменению за круг, писать каждую отрисовку в новое имя файла, чтобы пара показывала, что изменение дало, и рассчитывать на три-четыре круга на нестандартной вёрстке. Там же сказано, что всё, что стоит за display_logic, на первой отрисовке отсутствует и его отсутствие ничего не доказывает, поэтому условие закомментируют, отрисовывают и возвращают на место.

Три из девяти вспомогательных скриптов автоматизируют то, что можно измерить, а не оценить на глаз. check_ui.py измеряет живую вёрстку при 1280x900 и сообщает о схемах или кнопке Next ниже сгиба, о пустых медиавиджетах и дублирующихся горячих клавишах. boot_and_check.py запускает сервер и сообщает о каждой функции, которая настроена, но ничего не загрузила, — например, об обучающем раунде, загрузившем ноль обучающих объектов. walk_task.py проходит запущенную задачу так, как это делал бы разметчик, и сообщает, где он останавливается.

Безопасные и небезопасные изменения после старта разметчиков

Бо́льшая часть того, что идёт не так в исследовании с разметкой, идёт не так уже после того, как разметчики начали, и важные отказы не выдают никакого сообщения об ошибке. Навык держит два таких случая.

Переименование вопроса посреди исследования — самый резкий. Ничего не падает, а три поверхности потом сообщают три разные вещи. Админский обзор говорит, что исследование выполнено на 100%, отчёт о согласованности говорит, что в этой схеме ноль объектов, а экспорт в CSV несёт старое имя колонки, потому что экспорт строится по тому, что было сохранено, а не по конфигурации. Одна строка WARNING в логе запуска — вся страховка целиком. У добавления вопроса есть более тихая версия той же проблемы: Potato отслеживает завершённость по объектам и никогда по вопросам, поэтому вопрос, добавленный позже, никогда не дойдёт до того, кто уже прошёл корпус.

Аутентификация — второй случай. Бэкенд по умолчанию держит учётные записи в памяти, поэтому остановка сервера уносит с собой все логины разметчиков, тогда как сами разметки спокойно лежат на диске. Разметчик возвращается, регистрируется заново под тем же именем и снова подключается к своей работе, и это скрывает проблему до тех пор, пока кто-нибудь не наберёт другое имя и не начнёт корпус заново уже как второй человек. authentication.user_config_path записывает учётные записи на диск с солёным хешем. Важнее всего это там, где про него легче всего забыть, потому что Render и Hugging Face Spaces перезапускают контейнеры сами.

Для уже идущего исследования study_status.py читает админские маршруты и выдаёт прогресс, темп по каждому разметчику, согласованность по каждому вопросу, кто заваливает проверки внимательности и кто сидит на объектах, которые бросил. Дальше навык говорит, какие правки ещё безопасны, а какие испортят ответы, за которые вы уже заплатили.

MCP-серверы Potato

В Potato есть два MCP-сервера, которые дают агенту те же ответы без вызова командной строки. potato mcp serve --root . открывает 12 инструментов для сборки задач, читающих те же реестры, что и CLI, включая render_task_screenshot, который возвращает отрисованную страницу картинкой. potato mcp connect подключается к идущему исследованию и добавляет 12 живых инструментов: статус, прогресс, разметчики, согласованность, назначение и экспорт. Мосту нужен блок mcp в конфигурации со списком открываемых инструментов и токен из potato mcp issue-token.

Самодельные инструменты разметки и во что они обходятся

Обычный способ разметить пару сотен объектов — попросить кодового агента быстро сделать инструмент разметки: страницу на Streamlit или Flask, которая показывает по одному объекту и дописывает каждый ответ в CSV. Это разумно собрать, когда один человек однократно размечает данные на полдня. Цена приходит, когда исследованию нужны вход для каждого разметчика, три разметчика на объект с маршрутизацией каждого объекта нужным людям, обучающий раунд и проверки внимательности, статистика согласованности, код завершения для Prolific, экспорт в формате, которого ждёт следующий скрипт, или второе исследование через месяц, работающее так же. Каждый из этих пунктов — функция, которую кто-то пишет, тестирует и отлаживает внутри инструмента, сделанного под одно исследование, а в Potato они уже есть все.

Различаются эти два пути ещё и тем, что переживает исследование. Самодельный инструмент разметки обычно привязан к одному датасету в одном репозитории, а задача Potato — это папка с конфигурацией и данными, которую может запустить любой, у кого есть Potato. В галерее их больше 400, большинство взято из опубликованных статей, а find_design.py ищет там дизайн, близкий к описанному вами.

Исследования, которые навык настраивает

Пять случаев показывают диапазон, каждый начинается с короткого описания и заканчивается работающей задачей:

• Метки позиции от краудворкеров. Три разметчика на пост, обучающий раунд, проверки внимательности, код завершения Prolific и согласованность, когда метки собраны. См. как провести краудсорсинговое исследование и измерение согласованности разметчиков.
• Сравнение двух ответов чат-бота. Вёрстка бок о бок со шкалой предпочтения и свободным текстовым обоснованием. См. попарное сравнение моделей и данные предпочтений для RLHF.
• Отметка шага, на котором трасса агента сломалась. Трасса раскладывается по одному шагу за раз, и задача записывает шаг, который отметил разметчик, и его объяснение. См. разметку траекторий агентов.
• Продолжение проекта в CVAT. potato import читает 20 форматов, поэтому существующие рамки приходят вместе со своими метками, а исследование экспортируется обратно в COCO. См. измерение согласованности по ограничивающим рамкам.
• Два кодировщика и кодовая книга. Кодовая книга становится интерфейсом кодирования, обоим кодировщикам назначаются все ответы, а шаг согласования разбирает расхождения. См. согласование и расхождения.

Тесты по реестрам Potato

Правдоподобный неверный идентификатор хуже, чем отсутствие документации, потому что агент им воспользуется. Поэтому три из 28 справочных файлов генерируются из собственных реестров Potato и не могут разойтись с тем, что проверяет сервер: все 61 тип разметки, каждый с разобранным примером, взятым из реального проекта, документированные ключи конфигурации верхнего уровня и документированные вложенные ключи.

CI покрывает основные файлы навыка и проверяет, что каждый тип разметки, тип отображения, ключ конфигурации, оператор, название стратегии и команда, названные в них, есть в Potato. Каждый YAML-пример вставляется в рабочую конфигурацию и прогоняется через настоящий валидатор Potato, а разобранный пример поднимает настоящий сервер, где каждая включённая им функция обязана сообщить в логе ненулевое число.

Справочные материалы опубликованы на davidjurgens.github.io/potato-skill, так что прочитать, что навык говорит агенту, можно до установки. Anthropic рекомендует сначала просматривать любой навык.

Вопросы

Вопросы ниже касаются выбора между potato-skill и самодельным инструментом разметки, того, что навык проверяет перед сдачей, и того, как изменить интерфейс, который он собирает.

Должен ли кодовый агент собирать свой инструмент разметки или лучше взять готовый?

Свой инструмент стоит собирать, только если один человек однократно размечает пару сотен объектов. Для этого случая хватит страницы на Streamlit или Flask, которая показывает по одному объекту и дописывает каждый ответ в CSV. Как только исследованию нужны несколько разметчиков на объект, обучающий раунд, проверки внимательности, статистика согласованности или код завершения для Prolific, каждый из этих пунктов придётся написать и протестировать внутри инструмента, сделанного под одно исследование, а в Potato они уже есть все. Поэтому potato-skill строится на Potato, и задача, которую он создаёт, представляет собой папку, которую может перезапустить любой, у кого есть Potato.

Что potato-skill проверяет перед сдачей задачи?

potato-skill заставляет агента выполнить две команды Potato, прежде чем вернуть задачу, а три его вспомогательных скрипта проверяют то, чего эти команды увидеть не могут. potato validate config.yaml --strict завершается ошибкой на любом нераспознанном ключе конфигурации. potato preview config.yaml --screenshot поднимает настоящий сервер в headless-режиме через Playwright и завершается с кодом 0, только если страница не выдала ни ошибок консоли, ни неперехваченных исключений, ни HTTP-ответов с кодом 400 и выше. check_ui.py сообщает о вопросах разметки или кнопке Next ниже сгиба, boot_and_check.py сообщает о функциях, которые настроены, но ничего не загрузили, а walk_task.py проходит задачу так, как это делал бы разметчик, и сообщает, где он останавливается.

Можно ли настроить интерфейс, который собирает potato-skill?

Да. Задача представляет собой обычную конфигурацию Potato, поэтому вёрстку можно править руками или попросить агента её изменить. Для нестандартной вёрстки potato-skill велит агенту вносить по одному изменению за круг, писать каждую отрисовку в новый файл скриншота, чтобы соседние отрисовки показывали, что дало изменение, и рассчитывать на три-четыре круга. Всё, что стоит за display_logic, на первой отрисовке отсутствует, поэтому агент закомментирует условие, отрисует задачу и вернёт условие на место.

Что почитать дальше

• Быстрый старт с кодовым агентом, где настройка разобрана подробнее
• potato-skill на GitHub, сейчас версия 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/