potato-skill: costruire uno studio di annotazione con un coding agent
Descrivi a Claude Code, Codex o Cursor che cosa vuoi etichettare: potato-skill progetta lo studio, lo costruisce in Potato e verifica che si renderizzi.
Puoi avviare un progetto Potato in due modi. Scrivi il task da solo, come mostra la Guida rapida, oppure descrivi lo studio a un coding agent e lascia che potato-skill lo progetti e lo costruisca. Questa pagina tratta la seconda strada. Entrambe portano allo stesso punto: un task di annotazione Potato che puoi eseguire, modificare e condividere.
Che cosa decide la skill
potato-skill è una skill per agenti, un pacchetto di istruzioni e script di supporto che un coding agent carica quando una richiesta ne ha bisogno. Contiene 28 file di riferimento e nove script di supporto, e copre sia la progettazione dello studio sia la costruzione:
- che cosa chiedere agli annotatori, e su quale scala
- quanti annotatori servono per ogni item
- come addestrare gli annotatori e controllarne il lavoro
- l'interfaccia che vedono gli annotatori
- esportare i risultati nel formato che serve al passaggio successivo
Alcune di queste decisioni le prende da sola, altre te le rimanda. La regola che segue è che 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. Assume una scala a 5 punti con ogni punto etichettato, scorciatoie da tastiera su ogni domanda con nove etichette o meno, ordine casuale degli item con un random_seed fisso e tutte le domande obbligatorie. Chiede a te l'unità di annotazione, il numero di annotatori per item quando l'accordo verrà riportato, il testo del consenso informato e qualsiasi insieme di etichette senza un'opzione "non chiaro".
Il task che costruisce gira su Potato, quindi ha ciò che Potato fa già: un accesso per ogni annotatore, più annotatori per item, statistiche di accordo, integrazione con Prolific e SONA ed esportazione nei formati letti dagli strumenti a valle.
Requisiti
Potato va installato dove l'agente esegue i comandi, perché gli script di supporto della skill importano i registri di Potato e pilotano il comando potato:
pip install potato-annotationTi serve anche un coding agent. La skill è stata scritta per Claude Code, e si installa anche in Codex e Cursor.
Installare la skill
In Claude Code si installa dal marketplace di plugin:
/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potatoPer Codex e Cursor, la CLI skills la installa nel progetto su cui stai lavorando:
npx skills add davidjurgens/potato-skill --agent codex cursorCosa 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.
Descrivere lo studio
Di' che cosa va etichettato, chi lo etichetterà e a cosa servono le etichette. Non serve conoscere i tipi di annotazione di Potato né il formato del suo config. Una richiesta può essere breve così:
Voglio che tre annotatori etichettino ciascuno 200 tweet per sentiment su una scala a 5 punti, con una pagina di consenso e due controlli di attenzione. Costruiscilo e avvialo.
La skill stabilisce la formulazione delle domande, la scala, il modo in cui vengono assegnati gli item e come vengono controllati gli annotatori. Non si ferma ad aspettare le risposte alle domande che vuole farti confermare: dichiara le proprie assunzioni, costruisce il task, lo verifica e pone le domande accanto a qualcosa che puoi già usare cliccando.
Controlli che l'agente esegue 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. 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, e intercetta così un refuso che altrimenti lascerebbe una funzionalità spenta senza dirlo. --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.
Tre dei nove script di supporto automatizzano le parti che si possono misurare anziché giudicare. check_ui.py misura il layout dal vivo e segnala schemi o un pulsante Next sotto la piega, widget multimediali vuoti e scorciatoie duplicate. boot_and_check.py segnala ogni funzionalità configurata che non ha caricato nulla. walk_task.py percorre un task in esecuzione come farebbe un annotatore e segnala dove si blocca.
Apri il task nel browser ed etichetta tu stesso qualche item prima di invitare altre persone.
Il task che produce
Un task Potato è una cartella di progetto che contiene il config del task, i suoi dati e le sue istruzioni. Tutto ciò che sta nella Guida rapida vale anche per lui. Lo avvii con potato start config.yaml, lo modifichi a mano, aggiungi annotatori ed esporti le etichette.
Poiché il risultato è una cartella di task Potato, anche altre persone possono usarlo. Un collega può eseguire lo stesso studio su dati nuovi, tu puoi ripeterlo l'anno prossimo e pubblicarlo insieme all'articolo che lo ha usato. La vetrina è una raccolta di task condivisi in questo modo, tratti da articoli pubblicati.
Design e annotazioni esistenti
- Un design pubblicato. La skill può partire da uno dei 440 design di annotazione tratti da articoli pubblicati, con i loro insiemi di etichette, la formulazione delle domande e le istruzioni. Puoi sfogliarli nella vetrina, e
find_design.pyli interroga per trovare un design vicino a quello che hai descritto. - Annotazioni da un altro strumento.
potato importlegge 20 formati, tra cui Labelbox, CVAT e COCO, quindi un progetto a metà può proseguire in Potato. - Uno studio già in corso.
study_status.pyriporta l'avanzamento di ciascun annotatore e l'accordo su ogni domanda, e la skill dice quali correzioni sono sicure a studio avviato e quali corromperebbero i dati già raccolti.
I server MCP di Potato
Un agente può ottenere le stesse risposte via MCP invece che 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.
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 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.
Il suo materiale di riferimento è pubblicato su davidjurgens.github.io/potato-skill, leggibile senza installare nulla. Anthropic raccomanda di rivedere qualsiasi skill prima di installarla.
Le due strade a confronto
Le due strade differiscono in ciò da cui parti, non in ciò che ottieni:
| Scrivere il task da solo | Descriverlo a un coding agent | |
|---|---|---|
| Parti da | un config YAML | una descrizione in linguaggio comune |
| Adatto per | imparare Potato, task piccoli | studi nuovi, studi in crowdsourcing con addestramento e controlli, tipi di annotazione che non hai mai usato |
| Ottieni | un task Potato | un task Potato |
Puoi cambiare strada in qualsiasi momento. Un agente può modificare un task che hai scritto tu, e tu puoi modificare quello costruito dall'agente.
Domande
Le domande che seguono riguardano come configurare potato-skill con un coding agent e dove trovarne il codice sorgente.
Come uso Potato con un coding agent?
Installa Potato e potato-skill dove l'agente esegue i comandi, poi descrivi lo studio all'agente in linguaggio comune. pip install potato-annotation installa Potato. In Claude Code, /plugin marketplace add davidjurgens/potato-skill seguito da /plugin install potato-skill@potato installa la skill, e in Codex o Cursor lo fa npx skills add davidjurgens/potato-skill --agent codex cursor. Di' all'agente che cosa va etichettato, chi lo etichetterà e a cosa servono le etichette. potato-skill costruisce il task, lo renderizza per verificare che funzioni e ti restituisce l'elenco delle decisioni che ha preso al posto tuo.
Dove si trova potato-skill su GitHub?
potato-skill si trova su github.com/davidjurgens/potato-skill, distribuita con licenza GPL-3.0-or-later. Il suo materiale di riferimento è pubblicato su davidjurgens.github.io/potato-skill, quindi puoi leggere che cosa la skill dice all'agente prima di installarla.