AGENTS.md como um Plugin Intermediário: Um Estudo de Caso da Kobiton/Automate
Home canônica: Este post apareceu pela primeira vez no blog da Kobiton em kobiton.com/blog/agents-md-cross-tool-plugin-brief-case-study-kobiton-automate. Esta página é uma cópia; a autoridade de SEO se consolida na URL da Kobiton através de
rel="canonical".
AGENTS.md como um Plugin Inter-Tool: Um Estudo de Caso do kobiton/automate
Resumo — Eu executei uma varredura de paridade em 5 dispositivos contra a nuvem de dispositivos reais da Kobiton através do plugin Claude Code kobiton/automate. A captura de tela do iOS foi cerca de ~17% mais rápida do que a do Android nesta execução. A parte interessante não é a diferença — é que o plugin não documenta a diferença, ou o tempo de espera pós-deleteSession, ou quais endpoints de log do Appium realmente funcionam. É para isso que serve um arquivo AGENTS.md, e a PR #10 no repositório está começando a adicionar um. Este é um exemplo prático do que deve ser incluído nele.
Eu passei a semana passada investigando kobiton/automate, o plugin Claude Code que conecta à nuvem de dispositivos reais da Kobiton. Cinco dispositivos, duas pools, ambas as principais plataformas móveis, um pequeno harness do WebDriverIO. Os números mostraram algo que os autores de plugins raramente publicam: a captura de tela do iOS foi cerca de 17% mais rápida do que a do Android na amostra.
Essa diferença não é um bug. É uma variação de plataforma. Mas é o tipo de variação que você quer que seja visível antes que sua conta de CI silenciosamente a acumule — e trazer à tona coisas como essa é exatamente para isso que serve um resumo de agente inter-tool como o AGENTS.md.
O plugin
kobiton/automate é um plugin Claude Code fino que aponta para um servidor MCP remoto (https://api.kobiton.com/mcp). O repositório contém manifests, uma habilidade, esquemas e documentos. O Appium ainda executa o loop do driver uma vez que uma sessão é aberta. Essa é a fronteira correta. O plugin não finge ser o Appium; ele apenas ajuda o agente a entrar em uma sessão de trabalho e sair limpo.
O repositório público atualmente expõe 12 ferramentas MCP:
| Área | Ferramentas |
|---|---|
| Dispositivos |
listDevices, getDeviceStatus, reserveDevice, terminateReservation
|
| Sessões |
listSessions, getSession, getSessionArtifacts, terminateSession
|
| Apps |
listApps, uploadAppToStore, confirmAppUpload, getApp
|
Na semana passada, a equipe abriu PR #10, que adiciona suporte ao GitHub Copilot CLI e um arquivo AGENTS.md. Cinco arquivos foram alterados, 75 linhas adicionadas. No momento da escrita, está aberto e marcado como em teste. A maior parte da diferença é trabalho de portabilidade — declarando caminhos de habilidade e MCP, trocando a linguagem específica do Claude por uma linguagem neutra e adicionando o próprio arquivo de instruções voltado para o agente.
Essa PR é o que me fez querer escrever isso. É um exemplo real de um plugin passando de "funciona no Claude Code" para "qualquer agente de codificação razoável pode ler isso e se comportar".
A varredura de paridade
O harness é pequeno. Abra uma sessão do Appium, tire cinco capturas de tela, registre o tempo de inicialização e o p50 por captura de tela, termine limpo. Cinco dispositivos:
| Piscina de dispositivos | OS | Modelo | Inicialização ms | Captura de tela p50 |
|---|---|---|---|---|
| PRIVADO | Android 13 | Galaxy A52s 5G | 4,206 | 353 |
| CLOUD | Android 9 | moto g(7) play | 5,451 | 297 |
| PRIVADO | iOS 17.5.1 | iPhone XR | 5,091 | 242 |
| CLOUD | iOS 18.6 | iPhone 14 Plus | 4,490 | 306 |
| CLOUD | iOS 18.6.2 | iPad 9ª Geração | 5,259 | 256 |
Nesta execução:
- Os tempos de inicialização variaram cerca de 30%.
- A captura de tela p50 variou cerca de 46%.
- O Android teve uma média de ~325ms por captura de tela.
- O iOS teve uma média de ~268ms — cerca de 17% mais rápido.
Cinco dispositivos não são um estudo de frota, então não leia isso como "iOS vence". O que vale a pena notar é que a plataforma importou mais do que a contagem de pixels. A captura de tela mais rápida na execução veio de um iPhone XR a 828×1792; a mais lenta veio de um Galaxy A52s 5G a 1080×2400. A resolução sozinha não previu a variação.
Essa diferença é importante em CI. Um delta de captura de tela de 57ms parece trivial até que você o acumule. Em 100 testes × 50 execuções/dia × 3 capturas de tela por teste, você gastou cerca de ~855 segundos por dia, ou ~7 horas por mês, no caminho mais lento. Aumente isso para cinco capturas de tela por teste e você chega a ~12 horas/mês. Não é um número que justifique uma reformulação da suíte. Mas é um tempo real de fila — o suficiente para que uma decisão de roteamento ("envie a suíte pesada em capturas de tela para o iOS primeiro") comece a se pagar.
Duas descobertas que um AGENTS.md fecharia
Duas coisas surgiram que um resumo voltado para o agente teria fechado antes de eu começar.
Compatibilidade de endpoint
driver.getLogs('logcat') não retornou dados utilizáveis através do endpoint que meu cliente tentou. A documentação do Appium distingue entre /session/:sessionId/log e /session/:sessionId/se/log, e qual deles funciona depende do driver e do servidor. Um plugin como este deveria apenas dizer de antemão quais endpoints de log ele suporta, quais ele rejeita e o que o agente deve fazer quando a recuperação de logs falha.
Sem isso, um teste portado de uma configuração vanilla do Appium pode silenciosamente perder seus logs. O teste ainda passa. A evidência simplesmente desaparece. O pior tipo de falha — aquele que sorri e acena enquanto rouba sua evidência.
Invisibilidade do ciclo de vida
Após deleteSession, os dispositivos entraram em um breve tempo de espera. Durante a janela, getDeviceStatus os relatou como ATIVADO com is_online=true — mas eles não podiam realmente aceitar uma nova sessão ainda. Um agendador ingênuo vê "pronto", coloca o próximo trabalho na fila e espera.
A correção é um ciclo de vida documentado. Nomes como pronto / reservado / ativo / limpeza-requerida / cooldown-requerido / offline / desconhecido. A redação importa menos do que ter um. Se is_online=true não significa pronto para a sessão, o plugin precisa dizer isso claramente.
Ambas as lacunas são documentação, não código.
Onde as convenções do Claude Code encontram o AGENTS.md
Se você já escreveu um plugin Claude Code, você já sabe sobre CLAUDE.md (orientação específica do repositório Claude) e SKILL.md (frontmatter e fluxo de trabalho de habilidade). Nenhum deles substitui AGENTS.md.
AGENTS.md é o arquivo de instruções independente de ferramenta. Um pacote de briefing que qualquer agente de codificação pode ler: configuração, convenções, regras de teste, armadilhas operacionais. SKILL.md pertence a um modelo completamente diferente — a especificação aberta do AgentSkills.io define sua estrutura para habilidades reutilizáveis. Relacionados, mas não intercambiáveis.
Os quatro arquivos compõem:
