potato-skill: crea un estudio de anotación con Claude Code, Codex o Cursor

potato-skill convierte la descripción en lenguaje corriente de un estudio de anotación en una tarea de Potato en funcionamiento. Trae 28 archivos de referencia y nueve scripts auxiliares que cubren las decisiones de diseño previas al config, la interfaz que ve el anotador y las comprobaciones que detectan una tarea que valida pero no funciona. Se instala en Claude Code, Codex y Cursor, y se publica bajo la GPL-3.0-or-later.

Instalar la skill

Claude Code la instala desde un marketplace de plugins, con dos comandos:

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

Codex y Cursor la instalan con la CLI skills, que copia la skill dentro del proyecto en el que estás trabajando:

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

Potato tiene que estar instalado allí donde el agente ejecuta comandos, porque los nueve scripts auxiliares importan sus registros y manejan el comando potato:

pip install potato-annotation

Qué 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.

Valores por defecto que la skill fija sin preguntar

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. Cambiar un atajo de teclado no cuesta nada, mientras que volver a pasar 5.000 elementos porque la unidad de anotación era la equivocada se lleva el presupuesto del estudio. Estos son los valores por defecto que toma, y cada uno lo declara como supuesto cuando entrega la tarea:

Decisiones que te devuelve

Cinco decisiones vuelven al investigador en un único mensaje agrupado, cada una con una respuesta propuesta para que se pueda aceptar con una palabra:

• La unidad de anotación, cuando los datos no la determinan. Un archivo de párrafos donde la pregunta trata en realidad sobre oraciones es una bifurcación del estudio, y cualquiera de las dos opciones puede obligar a repetirlo.
• Anotadores por elemento, cuando se va a informar del acuerdo. Tres anotadores cuestan el triple que uno, así que la skill propone un número con su motivo en lugar de gastarte el presupuesto.
• La redacción del consentimiento. Escribe un borrador a partir de lo que describiste y dice claramente que hay que sustituirlo por el texto que aprobó tu comité de ética.
• Un conjunto de etiquetas sin sitio donde meter los casos difíciles. Tres etiquetas sin un «no está claro» y sin un «ninguna» suele ser un descuido, y entonces los anotadores colocan los elementos genuinamente ambiguos en algún sitio arbitrario, donde nada de lo que viene después puede ver que ocurrió. La skill nombra los elementos que cree que no tienen dónde ir.
• Cualquier cosa que muestre nombres de usuario, caras o ubicaciones a los anotadores.

Nada de esto bloquea la construcción. La skill declara sus supuestos, construye la tarea, la verifica y hace las preguntas junto a algo por lo que ya puedes navegar haciendo clic.

Comprobaciones antes de la entrega

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. Así que 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. Sin él, una errata se acepta, se ignora, y la función que creías haber activado sigue apagada, que es la causa habitual de un config que se lee bien mientras no pasa 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. Ese paso detecta lo que la validación no puede, porque la mayor parte de la interfaz de anotación la construye JavaScript después de que llegue el HTML. Un botón de radio invisible es el caso típico, ya que el texto de la etiqueta sí se renderiza y la pregunta parece correcta de un vistazo.

El ciclo alrededor de esos dos comandos es orientación, no automatización. El material de referencia le dice al agente que haga un cambio por ronda, que escriba cada renderizado en un nombre de archivo nuevo para que el par muestre qué hizo el cambio, y que espere tres o cuatro rondas en un layout a medida. También le dice que todo lo que esté detrás de display_logic no aparece en el primer renderizado y que su ausencia no prueba nada, así que la condición se comenta, se renderiza y se vuelve a poner.

Tres de los nueve scripts auxiliares automatizan las partes que se pueden medir en lugar de juzgar. check_ui.py mide el layout en vivo a 1280x900 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 arranca el servidor e informa de cada función que está configurada pero no cargó nada, como una fase de entrenamiento que cargó cero elementos de entrenamiento. walk_task.py recorre una tarea en marcha como lo haría un anotador e informa de dónde se detiene.

Cambios seguros e inseguros después de que empiecen los anotadores

Casi todo lo que sale mal en un estudio de anotación sale mal después de que los anotadores hayan empezado, y los fallos que importan no producen ningún mensaje de error. La skill recoge dos de ellos.

Renombrar una pregunta a mitad del estudio es el más afilado. No falla nada, y a partir de ahí tres superficies informan de tres cosas distintas. El resumen de administración dice que el estudio está completo al 100 %, el informe de acuerdo dice que ese esquema tiene cero elementos, y la exportación a CSV lleva el nombre de columna antiguo, porque las exportaciones se guían por lo que se almacenó y no por el config. Un único WARNING en el log de arranque es toda la red de seguridad. Añadir una pregunta tiene una versión más silenciosa del mismo problema, porque Potato hace el seguimiento de la finalización por elemento y nunca por pregunta, así que una pregunta añadida más tarde nunca llega a quien ya terminó el corpus.

La autenticación es el segundo. El backend por defecto guarda las cuentas en memoria, así que parar el servidor se lleva por delante todos los inicios de sesión de los anotadores mientras las anotaciones siguen a salvo en disco. Un anotador vuelve, se registra otra vez con el mismo nombre de usuario y queda reenganchado a su trabajo, lo que oculta el problema hasta que alguien escribe un nombre de usuario distinto y empieza el corpus de nuevo como una segunda persona. Configurar authentication.user_config_path escribe las cuentas en disco con un hash con sal. Importa más donde es más fácil olvidarlo, ya que Render y Hugging Face Spaces reinician los contenedores por su cuenta.

Para un estudio ya en marcha, study_status.py lee las rutas de administración y saca el progreso, los ritmos por anotador, el acuerdo en cada pregunta, quién está fallando las verificaciones de atención y quién está sentado sobre elementos que abandonó. La skill dice entonces qué arreglos siguen siendo seguros y cuáles corromperían respuestas que ya has pagado.

Los servidores MCP de Potato

Potato trae dos servidores MCP, que le dan al agente las mismas respuestas sin salir a 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.

Las herramientas de etiquetado escritas a mano y lo que cuestan

Una forma habitual de etiquetar unos cientos de elementos es pedirle a un agente de programación una herramienta de etiquetado rápida, por ejemplo una página en Streamlit o Flask que muestre un elemento cada vez y vaya añadiendo cada respuesta a un CSV. Es algo razonable de construir cuando una persona etiqueta una tarde de datos una sola vez. El coste llega cuando el estudio necesita un inicio de sesión por anotador, tres anotadores por elemento con cada elemento dirigido a las personas correctas, una fase de entrenamiento y verificaciones de atención, estadísticas de acuerdo, un código de finalización para Prolific, una exportación en el formato que espera el siguiente script, o un segundo estudio el mes que viene que funcione igual. Cada una de esas cosas es una función que alguien escribe, prueba y depura dentro de una herramienta construida para un solo estudio, y Potato ya las tiene todas.

Las dos se diferencian también en lo que sobrevive al estudio. Una herramienta de etiquetado escrita a mano suele estar atada a un conjunto de datos dentro de un repositorio, mientras que una tarea de Potato es una carpeta con un config y datos que cualquiera con Potato puede arrancar. El showcase tiene más de 400, la mayoría sacadas de artículos publicados, y find_design.py lo busca para encontrar un diseño parecido al que describiste.

Estudios que la skill deja montados

Cinco casos muestran el rango, cada uno partiendo de una descripción breve y terminando en una tarea ejecutable:

• Etiquetas de postura con crowdworkers. Tres anotadores por publicación, una fase de entrenamiento, verificaciones de atención, un código de finalización de Prolific y el acuerdo una vez que están las etiquetas. Consulta crowdsourcing en Prolific y MTurk y medir el acuerdo entre anotadores.
• Comparar dos respuestas de chatbot. Un layout en paralelo con una escala de preferencia y un motivo en texto libre. Consulta comparación de modelos por pares y datos de preferencias para RLHF.
• Marcar el paso que falla en la traza de un agente. La traza se despliega paso a paso, y la tarea registra el paso que marcó el anotador y su explicación. Consulta anotar trayectorias de agentes.
• Continuar un proyecto de CVAT. potato import lee 20 formatos, así que las cajas existentes entran con sus etiquetas, y el estudio vuelve a exportarse como COCO. Consulta medir el acuerdo en cajas delimitadoras.
• Dos codificadores y un libro de códigos. El libro de códigos se convierte en la interfaz de codificación, a los dos codificadores se les asigna cada respuesta, y un paso de adjudicación resuelve los desacuerdos. Consulta adjudicación y desacuerdo.

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. Por eso 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 donde cada función que activa tiene que registrar un recuento distinto de cero en el log.

El 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. Anthropic recomienda revisar cualquier skill antes.

Preguntas

¿Necesito conocer Potato primero?

No. Describes el estudio en lenguaje corriente, y Potato tiene que estar instalado en la máquina donde el agente ejecuta comandos. Antes de que los anotadores vean la tarea, ábrela en un navegador y etiqueta tú unos cuantos elementos.

¿Puedo usar potato-skill con Codex o Cursor?

Sí, por cualquiera de las dos vías. npx skills add davidjurgens/potato-skill --agent codex cursor deja la skill completa en el proyecto, y el AGENTS.md del repositorio da una versión más corta sin instalar nada. La skill se escribió para Claude Code, que es donde está la instalación desde el marketplace.

¿Debería pedirle a mi agente de programación que construya una herramienta de anotación a medida?

Para unos cientos de elementos que etiqueta una sola persona una vez, un script pequeño basta. En cuanto el estudio necesita varios anotadores por elemento, entrenamiento, verificaciones de atención, acuerdo o una plataforma de crowdsourcing, cada una de esas cosas hay que construirla y probarla. potato-skill se apoya en Potato, que ya las tiene, y la tarea que produce se puede volver a ejecutar y compartir.

¿Puedo editar lo que construye?

Sí. La salida es una tarea de Potato normal, una carpeta con un config, datos e instrucciones. Edítala a mano con el Inicio Rápido y los Fundamentos de Configuración, o pídele al agente que la cambie.

¿Cuánto cuesta?

Nada. Potato es gratuito y de código abierto, y potato-skill se publica bajo la GPL-3.0-or-later. Pagas por el agente de programación que ya usas, y por los anotadores si los contratas.

¿Qué es Potato?

Potato es una herramienta de anotación de código abierto de la Universidad de Michigan, descrita en una demostración de sistema de ACL 2026. Admite 61 tipos de anotación en texto, imágenes, audio, vídeo, diálogo y trazas de agentes.

Más lecturas

• Inicio rápido con un agente de programación, que cubre la instalación con más detalle
• potato-skill en GitHub, ahora mismo en la v1.0.1
• El material de referencia de la skill
• El showcase, para encontrar un diseño cercano a tu estudio

Referencias

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/