potato-skill: crie um estudo de anotação com um agente de programação
Descreva ao Claude Code, Codex ou Cursor o que precisa ser rotulado: o potato-skill projeta o estudo de anotação, o constrói no Potato e confere se renderiza.
Você pode começar um projeto no Potato de duas formas. Escreva a tarefa você mesmo, como mostra o Início Rápido, ou descreva o estudo a um agente de programação e deixe o potato-skill projetá-la e construí-la. Esta página trata do segundo caminho. Os dois terminam no mesmo lugar: uma tarefa de anotação do Potato que você pode executar, alterar e compartilhar.
O que a skill decide
O potato-skill é uma skill de agente, um pacote de instruções e scripts auxiliares que um agente de programação carrega quando um pedido precisa deles. Ele traz 28 arquivos de referência e nove scripts auxiliares, e cobre tanto o design do estudo quanto a construção:
- o que perguntar aos anotadores, e em que escala
- quantos anotadores cada item precisa
- como treinar os anotadores e conferir o trabalho deles
- a interface que os anotadores veem
- exportar os resultados no formato de que a próxima etapa precisa
Algumas dessas decisões ele resolve sozinho, e outras ele devolve. A regra que ele segue é que uma decisão é tomada na hora quando errar é barato de consertar, e devolvida quando errar é caro, irreversível ou não cabe ao agente. Ele adota uma escala de 5 pontos com todos os pontos rotulados, atalhos de teclado em qualquer pergunta com nove rótulos ou menos, ordem aleatória dos itens com um random_seed fixo e todas as perguntas obrigatórias. Ele pergunta a você sobre a unidade de anotação, o número de anotadores por item quando a concordância vai ser reportada, a redação do termo de consentimento e qualquer conjunto de rótulos sem uma opção de "indefinido".
A tarefa que ele constrói roda no Potato, então ela ganha o que o Potato já faz: um login para cada anotador, vários anotadores por item, estatísticas de concordância, integração com Prolific e SONA e exportação para os formatos que as ferramentas seguintes leem.
Requisitos
O Potato precisa estar instalado onde o agente executa comandos, porque os scripts auxiliares da skill importam os registros do Potato e acionam o comando potato:
pip install potato-annotationVocê também precisa de um agente de programação. A skill foi escrita para o Claude Code, e também se instala no Codex e no Cursor.
Instalando a skill
No Claude Code, instale a partir do marketplace de plugins:
/plugin marketplace add davidjurgens/potato-skill
/plugin install potato-skill@potatoPara Codex e Cursor, a CLI skills instala a skill dentro do projeto em que você está trabalhando:
npx skills add davidjurgens/potato-skill --agent codex cursorO 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.
Descrevendo o estudo
Diga o que precisa ser rotulado, quem vai rotular e para que servem os rótulos. Você não precisa conhecer os tipos de anotação do Potato nem o formato de config dele. Um pedido pode ser curto assim:
Quero 200 tweets rotulados por sentimento numa escala de 5 pontos, com três anotadores por item, uma página de consentimento e duas verificações de atenção. Construa e inicie.
A skill define o texto das perguntas, a escala, a forma de atribuir os itens e a forma de conferir os anotadores. Ela não trava nas perguntas que quer confirmadas. Ela declara seus pressupostos, monta a tarefa, verifica e pergunta junto com algo em que você já pode clicar.
Verificações que o agente executa antes de entregar
Um config que valida diz que o servidor vai subir, e não diz nada sobre se uma pessoa consegue fazer o trabalho. 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.pngO --strict transforma uma chave de configuração não reconhecida de aviso em falha, o que pega um erro de digitação que, de outro modo, deixaria um recurso desligado em silêncio. 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.
Três dos nove scripts auxiliares automatizam o que dá para medir em vez de julgar. O check_ui.py mede o layout ao vivo e reporta schemes ou um botão Next abaixo da dobra, widgets de mídia vazios e atalhos duplicados. O boot_and_check.py reporta cada recurso que está configurado mas não carregou nada. O walk_task.py percorre uma tarefa em execução do jeito que um anotador faria e reporta onde ela trava.
Abra a tarefa no seu navegador e rotule alguns itens você mesmo antes de convidar qualquer pessoa.
A tarefa que ele produz
Uma tarefa do Potato é uma pasta de projeto com o config da tarefa, os dados dela e as instruções. Tudo o que está no Início Rápido vale para ela. Você a inicia com potato start config.yaml, edita à mão, adiciona anotadores e exporta os rótulos.
Como o resultado é uma pasta de tarefa do Potato, outras pessoas também podem usá-la. Um colega pode rodar o mesmo estudo com dados novos, você pode repeti-lo no ano que vem e pode publicá-lo junto com o artigo que o usou. O showcase é uma coleção de tarefas compartilhadas dessa forma, tiradas de artigos publicados.
Designs e anotações existentes
- Um design publicado. A skill pode partir de um dos 440 designs de anotação tirados de artigos publicados, com seus conjuntos de rótulos, o texto das perguntas e as instruções. Você pode explorá-los no showcase, e o
find_design.pyfaz busca neles por um design parecido com o que você descreveu. - Anotações de outra ferramenta. O
potato importlê 20 formatos, entre eles Labelbox, CVAT e COCO, então um projeto pela metade pode continuar no Potato. - Um estudo que já está em andamento. O
study_status.pyreporta o progresso de cada anotador e a concordância em cada pergunta, e a skill diz quais correções são seguras no meio do estudo e quais corromperiam os dados já coletados.
Os servidores MCP do Potato
Um agente pode chegar às mesmas respostas por MCP em vez do 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.
Testes contra os registros do Potato
Um identificador errado mas plausível é pior do que documentação nenhuma, porque um agente vai usá-lo. 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.
O material de referência está publicado em davidjurgens.github.io/potato-skill, e pode ser lido sem instalar nada. A Anthropic recomenda revisar qualquer skill antes de instalá-la.
Comparação entre os dois caminhos
Os dois caminhos diferem no que você tem no começo, não no que você tem no fim:
| Escrever a tarefa você mesmo | Descrevê-la a um agente de programação | |
|---|---|---|
| Você começa com | um config YAML | uma descrição em linguagem comum |
| Indicado para | aprender o Potato, tarefas pequenas | estudos novos, estudos de crowdsourcing com treinamento e verificações, tipos de anotação que você ainda não usou |
| Você termina com | uma tarefa do Potato | uma tarefa do Potato |
Você pode trocar de caminho a qualquer momento. Um agente pode alterar uma tarefa que você escreveu, e você pode editar uma que o agente construiu.
Perguntas
As perguntas abaixo tratam de como configurar o potato-skill com um agente de programação e de onde encontrar o código-fonte dele.
Como uso o Potato com um agente de programação?
Instale o Potato e o potato-skill onde o agente executa comandos e depois descreva o estudo ao agente em linguagem comum. O pip install potato-annotation instala o Potato. No Claude Code, /plugin marketplace add davidjurgens/potato-skill seguido de /plugin install potato-skill@potato instala a skill, e no Codex ou no Cursor quem faz isso é npx skills add davidjurgens/potato-skill --agent codex cursor. Diga ao agente o que precisa ser rotulado, quem vai rotular e para que servem os rótulos. O potato-skill constrói a tarefa, renderiza-a para conferir que funciona e devolve a lista das decisões que tomou no seu lugar.
Onde está o potato-skill no GitHub?
O potato-skill está em github.com/davidjurgens/potato-skill, publicado sob a GPL-3.0-or-later. O material de referência dele está publicado em davidjurgens.github.io/potato-skill, então você pode ler o que a skill diz ao agente antes de instalá-la.