potato-skill: costruisci uno studio di annotazione con Claude Code, Codex o Cursor

potato-skill trasforma la descrizione a parole di uno studio di annotazione in un task Potato funzionante. Contiene 28 file di riferimento e nove script di supporto che coprono le decisioni di progettazione precedenti al config, l'interfaccia che vede l'annotatore e i controlli che intercettano un task valido ma inutilizzabile. Si installa in Claude Code, Codex e Cursor, ed è distribuito con licenza GPL-3.0-or-later.

Installare la skill

Claude Code la installa da un marketplace di plugin, con due comandi:

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

Codex e Cursor la installano con la CLI skills, che copia la skill nel progetto su cui stai lavorando:

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

Potato va installato dove l'agente esegue i comandi, perché i nove script di supporto importano i suoi registri e pilotano il comando potato:

pip install potato-annotation

Cosa comprende un'installazione su Codex o Cursor

La CLI skills scrive .agents/skills/potato-skill/ con SKILL.md, tutti i 28 riferimenti e tutti e nove gli script, quindi un progetto Codex o Cursor riceve lo stesso materiale di un'installazione su Claude Code. Non tocca AGENTS.md né .cursor/rules, e il modo in cui ciascuno strumento individua una skill in quella directory dipende dallo strumento.

Il repository contiene anche un AGENTS.md nella radice, che Codex e Cursor leggono dal nome del file senza alcuna installazione. È un riassunto breve a fronte di circa 79.000 parole distribuite sui riferimenti, e rimanda a file di riferimento e script che solo un'installazione completa mette su disco. Usalo quando vuoi dare a un agente il ciclo di verifica prima della consegna e le regole che contano davvero, e usa la CLI skills quando vuoi il materiale di riferimento che sta dietro a quelle regole.

Impostazioni predefinite che la skill applica senza chiedere

Una decisione viene presa sul posto quando sbagliare costa poco da correggere, e viene rimandata a te quando sbagliare costa caro, è irreversibile o non spetta all'agente. Cambiare una scorciatoia da tastiera non costa nulla, mentre rifare 5.000 item perché l'unità di annotazione era sbagliata si mangia il budget dello studio. Queste sono le impostazioni che assume, e che elenca una per una come assunzioni al momento della consegna:

Decisioni che rimanda a te

Cinque decisioni tornano al ricercatore in un unico messaggio raggruppato, ciascuna con una risposta proposta, così da poterla accettare con una parola:

• L'unità di annotazione, quando i dati non la determinano. Un file di paragrafi in cui la domanda riguarda in realtà le frasi è un bivio nello studio, e l'una o l'altra scelta può costringere a rifarlo.
• Annotatori per item, quando l'accordo tra annotatori verrà riportato. Tre annotatori costano tre volte uno, quindi la skill propone un numero motivandolo invece di spendere il budget al posto tuo.
• Il testo del consenso informato. Lo abbozza da ciò che hai descritto e dice chiaramente che la bozza va sostituita con il testo approvato dal tuo comitato etico.
• Un insieme di etichette senza un posto dove mettere i casi difficili. Tre etichette senza "non chiaro" e senza "nessuna" di solito sono una svista: gli annotatori finiscono per collocare gli item davvero ambigui in un punto arbitrario, dove nulla a valle può accorgersi che è successo. La skill indica gli item che secondo lei non hanno dove andare.
• Qualsiasi cosa mostri nomi utente, volti o luoghi agli annotatori.

Niente di tutto questo blocca la costruzione. La skill dichiara le proprie assunzioni, costruisce il task, lo verifica e pone le domande accanto a qualcosa che puoi già usare cliccando.

Controlli prima della consegna

Un config valido ti dice che il server si avvierà, e non ti dice nulla su se una persona possa fare il lavoro. Per questo la skill istruisce l'agente a renderizzare il task e a guardarlo:

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

--strict trasforma una chiave di config non riconosciuta da avviso a errore. Senza, un refuso viene accettato, ignorato, e la funzionalità che credevi di aver attivato resta spenta: è la causa abituale di un config che si legge correttamente mentre non succede nulla.

--screenshot avvia un vero server Potato e lo pilota con Playwright in modalità headless, registrando errori di console, eccezioni non gestite della pagina e risposte HTTP da 400 in su. Esce con 0 solo quando tutte e tre le liste sono vuote. Quel passaggio intercetta ciò che la validazione non può vedere, perché quasi tutta l'interfaccia di annotazione viene costruita da JavaScript dopo l'arrivo dell'HTML. Il caso tipico è un radio button invisibile: il testo dell'etichetta viene comunque renderizzato e a prima vista la domanda sembra a posto.

Il ciclo attorno a questi due comandi è indicazione, non automazione. Il materiale di riferimento dice all'agente di fare una modifica per giro, di scrivere ogni render su un nuovo nome di file così che la coppia mostri l'effetto della modifica, e di aspettarsi tre o quattro giri su un layout personalizzato. Gli dice anche che tutto ciò che sta dietro a display_logic è assente dal primo render e che la sua assenza non dimostra nulla, quindi la condizione va commentata, renderizzata e rimessa a posto.

Tre dei nove script di supporto automatizzano le parti che si possono misurare anziché giudicare. check_ui.py misura il layout dal vivo a 1280x900 e segnala schemi o un pulsante Next sotto la piega, widget multimediali vuoti e scorciatoie duplicate. boot_and_check.py avvia il server e segnala ogni funzionalità configurata che non ha caricato nulla, per esempio un round di addestramento che ha caricato zero item di addestramento. walk_task.py percorre un task in esecuzione come farebbe un annotatore e segnala dove si blocca.

Modifiche sicure e non sicure dopo che gli annotatori hanno iniziato

Quasi tutto ciò che va storto in uno studio di annotazione va storto dopo che gli annotatori hanno iniziato, e le modalità di guasto che contano non producono alcun messaggio di errore. La skill ne documenta due.

Rinominare una domanda a studio in corso è la più insidiosa. Nulla dà errore, e tre superfici riportano poi tre cose diverse. Il pannello di amministrazione dice che lo studio è completo al 100%, il report sull'accordo dice che quello schema ha zero item, e l'esportazione CSV riporta il vecchio nome di colonna, perché le esportazioni seguono ciò che è stato salvato e non il config. Un singolo WARNING nel log di avvio è tutta la rete di sicurezza. Aggiungere una domanda ha una versione più silenziosa dello stesso problema, perché Potato traccia il completamento per item e mai per domanda, quindi una domanda aggiunta in seguito non raggiunge mai chi ha già finito il corpus.

L'autenticazione è il secondo caso. Il backend predefinito tiene gli account in memoria, quindi fermare il server porta con sé tutti i login degli annotatori, mentre le annotazioni restano al sicuro su disco. Un annotatore torna, si registra di nuovo con lo stesso nome utente e viene ricollegato al suo lavoro: questo nasconde il problema finché qualcuno non digita un nome utente diverso e ricomincia il corpus come se fosse una seconda persona. Impostare authentication.user_config_path scrive gli account su disco con un hash salato. Conta soprattutto là dove è più facile dimenticarsene, dato che Render e Hugging Face Spaces riavviano i container per conto loro.

Per uno studio già in corso, study_status.py legge le route di amministrazione per avere avanzamento, ritmo di ciascun annotatore, accordo su ogni domanda, chi sta fallendo i controlli di attenzione e chi sta trattenendo item che ha abbandonato. La skill dice poi quali correzioni sono ancora sicure e quali corromperebbero risposte che hai già pagato.

I server MCP di Potato

Potato include due server MCP, che danno a un agente le stesse risposte senza passare dalla shell. potato mcp serve --root . espone 12 strumenti di authoring che leggono gli stessi registri della CLI, tra cui render_task_screenshot, che restituisce la pagina renderizzata come immagine. potato mcp connect fa da ponte verso uno studio in esecuzione e aggiunge 12 strumenti dal vivo su stato, avanzamento, annotatori, accordo, assegnazione ed esportazione. Il ponte richiede un blocco mcp nel config che elenchi gli strumenti da esporre, e un token da potato mcp issue-token.

Strumenti di etichettatura scritti a mano e quanto costano

Un modo comune per far etichettare qualche centinaio di item è chiedere a un coding agent un piccolo strumento di etichettatura, per esempio una pagina Streamlit o Flask che mostra un item alla volta e accoda ogni risposta a un CSV. È una cosa ragionevole da costruire quando una persona etichetta un pomeriggio di dati una volta sola. Il costo arriva quando lo studio richiede un login per annotatore, tre annotatori per item con ciascun item instradato alle persone giuste, un round di addestramento e controlli di attenzione, statistiche di accordo, un codice di completamento per Prolific, un'esportazione nel formato che si aspetta lo script successivo, o un secondo studio il mese prossimo che funzioni allo stesso modo. Ognuna di queste è una funzionalità che qualcuno scrive, testa e debugga dentro uno strumento costruito per un solo studio, e Potato le ha già tutte.

I due differiscono anche in ciò che sopravvive allo studio. Uno strumento di etichettatura scritto a mano è di solito legato a un dataset in un repository, mentre un task Potato è una cartella con un config e dei dati che chiunque abbia Potato può avviare. La vetrina ne raccoglie più di 400, la maggior parte tratti da articoli pubblicati, e find_design.py la interroga per trovare un design vicino a quello che hai descritto.

Studi che la skill imposta

Cinque casi mostrano la varietà, ciascuno a partire da una descrizione breve e con un task eseguibile come risultato:

• Etichette di stance da crowdworker. Tre annotatori per post, un round di addestramento, controlli di attenzione, un codice di completamento Prolific e l'accordo una volta raccolte le etichette. Vedi crowdsourcing su Prolific e MTurk e misurare l'accordo tra annotatori.
• Confrontare due risposte di chatbot. Un layout affiancato con una scala di preferenza e una motivazione a testo libero. Vedi confronto pairwise tra modelli e dati di preferenza per RLHF.
• Segnare il passo fallito in una traccia di agente. La traccia viene presentata un passo alla volta, e il task registra il passo segnato dall'annotatore e la sua spiegazione. Vedi annotazione di traiettorie di agenti.
• Proseguire un progetto CVAT. potato import legge 20 formati, quindi i bounding box esistenti entrano con le loro etichette, e lo studio esporta di nuovo in COCO. Vedi misurare l'accordo sui bounding box.
• Due codificatori e un codebook. Il codebook diventa l'interfaccia di codifica, a entrambi i codificatori viene assegnata ogni risposta, e un passo di adjudication gestisce i disaccordi. Vedi adjudication e disaccordo.

Test contro i registri di Potato

Un identificatore sbagliato ma plausibile è peggio di nessuna documentazione, perché un agente lo userà. Tre dei 28 riferimenti sono quindi generati dai registri di Potato stesso e non possono divergere da ciò che il server applica: tutti i 61 tipi di annotazione, ciascuno con un esempio pratico preso da un progetto reale, le chiavi di config di primo livello documentate e le sotto-chiavi documentate.

La CI copre i file principali della skill e verifica che ogni tipo di annotazione, tipo di display, chiave di config, operatore, nome di strategia e comando citato in essi esista in Potato. Ogni campione YAML viene innestato in un config funzionante e passato per il vero validatore di Potato, e l'esempio pratico avvia un server reale in cui ogni funzionalità che attiva deve riportare un conteggio diverso da zero nel log.

Il materiale di riferimento è pubblicato su davidjurgens.github.io/potato-skill, così puoi leggere cosa la skill dice all'agente prima di installarla. Anthropic raccomanda di rivedere qualsiasi skill prima dell'uso.

Domande

Devo già conoscere Potato?

No. Descrivi lo studio in linguaggio naturale, e Potato deve essere installato sulla macchina dove l'agente esegue i comandi. Prima che gli annotatori vedano il task, aprilo in un browser ed etichetta tu stesso qualche item.

Posso usare potato-skill con Codex o Cursor?

Sì, per entrambe le strade. npx skills add davidjurgens/potato-skill --agent codex cursor mette la skill completa nel progetto, e l'AGENTS.md del repository ne offre una versione più breve senza alcuna installazione. La skill è stata scritta per Claude Code, dove si trova l'installazione dal marketplace.

Conviene invece far costruire al mio coding agent uno strumento di annotazione su misura?

Per qualche centinaio di item etichettati una volta sola da una persona, basta uno script piccolo. Quando lo studio richiede più annotatori per item, addestramento, controlli di attenzione, accordo o una piattaforma di crowdsourcing, ognuna di queste cose va costruita e testata. potato-skill si appoggia a Potato, che le ha già, e il task che produce può essere rieseguito e condiviso.

Posso modificare ciò che costruisce?

Sì. Il risultato è un normale task Potato: una cartella con un config, i dati e le istruzioni. Modificalo a mano con la Guida rapida e le basi della configurazione, oppure chiedi all'agente di cambiarlo.

Quanto costa?

Nulla. Potato è gratuito e open source, e potato-skill è distribuito con licenza GPL-3.0-or-later. Paghi il coding agent che già usi, e gli annotatori se li recluti.

Che cos'è Potato?

Potato è uno strumento di annotazione open source dell'Università del Michigan, descritto in una system demonstration ad ACL 2026. Supporta 61 tipi di annotazione su testo, immagini, audio, video, dialoghi e tracce di agenti.

Letture consigliate

• Guida rapida con un coding agent, che tratta la configurazione più nel dettaglio
• potato-skill su GitHub, attualmente alla v1.0.1
• Il materiale di riferimento della skill
• La vetrina, per un design vicino al tuo studio

Riferimenti

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/