potato-skill: Eine Annotationsstudie mit Claude Code, Codex oder Cursor aufbauen

potato-skill macht aus einer schlichten Beschreibung einer Annotationsstudie eine laufende Potato-Aufgabe. Er bringt 28 Referenzdateien und neun Hilfsskripte mit, die die Designentscheidungen vor der Konfiguration abdecken, die Oberfläche, die der Annotator sieht, und die Prüfungen, die eine Aufgabe auffangen, die zwar validiert, aber nicht funktioniert. Er installiert sich in Claude Code, Codex und Cursor und ist unter der GPL-3.0-or-later veröffentlicht.

Den Skill installieren

Claude Code installiert ihn mit zwei Befehlen aus einem Plugin-Marketplace:

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

Codex und Cursor installieren ihn über das skills-CLI, das den Skill in das Projekt kopiert, an dem Sie gerade arbeiten:

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

Potato selbst muss dort installiert sein, wo der Agent Befehle ausführt, denn die neun Hilfsskripte importieren seine Registries und steuern den potato-Befehl:

pip install potato-annotation

Was eine Installation für Codex oder Cursor enthält

Das skills-CLI legt .agents/skills/potato-skill/ mit SKILL.md, allen 28 Referenzen und allen neun Skripten an, sodass ein Codex- oder Cursor-Projekt dasselbe Material bekommt wie eine Installation in Claude Code. AGENTS.md und .cursor/rules bleiben unangetastet, und wie das jeweilige Werkzeug einen Skill in diesem Verzeichnis findet, bleibt dem Werkzeug überlassen.

Im Wurzelverzeichnis des Repositorys liegt außerdem eine AGENTS.md, die Codex und Cursor allein am Dateinamen erkennen, ganz ohne Installationsschritt. Diese Datei fasst kurz zusammen, was über die Referenzen hinweg rund 79.000 Wörter umfasst, und sie verweist auf Referenzdateien und Skripte, die erst eine vollständige Installation auf die Platte legt. Nehmen Sie sie, wenn ein Agent die Prüfschleife vor der Übergabe und die Regeln bekommen soll, die wirklich greifen, und nehmen Sie das skills-CLI, wenn Sie das Referenzmaterial dahinter wollen.

Voreinstellungen, die der Skill ohne Rückfrage setzt

Eine Entscheidung fällt vor Ort, wenn ein Fehler billig zu beheben ist, und geht zurück, wenn ein Fehler teuer, nicht umkehrbar oder nicht Sache des Agenten ist. Ein Tastenkürzel zu ändern kostet nichts, während 5.000 Items noch einmal durchlaufen zu lassen, weil die Annotationseinheit falsch war, das Budget der Studie kostet. Das sind die Voreinstellungen, die er trifft, und jede davon führt er bei der Übergabe der Aufgabe als Annahme auf:

Entscheidungen, die er an Sie zurückgibt

Fünf Entscheidungen gehen in einer gebündelten Nachricht an die Forscherin oder den Forscher zurück, jede mit einem Vorschlag, sodass sie sich mit einem Wort annehmen lässt:

• Die Annotationseinheit, wenn die Daten sie nicht festlegen. Eine Datei aus Absätzen, bei der die Frage eigentlich Sätze betrifft, ist eine Weggabelung in der Studie, und beide Wege können bedeuten, dass sie neu laufen muss.
• Annotatoren pro Item, wenn Übereinstimmung berichtet werden soll. Drei Annotatoren kosten dreimal so viel wie einer, deshalb schlägt der Skill eine Zahl mit Begründung vor, statt Ihr Budget für Sie auszugeben.
• Der Wortlaut der Einwilligung. Er entwirft ihn aus dem, was Sie beschrieben haben, und sagt klar, dass der Entwurf durch den Text ersetzt werden muss, den Ihre Ethikkommission genehmigt hat.
• Ein Labelsatz ohne Platz für die schwierigen Fälle. Drei Label ohne "unklar" und ohne "keines" sind meist ein Versehen, und Annotatoren legen echte Grenzfälle dann irgendwo ab, wo nachgelagert niemand sehen kann, dass es passiert ist. Der Skill benennt die Items, für die es seiner Ansicht nach keinen Platz gibt.
• Alles, was Annotatoren Benutzernamen, Gesichter oder Orte zeigt.

Nichts davon blockiert den Aufbau. Der Skill nennt seine Annahmen, baut die Aufgabe, prüft sie und stellt die Fragen zusammen mit etwas, das Sie bereits durchklicken können.

Prüfungen vor der Übergabe

Eine Konfiguration, die validiert, sagt Ihnen, dass der Server startet, und sagt nichts darüber, ob ein Mensch die Arbeit erledigen kann. Deshalb weist der Skill den Agenten an, die Aufgabe zu rendern und sie anzusehen:

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

--strict macht aus einem unbekannten Konfigurationsschlüssel statt einer Warnung einen Fehler. Ohne die Option wird ein Tippfehler angenommen und ignoriert, und das Feature, das Sie eingeschaltet glaubten, bleibt aus. Das ist die übliche Ursache für eine Konfiguration, die sich richtig liest, während nichts passiert.

--screenshot startet einen echten Potato-Server und steuert ihn in einem headless laufenden Playwright, wobei Konsolenfehler, nicht abgefangene Page Exceptions und HTTP-Antworten ab 400 aufgezeichnet werden. Der Befehl endet nur dann mit 0, wenn alle drei Listen leer sind. Dieser Schritt fängt ab, was die Validierung nicht sehen kann, denn der größte Teil der Annotationsoberfläche wird von JavaScript gebaut, nachdem das HTML angekommen ist. Ein unsichtbarer Radio-Button ist der Standardfall, weil der Labeltext trotzdem rendert und die Frage auf den ersten Blick richtig aussieht.

Der Zyklus um diese beiden Befehle ist Anleitung und keine Automatisierung. Das Referenzmaterial sagt dem Agenten, pro Runde eine Änderung zu machen, jedes Rendering in einen neuen Dateinamen zu schreiben, damit das Paar zeigt, was die Änderung bewirkt hat, und bei einem eigenen Layout mit drei oder vier Runden zu rechnen. Es sagt dem Agenten außerdem, dass alles hinter display_logic im ersten Rendering fehlt und dass dieses Fehlen nichts beweist, weshalb die Bedingung auskommentiert, gerendert und wieder eingesetzt wird.

Drei der neun Hilfsskripte automatisieren die Teile, die sich messen statt beurteilen lassen. check_ui.py vermisst das Live-Layout bei 1280x900 und meldet Schemata oder einen Next-Button unterhalb des sichtbaren Bereichs, leere Medien-Widgets und doppelte Tastenkürzel. boot_and_check.py startet den Server und meldet jedes Feature, das konfiguriert ist, aber nichts geladen hat, etwa eine Trainingsrunde, die null Trainings-Items geladen hat. walk_task.py durchläuft eine laufende Aufgabe so, wie ein Annotator es täte, und meldet, wo sie stehen bleibt.

Sichere und unsichere Änderungen, nachdem Annotatoren begonnen haben

Das meiste, was in einer Annotationsstudie schiefgeht, geht schief, nachdem die Annotatoren begonnen haben, und die Fehlerbilder, auf die es ankommt, erzeugen keine Fehlermeldung. Der Skill behandelt zwei davon.

Eine Frage mitten in der Studie umzubenennen ist der schärfste Fall. Nichts wirft einen Fehler, und drei Stellen berichten danach drei verschiedene Dinge. Die Admin-Übersicht sagt, die Studie sei zu 100 % abgeschlossen, der Übereinstimmungsbericht sagt, dieses Schema habe null Items, und der CSV-Export trägt den alten Spaltennamen, weil sich Exporte danach richten, was gespeichert wurde, und nicht nach der Konfiguration. Eine einzige WARNING im Boot-Log ist das gesamte Sicherheitsnetz. Eine Frage hinzuzufügen hat eine leisere Variante desselben Problems, denn Potato verfolgt den Fortschritt pro Item und nie pro Frage, sodass eine später hinzugefügte Frage nie bei jemandem ankommt, der das Korpus bereits abgeschlossen hat.

Die Authentifizierung ist der zweite Fall. Das Standard-Backend hält Konten im Arbeitsspeicher, sodass ein Stopp des Servers alle Annotator-Logins mitnimmt, während die Annotationen sicher auf der Platte bleiben. Ein Annotator kommt zurück, registriert sich unter demselben Benutzernamen neu und wird wieder mit seiner Arbeit verbunden, was das Problem verdeckt, bis jemand einen anderen Benutzernamen eintippt und das Korpus als zweite Person von vorn beginnt. Wird authentication.user_config_path gesetzt, werden Konten mit gesalzenem Hash herausgeschrieben. Am wichtigsten ist das dort, wo man es am leichtesten vergisst, denn Render und Hugging Face Spaces starten Container von sich aus neu.

Für eine bereits laufende Studie liest study_status.py die Admin-Routen aus und liefert Fortschritt, Raten pro Annotator, Übereinstimmung zu jeder Frage, wer die Aufmerksamkeitstests nicht besteht und wer auf Items sitzt, die er abgebrochen hat. Der Skill sagt dann, welche Korrekturen noch sicher sind und welche Antworten beschädigen würden, für die Sie bereits bezahlt haben.

Potatos MCP-Server

Potato liefert zwei MCP-Server mit, die einem Agenten dieselben Antworten geben, ohne dass er auf die Shell ausweichen muss. potato mcp serve --root . stellt 12 Authoring-Tools bereit, die dieselben Registries lesen wie das CLI, darunter render_task_screenshot, das die gerenderte Seite als Bild zurückgibt. potato mcp connect schlägt eine Brücke zu einer laufenden Studie und ergänzt 12 Live-Tools für Status, Fortschritt, Annotatoren, Übereinstimmung, Zuweisung und Export. Die Brücke braucht einen mcp-Block in der Konfiguration, der die freizugebenden Tools auflistet, und ein Token aus potato mcp issue-token.

Handgeschriebene Labeling-Werkzeuge und was sie kosten

Ein verbreiteter Weg, ein paar hundert Items labeln zu lassen, besteht darin, einen Coding-Agenten um ein schnelles Labeling-Werkzeug zu bitten, etwa eine Streamlit- oder Flask-Seite, die ein Item nach dem anderen zeigt und jede Antwort an eine CSV-Datei anhängt. Das zu bauen ist vernünftig, wenn eine Person einmalig einen Nachmittag lang Daten labelt. Die Kosten kommen, wenn die Studie ein Login pro Annotator braucht, drei Annotatoren pro Item mit einer Zuweisung jedes Items an die richtigen Leute, eine Trainingsrunde und Aufmerksamkeitstests, Übereinstimmungsstatistiken, einen Completion Code für Prolific, einen Export in dem Format, das das nächste Skript erwartet, oder nächsten Monat eine zweite Studie, die genauso funktioniert. Jedes davon ist ein Feature, das jemand schreibt, testet und debuggt, und zwar in einem Werkzeug, das für eine einzige Studie gebaut wurde. Potato hat sie alle bereits.

Die beiden unterscheiden sich auch darin, was die Studie überdauert. Ein handgeschriebenes Labeling-Werkzeug hängt meist an einem Datensatz in einem Repository, während eine Potato-Aufgabe ein Ordner mit einer Konfiguration und Daten ist, den jeder mit Potato starten kann. Der Showcase enthält mehr als 400 davon, die meisten aus veröffentlichten Arbeiten, und find_design.py durchsucht ihn nach einem Design, das dem von Ihnen beschriebenen nahekommt.

Studien, die der Skill aufsetzt

Fünf Fälle zeigen die Bandbreite, jeder beginnt mit einer kurzen Beschreibung und endet in einer lauffähigen Aufgabe:

• Stance-Label von Crowdworkern. Drei Annotatoren pro Beitrag, eine Trainingsrunde, Aufmerksamkeitstests, ein Completion Code für Prolific und Übereinstimmung, sobald die Label vorliegen. Siehe Crowdsourcing auf Prolific und MTurk und Übereinstimmung zwischen Annotatoren messen.
• Zwei Chatbot-Antworten vergleichen. Ein Layout mit zwei Antworten nebeneinander, einer Präferenzskala und einer Freitextbegründung. Siehe paarweiser Modellvergleich und RLHF-Präferenzdaten.
• Den fehlgeschlagenen Schritt in einem Agent-Trace markieren. Der Trace wird Schritt für Schritt ausgelegt, und die Aufgabe hält fest, welchen Schritt der Annotator markiert hat und wie er es begründet. Siehe Annotation von Agent-Trajektorien.
• Ein CVAT-Projekt fortführen. potato import liest 20 Formate, sodass vorhandene Boxen mit ihren Labeln hereinkommen, und die Studie exportiert wieder als COCO. Siehe Übereinstimmung bei Bounding Boxes messen.
• Zwei Codierer und ein Codebuch. Das Codebuch wird zur Codieroberfläche, beiden Codierern wird jede Antwort zugewiesen, und ein Adjudikationsschritt löst die Uneinigkeiten auf. Siehe Adjudikation und Uneinigkeit.

Tests gegen Potatos Registries

Ein plausibler falscher Bezeichner ist schlimmer als gar keine Dokumentation, weil ein Agent ihn benutzen wird. Drei der 28 Referenzen werden deshalb aus Potatos eigenen Registries erzeugt und können nicht von dem abweichen, was der Server durchsetzt: alle 61 Annotationstypen, jeder mit einem ausgearbeiteten Beispiel aus einem echten Projekt, die dokumentierten Konfigurationsschlüssel auf oberster Ebene und die dokumentierten Unterschlüssel.

Die CI deckt die Kerndateien des Skills ab und prüft, dass jeder Annotationstyp, Anzeigetyp, Konfigurationsschlüssel, Operator, Strategiename und Befehl, der darin genannt wird, in Potato existiert. Jedes YAML-Beispiel wird in eine funktionierende Konfiguration eingesetzt und durch Potatos echten Validator geschickt, und das ausgearbeitete Beispiel startet einen echten Server, in dem jedes Feature, das es einschaltet, im Log eine Zahl größer null melden muss.

Das Referenzmaterial ist unter davidjurgens.github.io/potato-skill veröffentlicht, sodass Sie vor der Installation nachlesen können, was der Skill dem Agenten sagt. Anthropic empfiehlt, jeden Skill vorher zu prüfen.

Fragen

Muss ich Potato vorher kennen?

Nein. Sie beschreiben die Studie in normaler Sprache, und Potato muss auf der Maschine installiert sein, auf der der Agent Befehle ausführt. Bevor Annotatoren die Aufgabe sehen, öffnen Sie sie im Browser und labeln Sie selbst ein paar Items.

Kann ich potato-skill mit Codex oder Cursor verwenden?

Ja, auf beiden Wegen. npx skills add davidjurgens/potato-skill --agent codex cursor legt den vollständigen Skill ins Projekt, und die AGENTS.md des Repositorys liefert ganz ohne Installation eine kürzere Fassung. Geschrieben wurde der Skill für Claude Code, dort liegt auch die Installation über den Marketplace.

Sollte mein Coding-Agent stattdessen ein eigenes Annotationswerkzeug bauen?

Für ein paar hundert Items, die eine Person einmal labelt, reicht ein kleines Skript. Sobald die Studie mehrere Annotatoren pro Item, Training, Aufmerksamkeitstests, Übereinstimmung oder eine Crowdsourcing-Plattform braucht, muss jedes davon gebaut und getestet werden. potato-skill setzt auf Potato auf, das all das bereits hat, und die erzeugte Aufgabe lässt sich erneut ausführen und weitergeben.

Kann ich ändern, was er baut?

Ja. Das Ergebnis ist eine gewöhnliche Potato-Aufgabe, ein Ordner mit Konfiguration, Daten und Anleitung. Bearbeiten Sie sie von Hand mit dem Schnellstart und den Grundlagen der Konfiguration, oder lassen Sie den Agenten sie ändern.

Was kostet das?

Nichts. Potato ist kostenlos und quelloffen, und potato-skill ist unter der GPL-3.0-or-later veröffentlicht. Sie zahlen für den Coding-Agenten, den Sie ohnehin nutzen, und für Annotatoren, wenn Sie welche anwerben.

Was ist Potato?

Potato ist ein quelloffenes Annotationswerkzeug der University of Michigan, beschrieben in einer ACL-2026-Systemdemonstration. Es unterstützt 61 Annotationstypen über Text, Bilder, Audio, Video, Dialoge und Agent-Traces hinweg.

Weiterführende Lektüre

• Schnellstart mit einem Coding-Agenten, mit mehr Details zur Einrichtung
• potato-skill auf GitHub, derzeit bei v1.0.1
• Das Referenzmaterial des Skills
• Der Showcase, für ein Design nahe an Ihrer Studie

Literatur

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/