potato-skill : construire une étude d'annotation avec Claude Code, Codex ou Cursor

potato-skill transforme la description en langage courant d'une étude d'annotation en une tâche Potato qui tourne. Il livre 28 fichiers de référence et neuf scripts d'assistance couvrant les décisions de conception qui précèdent la configuration, l'interface que voit l'annotateur, et les vérifications qui attrapent une tâche qui passe la validation mais ne fonctionne pas. Il s'installe dans Claude Code, Codex et Cursor, et il est publié sous licence GPL-3.0-or-later.

Installer le skill

Claude Code l'installe depuis un marketplace de plugins, en deux commandes :

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

Codex et Cursor l'installent avec la CLI skills, qui copie le skill dans le projet sur lequel vous travaillez :

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

Potato lui-même doit être installé là où l'agent exécute ses commandes, car les neuf scripts d'assistance importent ses registres et pilotent la commande potato :

pip install potato-annotation

Ce que contient une installation Codex ou Cursor

La CLI skills écrit .agents/skills/potato-skill/ avec SKILL.md, les 28 références et les neuf scripts, si bien qu'un projet Codex ou Cursor reçoit le même matériel qu'une installation Claude Code. Elle ne touche ni à AGENTS.md ni à .cursor/rules, et la façon dont chaque outil découvre un skill dans ce répertoire lui appartient.

Le dépôt porte aussi un AGENTS.md à sa racine, que Codex et Cursor lisent d'après son nom de fichier, sans aucune étape d'installation. Ce fichier est un court résumé face à environ 79 000 mots répartis dans les références, et il renvoie à des fichiers de référence et à des scripts que seule une installation complète pose sur le disque. Utilisez-le quand vous voulez donner à un agent la boucle de vérification avant remise et les règles qui mordent, et utilisez la CLI skills quand vous voulez le matériel de référence qui les sous-tend.

Les valeurs par défaut que le skill fixe sans demander

Une décision est prise sur place quand se tromper coûte peu à corriger, et renvoyée quand se tromper coûte cher, est irréversible, ou n'appartient pas à l'agent. Changer un raccourci clavier ne coûte rien, alors que relancer 5 000 éléments parce que l'unité d'annotation était mauvaise coûte le budget de l'étude. Voici les valeurs par défaut qu'il retient, chacune étant listée comme une hypothèse au moment où il remet la tâche :

Les décisions qu'il vous renvoie

Cinq décisions reviennent au chercheur dans un message groupé, chacune avec une réponse proposée, de sorte qu'on peut l'accepter d'un mot :

• L'unité d'annotation, quand les données ne la tranchent pas. Un fichier de paragraphes alors que la question porte en réalité sur des phrases est un embranchement dans l'étude, et l'un ou l'autre choix peut obliger à la relancer.
• Le nombre d'annotateurs par élément, quand l'accord sera rapporté. Trois annotateurs coûtent trois fois un seul, alors le skill propose un nombre avec sa justification plutôt que de dépenser le budget à votre place.
• La formulation du consentement. Il rédige un brouillon à partir de ce que vous avez décrit et dit clairement qu'il faut le remplacer par le texte approuvé par votre comité d'éthique.
• Un jeu d'étiquettes sans nulle part où ranger les cas difficiles. Trois étiquettes sans « incertain » et sans « aucune » relèvent en général de l'oubli, et les annotateurs placent alors les éléments réellement ambigus quelque part au hasard, là où rien en aval ne peut voir que c'est arrivé. Le skill nomme les éléments qui, selon lui, n'ont nulle part où aller.
• Tout ce qui montre aux annotateurs des noms d'utilisateur, des visages ou des lieux.

Rien de tout cela ne bloque la construction. Le skill énonce ses hypothèses, construit la tâche, la vérifie, et pose ses questions à côté de quelque chose que vous pouvez déjà parcourir.

Les vérifications avant remise

Une configuration qui passe la validation vous dit que le serveur va démarrer, et ne vous dit rien sur la possibilité pour une personne de faire le travail. Le skill demande donc à l'agent d'afficher la tâche et de la regarder :

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

--strict fait passer une clé de configuration non reconnue d'un avertissement à un échec. Sans cette option, une faute de frappe est acceptée, ignorée, et la fonctionnalité que vous pensiez avoir activée reste désactivée, ce qui est la cause habituelle d'une configuration qui se lit correctement pendant qu'il ne se passe rien.

--screenshot démarre un vrai serveur Potato et le pilote dans Playwright en mode headless, en enregistrant les erreurs de console, les exceptions non rattrapées de la page et les réponses HTTP de 400 ou plus. Il ne sort avec le code 0 que si ces trois listes sont vides. Cette étape attrape ce que la validation ne peut pas voir, car l'essentiel de l'interface d'annotation est construit par JavaScript après l'arrivée du HTML. Le bouton radio invisible en est le cas type, puisque le texte de l'étiquette s'affiche quand même et que la question a l'air correcte au premier coup d'œil.

Le cycle autour de ces deux commandes relève de la consigne plutôt que de l'automatisation. Le matériel de référence dit à l'agent de faire une seule modification par tour, d'écrire chaque rendu dans un nouveau nom de fichier pour que la paire montre ce que la modification a fait, et de s'attendre à trois ou quatre tours sur une mise en page sur mesure. Il dit aussi à l'agent que tout ce qui se trouve derrière display_logic est absent du premier rendu et que cette absence ne prouve rien, donc la condition est commentée, le rendu refait, et la condition remise.

Trois des neuf scripts d'assistance automatisent les parties qui peuvent être mesurées plutôt que jugées. check_ui.py mesure la mise en page réelle en 1280x900 et signale les schémas ou un bouton Next sous la ligne de flottaison, les widgets média vides et les raccourcis en double. boot_and_check.py démarre le serveur et signale chaque fonctionnalité configurée qui n'a rien chargé, par exemple une phase de formation qui a chargé zéro élément de formation. walk_task.py parcourt une tâche en cours d'exécution comme le ferait un annotateur et indique où elle s'arrête.

Modifications sûres et dangereuses une fois les annotateurs lancés

L'essentiel de ce qui tourne mal dans une étude d'annotation tourne mal après le démarrage des annotateurs, et les modes de défaillance qui comptent ne produisent aucun message d'erreur. Le skill en porte deux.

Renommer une question en cours d'étude est le plus tranchant. Rien ne lève d'erreur, et trois surfaces rapportent ensuite trois choses différentes. La vue d'administration dit que l'étude est complète à 100 %, le rapport d'accord dit que ce schéma a zéro élément, et l'export CSV porte l'ancien nom de colonne, parce que les exports sont pilotés par ce qui a été stocké et non par la configuration. Un unique WARNING dans le journal de démarrage constitue tout le filet de sécurité. Ajouter une question présente une version plus discrète du même problème, car Potato suit l'avancement par élément et jamais par question, si bien qu'une question ajoutée plus tard n'atteint jamais personne ayant déjà fini le corpus.

L'authentification est le deuxième. Le backend par défaut garde les comptes en mémoire, donc arrêter le serveur emporte avec lui chaque identifiant d'annotateur pendant que les annotations restent bien au chaud sur le disque. Un annotateur revient, se réinscrit sous le même nom d'utilisateur, et se retrouve rattaché à son travail, ce qui masque le problème jusqu'à ce que quelqu'un tape un nom d'utilisateur différent et recommence le corpus en tant que deuxième personne. Définir authentication.user_config_path écrit les comptes sur disque avec un hachage salé. Cela compte le plus là où c'est le plus facile à oublier, puisque Render et Hugging Face Spaces redémarrent les conteneurs d'eux-mêmes.

Pour une étude déjà en cours, study_status.py lit les routes d'administration pour l'avancement, les cadences par annotateur, l'accord sur chaque question, qui échoue aux contrôles d'attention, et qui est assis sur des éléments qu'il a abandonnés. Le skill dit ensuite quelles corrections restent sûres et lesquelles corrompraient des réponses que vous avez déjà payées.

Les serveurs MCP de Potato

Potato livre deux serveurs MCP, qui donnent à un agent les mêmes réponses sans passer par le shell. potato mcp serve --root . expose 12 outils de création qui lisent les mêmes registres que la CLI, dont render_task_screenshot, qui renvoie la page rendue sous forme d'image. potato mcp connect fait le pont avec une étude en cours et ajoute 12 outils en direct couvrant le statut, l'avancement, les annotateurs, l'accord, l'affectation et l'export. Le pont a besoin d'un bloc mcp dans la configuration listant les outils à exposer, et d'un jeton issu de potato mcp issue-token.

Les outils d'étiquetage écrits à la main et ce qu'ils coûtent

Une façon courante de faire étiqueter quelques centaines d'éléments est de demander à un agent de coding un petit outil d'étiquetage, par exemple une page Streamlit ou Flask qui affiche un élément à la fois et ajoute chaque réponse à un CSV. C'est une chose raisonnable à construire quand une personne étiquette une après-midi de données une seule fois. Le coût arrive quand l'étude a besoin d'un identifiant par annotateur, de trois annotateurs par élément avec chaque élément acheminé vers les bonnes personnes, d'une phase de formation et de contrôles d'attention, de statistiques d'accord, d'un code de complétion pour Prolific, d'un export dans le format qu'attend le script suivant, ou d'une deuxième étude le mois prochain qui fonctionne de la même manière. Chacun de ces points est une fonctionnalité que quelqu'un écrit, teste et débogue à l'intérieur d'un outil construit pour une seule étude, et Potato les a déjà toutes.

Les deux diffèrent aussi par ce qui survit à l'étude. Un outil d'étiquetage écrit à la main est en général lié à un jeu de données dans un dépôt, alors qu'une tâche Potato est un dossier contenant une configuration et des données que n'importe qui disposant de Potato peut démarrer. La vitrine en contient plus de 400, la plupart tirées d'articles publiés, et find_design.py y cherche un design proche de celui que vous avez décrit.

Les études que le skill met en place

Cinq cas montrent l'étendue, chacun partant d'une courte description et aboutissant à une tâche exécutable :

• Des étiquettes de positionnement par des travailleurs de plateforme. Trois annotateurs par publication, une phase de formation, des contrôles d'attention, un code de complétion Prolific, et l'accord une fois les étiquettes rentrées. Voir le crowdsourcing sur Prolific et MTurk et mesurer l'accord inter-annotateurs.
• Comparer deux réponses de chatbot. Une mise en page côte à côte avec une échelle de préférence et une justification en texte libre. Voir la comparaison de modèles par paires et les données de préférence RLHF.
• Marquer l'étape fautive dans une trace d'agent. La trace est présentée une étape à la fois, et la tâche enregistre l'étape marquée par l'annotateur ainsi que son explication. Voir l'annotation de trajectoires d'agents.
• Poursuivre un projet CVAT. potato import lit 20 formats, donc les boîtes existantes arrivent avec leurs étiquettes, et l'étude ressort en COCO. Voir mesurer l'accord sur les boîtes englobantes.
• Deux codeurs et un livre de codes. Le livre de codes devient l'interface de codage, les deux codeurs se voient affecter chaque réponse, et une étape d'arbitrage traite les désaccords. Voir arbitrage et désaccord.

Les tests contre les registres de Potato

Un identifiant faux mais plausible est pire que pas de documentation du tout, parce qu'un agent l'utilisera. Trois des 28 références sont donc générées depuis les propres registres de Potato et ne peuvent pas s'écarter de ce que le serveur impose : les 61 types d'annotation, chacun avec un exemple travaillé repris d'un vrai projet, les clés de configuration de premier niveau documentées, et les sous-clés documentées.

La CI couvre les fichiers centraux du skill, en vérifiant que chaque type d'annotation, type d'affichage, clé de configuration, opérateur, nom de stratégie et commande qui y est nommé existe bien dans Potato. Chaque exemple YAML est inséré dans une configuration fonctionnelle et passé au vrai validateur de Potato, et l'exemple travaillé démarre un vrai serveur où chaque fonctionnalité qu'il active doit rapporter un compte non nul dans le journal.

Le matériel de référence est publié sur davidjurgens.github.io/potato-skill, ce qui vous permet de lire ce que le skill dit à l'agent avant de l'installer. Anthropic recommande de relire tout skill au préalable.

Questions

Dois-je d'abord connaître Potato ?

Non. Vous décrivez l'étude en langage courant, et Potato doit être installé sur la machine où l'agent exécute ses commandes. Avant que les annotateurs voient la tâche, ouvrez-la dans un navigateur et étiquetez vous-même quelques éléments.

Puis-je utiliser potato-skill avec Codex ou Cursor ?

Oui, par l'une ou l'autre voie. npx skills add davidjurgens/potato-skill --agent codex cursor met le skill complet dans le projet, et l'AGENTS.md du dépôt en donne une version plus courte sans aucune installation. Le skill a été écrit pour Claude Code, où se trouve l'installation par le marketplace.

Devrais-je plutôt demander à mon agent de coding de construire un outil d'annotation sur mesure ?

Pour quelques centaines d'éléments qu'une seule personne étiquette une seule fois, un petit script suffit. Dès que l'étude a besoin de plusieurs annotateurs par élément, de formation, de contrôles d'attention, d'accord ou d'une plateforme de crowdsourcing, chacun de ces éléments doit être construit et testé. potato-skill s'appuie sur Potato, qui les a déjà, et la tâche qu'il produit peut être relancée et partagée.

Puis-je modifier ce qu'il construit ?

Oui. La sortie est une tâche Potato ordinaire, un dossier contenant une configuration, des données et des consignes. Modifiez-la à la main avec le démarrage rapide et les bases de la configuration, ou demandez à l'agent de la changer.

Combien ça coûte ?

Rien. Potato est libre et open source, et potato-skill est publié sous licence GPL-3.0-or-later. Vous payez pour l'agent de coding que vous utilisez déjà, et pour les annotateurs si vous en recrutez.

Qu'est-ce que Potato ?

Potato est un outil d'annotation open source de l'Université du Michigan, décrit dans une démonstration système ACL 2026. Il prend en charge 61 types d'annotation sur du texte, des images, de l'audio, de la vidéo, du dialogue et des traces d'agents.

Pour aller plus loin

• Démarrage rapide avec un agent de coding, qui détaille davantage l'installation
• potato-skill sur GitHub, actuellement en v1.0.1
• Le matériel de référence du skill
• La vitrine, pour un design proche de votre étude

Références

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/