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:
pip install potato-annotationНужен ещё и кодовый агент. Навык писался под Claude Code, а ставится также в Codex и Cursor.
Установка навыка
В 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Что входит в установку для 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, когда вам нужен стоящий за ними справочный материал.
Описание исследования
Скажите, что нужно разметить, кто будет размечать и для чего нужны метки. Знать типы разметки Potato или формат его конфигурации не требуется. Запрос может быть совсем коротким:
Хочу, чтобы 200 твитов разметили по тональности по 5-балльной шкале, по три разметчика на твит, со страницей согласия и двумя проверками внимательности. Собери и запусти.
Навык сам определяет формулировки вопросов, шкалу, способ назначения объектов и способ проверки разметчиков. Вопросы, которые он хочет подтвердить, сборку не блокируют: он фиксирует свои допущения, собирает задачу, проверяет её и задаёт вопросы рядом с тем, что уже можно покликать.
Проверки, которые агент выполняет перед сдачей
Конфигурация, прошедшая валидацию, говорит вам, что сервер запустится, и ничего не говорит о том, сможет ли человек сделать работу. Поэтому навык велит агенту отрисовать задачу и посмотреть на неё:
potato validate config.yaml --strict
potato preview config.yaml --screenshot shot-01.png--strict превращает нераспознанный ключ конфигурации из предупреждения в ошибку и тем ловит опечатку, из-за которой функция осталась бы тихо выключенной. --screenshot поднимает настоящий сервер Potato и управляет им в headless-режиме через Playwright, записывая ошибки консоли, неперехваченные исключения страницы и HTTP-ответы с кодом 400 и выше. Он завершается с кодом 0, только когда все три списка пусты.
Три из девяти вспомогательных скриптов автоматизируют то, что можно измерить, а не оценить на глаз. check_ui.py измеряет живую вёрстку и сообщает о схемах или кнопке Next ниже сгиба, о пустых медиавиджетах и дублирующихся горячих клавишах. 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сообщает прогресс по каждому разметчику и согласованность по каждому вопросу, а навык говорит, какие правки безопасны посреди исследования, а какие испортят уже собранные данные.
MCP-серверы Potato
Те же ответы агент может получать через MCP, а не через командную строку. 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 там, где агент выполняет команды, а затем опишите агенту исследование обычными словами. 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, так что вы можете прочитать, что навык говорит агенту, ещё до установки.