potato-skill: crie um estudo de anotação com Claude Code, Codex ou Cursor

O potato-skill transforma a descrição em linguagem comum de um estudo de anotação em uma tarefa do Potato em funcionamento. Ele traz 28 arquivos de referência e nove scripts auxiliares que cobrem as decisões de design que vêm antes do config, a interface que o anotador vê e as verificações que pegam uma tarefa que valida mas não funciona. Instala no Claude Code, no Codex e no Cursor, e é publicado sob a GPL-3.0-or-later.

Instalando a skill

O Claude Code instala a skill a partir de um marketplace de plugins, em dois comandos:

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

Codex e Cursor instalam com a CLI skills, que copia a skill para dentro do projeto em que você está trabalhando:

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

O próprio Potato precisa estar instalado onde quer que o agente execute comandos, porque os nove scripts auxiliares importam os registros dele e acionam o comando potato:

pip install potato-annotation

O que uma instalação no Codex ou no Cursor inclui

A CLI skills escreve .agents/skills/potato-skill/ com o SKILL.md, todas as 28 referências e todos os nove scripts, então um projeto de Codex ou Cursor recebe o mesmo material que uma instalação no Claude Code. Ela não mexe no AGENTS.md nem no .cursor/rules, e como cada ferramenta descobre uma skill nesse diretório é problema da ferramenta.

O repositório também traz um AGENTS.md na raiz, que Codex e Cursor leem pelo nome do arquivo, sem nenhum passo de instalação. Esse arquivo é um resumo curto diante de cerca de 79.000 palavras espalhadas pelas referências, e aponta para arquivos de referência e scripts que só uma instalação completa coloca em disco. Use-o quando quiser que um agente tenha o ciclo de verificar antes de entregar e as regras que realmente mordem, e use a CLI skills quando quiser o material de referência por trás delas.

Padrões que a skill adota sem perguntar

Uma decisão é tomada na hora quando errar é barato de consertar, e devolvida quando errar é caro, irreversível ou não cabe ao agente. Mudar um atalho de teclado não custa nada, enquanto refazer 5.000 itens porque a unidade de anotação estava errada consome o orçamento do estudo. Estes são os padrões que ele adota, e cada um é declarado como pressuposto na hora de entregar a tarefa:

Decisões que ele devolve para você

Cinco decisões voltam para o pesquisador em uma única mensagem agrupada, cada uma com uma resposta proposta, para que possa ser aceita em uma palavra:

• A unidade de anotação, quando os dados não resolvem isso. Um arquivo de parágrafos em que a pergunta é na verdade sobre sentenças é uma bifurcação do estudo, e qualquer uma das escolhas pode obrigar a refazê-lo.
• Anotadores por item, quando a concordância vai ser reportada. Três anotadores custam o triplo de um, então a skill propõe um número com o motivo em vez de gastar o seu orçamento por você.
• A redação do termo de consentimento. Ela escreve um rascunho a partir do que você descreveu e diz com todas as letras que o rascunho precisa ser substituído pelo texto aprovado pelo seu comitê de ética.
• Um conjunto de rótulos sem lugar para os casos difíceis. Três rótulos sem um "indefinido" e sem um "nenhum" costuma ser um descuido, e aí os anotadores colocam os itens genuinamente ambíguos em algum lugar arbitrário, onde nada mais adiante consegue ver que isso aconteceu. A skill aponta os itens que acha que não têm para onde ir.
• Qualquer coisa que mostre nomes de usuário, rostos ou localizações para os anotadores.

Nada disso bloqueia a construção. A skill declara seus pressupostos, monta a tarefa, verifica e faz as perguntas junto com algo em que você já pode clicar.

Verificações antes da entrega

Um config que valida diz que o servidor vai subir, e não diz nada sobre se uma pessoa consegue fazer o trabalho. Então a skill instrui o agente a renderizar a tarefa e olhar para ela:

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

O --strict transforma uma chave de configuração não reconhecida de aviso em falha. Sem ele, um erro de digitação é aceito, ignorado, e o recurso que você achava que tinha ativado continua desligado, que é a causa comum de um config que lê corretamente enquanto nada acontece.

O --screenshot sobe um servidor Potato de verdade e o conduz com Playwright em modo headless, registrando erros de console, exceções não capturadas da página e respostas HTTP de 400 para cima. Ele sai com 0 apenas quando as três listas estão vazias. Esse passo pega o que a validação não consegue, porque a maior parte da interface de anotação é construída por JavaScript depois que o HTML chega. Um botão de rádio invisível é o caso clássico, já que o texto do rótulo renderiza mesmo assim e a pergunta parece certa à primeira vista.

O ciclo em torno desses dois comandos é orientação, não automação. O material de referência manda o agente fazer uma mudança por rodada, escrever cada renderização em um nome de arquivo novo para que o par mostre o que a mudança fez, e esperar três ou quatro rodadas em um layout customizado. Também diz ao agente que tudo que está atrás de display_logic não aparece na primeira renderização e que essa ausência não prova nada, então a condição é comentada, renderizada e recolocada.

Três dos nove scripts auxiliares automatizam as partes que dá para medir em vez de julgar. O check_ui.py mede o layout ao vivo em 1280x900 e reporta schemes ou um botão Next abaixo da dobra, widgets de mídia vazios e atalhos duplicados. O boot_and_check.py sobe o servidor e reporta cada recurso que está configurado mas não carregou nada, como uma rodada de treinamento que carregou zero itens de treinamento. O walk_task.py percorre uma tarefa em execução do jeito que um anotador faria e reporta onde ela trava.

Mudanças seguras e inseguras depois que os anotadores começam

A maior parte do que dá errado em um estudo de anotação dá errado depois que os anotadores já começaram, e as falhas que importam não produzem nenhuma mensagem de erro. A skill cobre duas delas.

Renomear uma pergunta no meio do estudo é a mais afiada. Nada dá erro, e três superfícies passam a reportar três coisas diferentes. O resumo de administração diz que o estudo está 100% completo, o relatório de concordância diz que aquele scheme tem zero itens, e a exportação em CSV carrega o nome antigo da coluna, porque as exportações são guiadas pelo que foi armazenado, e não pelo config. Um único WARNING no log de inicialização é toda a rede de segurança. Adicionar uma pergunta tem uma versão mais silenciosa do mesmo problema, porque o Potato rastreia a conclusão por item e nunca por pergunta, então uma pergunta adicionada depois nunca chega a quem já terminou o corpus.

A autenticação é a segunda. O backend padrão mantém as contas em memória, então parar o servidor leva junto todos os logins dos anotadores, enquanto as anotações continuam seguras em disco. Um anotador volta, se registra de novo com o mesmo nome de usuário e é reconectado ao trabalho dele, o que esconde o problema até que alguém digite um nome de usuário diferente e comece o corpus de novo como uma segunda pessoa. Definir authentication.user_config_path grava as contas em disco com um hash com sal. Isso importa mais justamente onde é mais fácil esquecer, já que Render e Hugging Face Spaces reiniciam contêineres por conta própria.

Para um estudo já em andamento, o study_status.py lê as rotas de administração e traz progresso, ritmo por anotador, concordância em cada pergunta, quem está falhando nas verificações de atenção e quem está sentado em cima de itens que abandonou. A skill então diz quais correções ainda são seguras e quais corromperiam respostas que você já pagou.

Os servidores MCP do Potato

O Potato traz dois servidores MCP, que dão ao agente as mesmas respostas sem precisar sair para o shell. O potato mcp serve --root . expõe 12 ferramentas de autoria que leem os mesmos registros que a CLI, entre elas a render_task_screenshot, que devolve a página renderizada como imagem. O potato mcp connect faz ponte com um estudo em execução e adiciona 12 ferramentas ao vivo, cobrindo status, progresso, anotadores, concordância, atribuição e exportação. A ponte precisa de um bloco mcp no config listando as ferramentas a expor, e de um token do potato mcp issue-token.

Ferramentas de rotulagem feitas à mão e o que elas custam

Uma forma comum de rotular algumas centenas de itens é pedir a um agente de programação uma ferramenta rápida de rotulagem, tipo uma página em Streamlit ou Flask que mostra um item por vez e vai anexando cada resposta a um CSV. É uma coisa razoável de construir quando uma pessoa rotula uma tarde de dados uma única vez. O custo chega quando o estudo precisa de um login por anotador, três anotadores por item com cada item direcionado às pessoas certas, uma rodada de treinamento e verificações de atenção, estatísticas de concordância, um código de conclusão para o Prolific, uma exportação no formato que o próximo script espera, ou um segundo estudo no mês que vem que funcione do mesmo jeito. Cada um desses é um recurso que alguém escreve, testa e depura dentro de uma ferramenta construída para um único estudo, e o Potato já tem todos eles.

As duas também diferem no que sobrevive ao estudo. Uma ferramenta de rotulagem feita à mão costuma estar amarrada a um conjunto de dados dentro de um repositório, enquanto uma tarefa do Potato é uma pasta com um config e dados que qualquer pessoa com o Potato consegue iniciar. O showcase tem mais de 400 delas, a maioria tirada de artigos publicados, e o find_design.py faz busca nele por um design parecido com o que você descreveu.

Estudos que a skill deixa montados

Cinco casos mostram a variedade, cada um partindo de uma descrição curta e terminando em uma tarefa executável:

• Rótulos de posicionamento com crowdworkers. Três anotadores por publicação, uma rodada de treinamento, verificações de atenção, um código de conclusão do Prolific e a concordância depois que os rótulos chegam. Veja crowdsourcing no Prolific e no MTurk e medir a concordância entre anotadores.
• Comparar duas respostas de chatbot. Um layout lado a lado com uma escala de preferência e um motivo em texto livre. Veja comparação pareada de modelos e dados de preferência para RLHF.
• Marcar o passo que falha em um trace de agente. O trace é apresentado um passo por vez, e a tarefa registra o passo que o anotador marcou e a explicação dele. Veja anotação de trajetória de agentes.
• Continuar um projeto do CVAT. O potato import lê 20 formatos, então as caixas existentes entram com seus rótulos, e o estudo exporta de volta como COCO. Veja medir concordância em caixas delimitadoras.
• Dois codificadores e um livro de códigos. O livro de códigos vira a interface de codificação, os dois codificadores recebem todas as respostas, e um passo de adjudicação trata as discordâncias. Veja adjudicação e discordância.

Testes contra os registros do Potato

Um identificador errado mas plausível é pior do que documentação nenhuma, porque um agente vai usá-lo. Por isso três das 28 referências são geradas a partir dos próprios registros do Potato e não têm como divergir do que o servidor impõe: todos os 61 tipos de anotação, cada um com um exemplo funcional tirado de um projeto real, as chaves de configuração de nível superior documentadas e as subchaves documentadas.

O CI cobre os arquivos centrais da skill, conferindo que cada tipo de anotação, tipo de display, chave de configuração, operador, nome de estratégia e comando citado neles existe no Potato. Cada amostra de YAML é encaixada em um config que funciona e passa pelo validador real do Potato, e o exemplo funcional sobe um servidor de verdade, onde cada recurso que ele liga tem que reportar uma contagem diferente de zero no log.

O material de referência está publicado em davidjurgens.github.io/potato-skill, então você pode ler o que a skill diz ao agente antes de instalá-la. A Anthropic recomenda revisar qualquer skill antes.

Perguntas

Preciso conhecer o Potato antes?

Não. Você descreve o estudo em linguagem comum, e o Potato precisa estar instalado na máquina onde o agente executa comandos. Antes de os anotadores verem a tarefa, abra-a em um navegador e rotule alguns itens você mesmo.

Dá para usar o potato-skill com Codex ou Cursor?

Sim, pelos dois caminhos. O npx skills add davidjurgens/potato-skill --agent codex cursor coloca a skill completa no projeto, e o AGENTS.md do repositório dá uma versão mais curta sem instalar nada. A skill foi escrita para o Claude Code, que é onde está a instalação pelo marketplace.

Melhor pedir ao meu agente de programação que construa uma ferramenta de anotação customizada?

Para algumas centenas de itens que uma pessoa rotula uma vez, um script pequeno basta. A partir do momento em que o estudo precisa de vários anotadores por item, treinamento, verificações de atenção, concordância ou uma plataforma de crowdsourcing, cada uma dessas coisas tem que ser construída e testada. O potato-skill se apoia no Potato, que já tem tudo isso, e a tarefa que ele produz pode ser reexecutada e compartilhada.

Posso editar o que ele constrói?

Sim. A saída é uma tarefa comum do Potato, uma pasta com um config, dados e instruções. Edite à mão com o Início Rápido e os Fundamentos de Configuração, ou peça ao agente para mudá-la.

Quanto custa?

Nada. O Potato é gratuito e de código aberto, e o potato-skill é publicado sob a GPL-3.0-or-later. Você paga pelo agente de programação que já usa, e pelos anotadores se recrutar alguém.

O que é o Potato?

O Potato é uma ferramenta de anotação de código aberto da Universidade de Michigan, descrita em uma demonstração de sistema na ACL 2026. Ele suporta 61 tipos de anotação em texto, imagens, áudio, vídeo, diálogo e traces de agentes.

Leitura adicional

• Início rápido com um agente de programação, que cobre a instalação com mais detalhe
• potato-skill no GitHub, atualmente na v1.0.1
• O material de referência da skill
• O showcase, para achar um design perto do seu estudo

Referências

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/