potato-skill: Crea un estudio de anotación con un agente de programación
Describe a Claude Code, Codex o Cursor qué etiquetar y potato-skill diseña el estudio de anotación, lo construye en Potato y comprueba que se renderiza.
Hay dos formas de empezar un proyecto de Potato. Puedes escribir la tarea tú mismo, como muestra el Inicio rápido, o describir el estudio a un agente de programación y dejar que potato-skill lo diseñe y lo construya. Esta página trata la segunda vía. Las dos terminan en el mismo sitio, una tarea de anotación de Potato que puedes ejecutar, cambiar y compartir.
Qué decide la skill
potato-skill es una skill de agente, un paquete de instrucciones y scripts auxiliares que un agente de programación carga cuando una petición lo necesita. Trae 28 archivos de referencia y nueve scripts auxiliares, y cubre tanto el diseño del estudio como su construcción:
- qué preguntar a los anotadores y con qué escala
- cuántos anotadores necesita cada elemento
- cómo formar a los anotadores y revisar su trabajo
- la interfaz que ven los anotadores
- exportar los resultados en el formato que necesita el siguiente paso
Unas cuantas de esas decisiones las resuelve por su cuenta y otras te las devuelve. La regla con la que trabaja es que una decisión se toma sobre la marcha cuando equivocarse sale barato de arreglar, y se devuelve cuando equivocarse sale caro, es irreversible o no le corresponde al agente. Toma una escala de 5 puntos con todos los puntos etiquetados, atajos de teclado en cualquier pregunta con nueve etiquetas o menos, orden aleatorio de los elementos con un random_seed fijo y todas las preguntas obligatorias. Te pregunta por la unidad de anotación, por el número de anotadores por elemento cuando se va a informar del acuerdo, por la redacción del consentimiento y por cualquier conjunto de etiquetas sin una opción de «no está claro».
La tarea que construye funciona sobre Potato, así que recibe lo que Potato ya hace: un inicio de sesión por anotador, varios anotadores por elemento, estadísticas de acuerdo, integración con Prolific y SONA y exportación a los formatos que leen las herramientas posteriores.
Requisitos
Potato tiene que estar instalado allí donde el agente ejecuta comandos, porque los scripts auxiliares de la skill importan los registros de Potato y manejan el comando potato:
pip install potato-annotationTambién necesitas un agente de programación. La skill se escribió para Claude Code, y se instala igualmente en Codex y en Cursor.
Instalar la skill
En Claude Code, se instala desde el marketplace de plugins:
/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potatoPara Codex y Cursor, la CLI skills la instala dentro del proyecto en el que estás trabajando:
npx skills add davidjurgens/potato-skill --agent codex cursorQué incluye una instalación en Codex o Cursor
La CLI skills escribe .agents/skills/potato-skill/ con SKILL.md, las 28 referencias y los nueve scripts, así que un proyecto de Codex o Cursor recibe el mismo material que una instalación en Claude Code. No toca AGENTS.md ni .cursor/rules, y cómo descubre cada herramienta una skill en ese directorio depende de la herramienta.
El repositorio también lleva un AGENTS.md en la raíz, que Codex y Cursor leen por el nombre de archivo sin ningún paso de instalación. Ese archivo es un resumen breve frente a unas 79.000 palabras repartidas entre las referencias, y apunta a archivos de referencia y scripts que solo deja en disco una instalación completa. Úsalo cuando quieras que un agente tenga el ciclo de comprobar antes de entregar y las reglas que de verdad muerden, y usa la CLI skills cuando quieras el material de referencia que hay detrás.
Describir el estudio
Di qué hay que etiquetar, quién lo va a etiquetar y para qué sirven las etiquetas. No necesitas conocer los tipos de anotación de Potato ni su formato de configuración. Una petición puede ser así de corta:
Quiero que tres anotadores etiqueten cada uno 200 tuits según su sentimiento en una escala de 5 puntos, con una página de consentimiento y dos verificaciones de atención. Constrúyelo y ponlo en marcha.
La skill decide la redacción de las preguntas, la escala, cómo se asignan los elementos y cómo se revisa a los anotadores. No se queda bloqueada esperando a que confirmes las preguntas que te plantea. Declara sus supuestos, construye la tarea, la verifica y pregunta junto a algo por lo que ya puedes navegar haciendo clic.
Comprobaciones que hace el agente antes de entregar
Un config que valida te dice que el servidor va a arrancar, y no te dice nada sobre si una persona puede hacer el trabajo. La skill le indica al agente que renderice la tarea y la mire:
potato validate config.yaml --strict
potato preview config.yaml --screenshot shot-01.png--strict convierte una clave de configuración no reconocida de aviso en error, lo que detecta una errata que en otro caso dejaría una función apagada sin decir nada. --screenshot arranca un servidor real de Potato y lo maneja con Playwright en modo headless, registrando errores de consola, excepciones no capturadas de la página y respuestas HTTP de 400 en adelante. Sale con 0 solo cuando las tres listas están vacías.
Tres de los nueve scripts auxiliares automatizan lo que se puede medir en lugar de juzgar. check_ui.py mide el layout en vivo e informa de esquemas o de un botón Next por debajo del pliegue, widgets de medios vacíos y atajos duplicados. boot_and_check.py informa de cada función que está configurada pero no cargó nada. walk_task.py recorre una tarea en marcha como lo haría un anotador e informa de dónde se detiene.
Abre la tarea en el navegador y etiqueta tú mismo unos cuantos elementos antes de invitar a nadie.
La tarea que produce
Una tarea de Potato es una carpeta de proyecto con la configuración, los datos y las instrucciones de la tarea. Todo lo del Inicio rápido se aplica a ella. La inicias con potato start config.yaml, la editas a mano, añades anotadores y exportas las etiquetas.
Como el resultado es una carpeta de tarea de Potato, otras personas también pueden usarla. Un colega puede ejecutar el mismo estudio con datos nuevos, tú puedes repetirlo el año que viene y puedes publicarlo junto al artículo que lo usó. El showcase es una colección de tareas compartidas así, tomadas de artículos publicados.
Diseños y anotaciones que ya existen
- Un diseño publicado. La skill puede partir de uno de los 440 diseños de anotación tomados de artículos publicados, con sus conjuntos de etiquetas, la redacción de sus preguntas y sus instrucciones. Puedes explorarlos en el showcase, y
find_design.pylos busca para encontrar un diseño cercano al que describiste. - Anotaciones de otra herramienta.
potato importlee 20 formatos, entre ellos Labelbox, CVAT y COCO, así que un proyecto a medias puede continuar en Potato. - Un estudio que ya está en marcha.
study_status.pyinforma del progreso de cada anotador y del acuerdo en cada pregunta, y la skill dice qué correcciones son seguras a mitad del estudio y cuáles corromperían los datos ya recogidos.
Los servidores MCP de Potato
Un agente puede llegar a las mismas respuestas por MCP en lugar de por la shell. potato mcp serve --root . expone 12 herramientas de autoría que leen los mismos registros que la CLI, entre ellas render_task_screenshot, que devuelve la página renderizada como imagen. potato mcp connect hace de puente con un estudio en marcha y añade 12 herramientas en vivo que cubren estado, progreso, anotadores, acuerdo, asignación y exportación. El puente necesita un bloque mcp en el config que liste las herramientas a exponer, y un token de potato mcp issue-token.
Pruebas contra los registros de Potato
Un identificador equivocado pero plausible es peor que no tener documentación, porque un agente lo va a usar. Tres de las 28 referencias se generan a partir de los propios registros de Potato y no pueden desviarse de lo que el servidor aplica: los 61 tipos de anotación, cada uno con un ejemplo funcional sacado de un proyecto real, las claves de configuración de nivel superior documentadas y las subclaves documentadas.
CI cubre los archivos centrales de la skill y comprueba que cada tipo de anotación, tipo de display, clave de configuración, operador, nombre de estrategia y comando que aparece en ellos existe en Potato. Cada muestra de YAML se inserta en un config que funciona y se pasa por el validador real de Potato, y el ejemplo funcional arranca un servidor real.
Su material de referencia está publicado en davidjurgens.github.io/potato-skill, y se puede leer sin instalar nada. Anthropic recomienda revisar cualquier skill antes de instalarla.
Comparación de las dos vías
Las dos vías se diferencian en aquello de lo que partes, no en aquello con lo que terminas:
| Escribir la tarea tú mismo | Describirla a un agente de programación | |
|---|---|---|
| Empiezas con | un config YAML | una descripción en lenguaje corriente |
| Adecuada para | aprender Potato, tareas pequeñas | estudios nuevos, estudios de crowdsourcing con formación y comprobaciones, tipos de anotación que no has usado |
| Terminas con | una tarea de Potato | una tarea de Potato |
Puedes cambiar de vía en cualquier momento. Un agente puede modificar una tarea que escribiste, y tú puedes editar una que construyó el agente.
Preguntas
Las preguntas siguientes tratan cómo configurar potato-skill con un agente de programación y dónde encontrar su código fuente.
¿Cómo uso Potato con un agente de programación?
Instala Potato y potato-skill allí donde el agente ejecuta comandos, y después describe el estudio al agente en lenguaje corriente. pip install potato-annotation instala Potato. En Claude Code, /plugin marketplace add davidjurgens/potato-skill seguido de /plugin install potato-skill@potato instala la skill, y en Codex o Cursor lo hace npx skills add davidjurgens/potato-skill --agent codex cursor. Dile al agente qué hay que etiquetar, quién lo va a etiquetar y para qué sirven las etiquetas. potato-skill construye la tarea, la renderiza para comprobar que funciona y te devuelve la lista de decisiones que tomó por ti.
¿Dónde está potato-skill en GitHub?
potato-skill está en github.com/davidjurgens/potato-skill, publicada bajo la GPL-3.0-or-later. Su material de referencia está publicado en davidjurgens.github.io/potato-skill, así que puedes leer lo que la skill le dice al agente antes de instalarla.