Veja o que Theo mudou em AGENTS.md e skills para agentes: descrições como gatilho, PRs legíveis e menos escopo. Aprenda o processo, não copie.
O que muda em AGENTS.md e skills de agentes
O ajuste em AGENTS.md na prática consiste em escrever para o agente, não para o leitor humano, e em usar a descrição de cada skill como gatilho de acionamento. Theo, desenvolvedor conhecido pelo canal t3.gg, descreveu em 2026 uma reformulação de arquivos globais e específicos de projeto depois de perceber que os agentes comunicavam mal. O ganho não veio de instruções mais longas, e sim de instruções mais alinhadas ao trabalho real.
Ele separa três camadas. A primeira é o arquivo global, que vale para todas as máquinas e projetos. A segunda é o arquivo de projeto, que descreve como alterar aquela base de código. A terceira são as skills, pastas com metadados que o modelo carrega quando o pedido combina com o gatilho.
Um ponto central do relato: essas descrições não existem para explicar a skill. Existem para o modelo decidir quando abrir a skill. Se a descrição já entrega tudo, o modelo não precisa carregar nada — e você perde o controle do momento em que as instruções entram em contexto.
AGENTS.md global: como Theo organizou as regras
O arquivo global concentra preferências que valem em qualquer repositório. Theo contou que passou cerca de 6 horas editando markdown e outras 6 a 10 horas testando ajustes no dia seguinte, com quatro máquinas rodando trabalho em paralelo. O arquivo antigo durou perto de dois anos sem revisão.
A nova versão abre com uma apresentação curta: quem ele é, o que constrói e como prefere trabalhar. A justificativa é simples. Modelos fazem correspondência de tom, então um texto direto tende a produzir respostas diretas.
As regras de código evitam instruções genéricas. Em vez de pedir "escreva bom TypeScript", o arquivo lista what evitar: conversões desnecessárias, one-liners que só embrulham casts e código que parece tradução de Python. Também define quando perguntas são somente leitura e quando vale delegar para subagentes.
Segundo Theo, duas frases sobre simplicidade e sobre não começar a escrever código antes de entender o pedido reduziram bastante o excesso de iniciativa de modelos mais agressivos. Ele cita Opus 5 e GPT-5.6 como os que mais exageravam nesse ponto.
Skill, descrição e gatilho: onde a maioria erra
A descrição de uma skill é um gatilho, não um resumo. Theo mostrou a skill de acompanhar pull request, cuja descrição poderia ser reduzida a uma frase do tipo "use quando o usuário pedir para monitorar, acompanhar ou cuidar de um PR". O resto do conteúdo fica no corpo da skill.
Ele chegou a separar uma skill única em duas: uma para abrir PR e outra para acompanhar PR. Motivo prático: com gatilhos distintos, o modelo acerta qual carregar, e muitas vezes ele quer só uma das duas.
O mesmo raciocínio aparece na skill de upload de arquivos, usada para publicar capturas de tela, gravações e logs em uma URL pública que pode entrar na descrição de um PR. A skill exige um token; quando ele não existe na máquina, o agente deve avisar em vez de tentar adivinhar.
Um cuidado que Theo repete: descrição longa demais faz o modelo responder sem abrir a skill. Se o texto já contém o procedimento, a skill vira peso morto.
Como auditar o histórico de falhas dos seus agentes
A auditoria de histórico é a parte do processo que mais rende, e ela começa com um pedido direto ao próprio agente. Theo pediu que ele revisasse o histórico de conversas com modelos diferentes e apontasse os erros mais comuns, separados por modelo e por ferramenta.
O resultado virou insumo para os arquivos. Entre os padrões que ele relata, um modelo abria PR em rascunho cerca de 40% das vezes em que criava um PR, o que impedia a revisão automática. Outro matava processos errados com frequência, inclusive a instância que o próprio agente estava usando.
"Correções por 100 mensagens do usuário" foi a métrica que ele achou mais útil, porque mostra onde o humano precisou intervir. Theo reconhece o viés: ele usa um modelo para as tarefas mais difíceis e com menos contexto inicial, então corrige mais esse modelo.
O método não exige ferramenta especial. Peça ao agente para categorizar as chamadas de ferramenta, identificar quais foram inúteis e explicar decisões estranhas. Se um pedido simples levou 30 minutos, pergunte onde o tempo foi gasto.
AGENTS.md de projeto não é README
O arquivo de projeto responde a uma pergunta diferente do README. O README ajuda humanos e agentes a decidir se querem usar ou adotar aquele código. O arquivo de agente ensina como alterar o código sem quebrar o que existe.
Theo recomenda começar pelo glossário. Termos simples como "você", "nós", "usuário", "agente", "provedor" e "ambiente" fazem o agente descrever o sistema com o vocabulário do time. Isso melhora a leitura das saídas mais do que a capacidade técnica do modelo.
A seção sobre o que nunca pode ser comprometido cumpre outro papel. Ao dizer que o projeto é aberto, que a performance é auditada e que existem várias superfícies — web, desktop e mobile —, o arquivo dá ao agente critérios para recusar mudanças que pareçam boas localmente e ruins no conjunto.
Theo também inclui uma cláusula de escape: as instruções são padrões, não leis, e a preferência do desenvolvedor pode sobrepor tudo. Sem isso, uma regra desatualizada vira conflito entre agente e pessoa.
Menos escopo, PRs legíveis e o efeito no dia a dia
A regra que Theo considera mais importante na skill de PR é curta: não deixe o feedback da revisão expandir o PR além do objetivo original. Endereçar problemas reais, sim; perseguir cada comentário de bot, não.
Ele mostrou exemplos de títulos. Um título ruim descrevia negociação de compressão por mensagem no WebSocket. O título bom dizia que o tamanho do quadro caía 70% com gzip — um número verificável no diff. Para descrições, a ordem é problema primeiro, solução depois, nunca um inventário de implementação.
Boas e más práticas dentro da skill funcionam como exemplos para o modelo. Theo chama isso de semear os pesos com o que importa para você. Um ou dois pares de exemplo por skill costumam bastar.
O efeito visível é a redução do prompt do dia a dia. Pedidos como "faça C mais D mais A, abra e acompanhe o PR" passam a produzir o resultado esperado porque as regras já estão no arquivo, não na conversa.
O que não fazer ao montar seus próprios arquivos
Copiar os arquivos de outra pessoa é o erro que Theo pede para evitar. Instalar as skills de alguém se parece com instalar todas as dependências de um projeto alheio sem olhar o que cada uma faz.
O valor está no raciocínio, não no texto final. Cada regra existe por causa de um problema concreto observado em execuções reais. Reproduzir a conclusão sem viver o problema tende a produzir arquivos que ninguém mantém.
Vale tratar esses arquivos como código de infraestrutura: versionar, revisar e remover o que envelheceu. Theo admite que ainda precisa aposentar várias skills antigas.
Se você quer aprender mais sobre TypeScript e desenvolvimento assistido por agentes, vale acompanhar o trabalho de Gustavo Dev Doido e o Crazystack Typescript, que cobrem esse tipo de fluxo no contexto brasileiro. O Bootcamp do Dev Doido é outro caminho para quem quer estrutura em vez de vídeos soltos.
Perguntas frequentes sobre AGENTS.md e skills
- O que é um arquivo AGENTS.md? É um documento de instruções que agentes de código leem antes de agir em um repositório. Ele define preferências globais, regras de projeto, glossário e limites. O objetivo é alinhar comportamento, não documentar o software para humanos.
- Qual a diferença entre AGENTS.md global e de projeto? O global vale para todas as máquinas e repositórios, com preferências pessoais de estilo e fluxo. O de projeto descreve como alterar aquela base específica, incluindo superfícies, contratos e armadilhas. Os dois se sobrepõem, mas respondem a perguntas diferentes.
- Como escrever a descrição de uma skill? Escreva o gatilho, não o conteúdo. A descrição deve dizer quando o modelo carrega a skill, com os verbos que você usa nos pedidos. Se o texto explica o procedimento inteiro, o modelo responde sem abrir a skill.
- Por que o agente abre pull requests ruins? Em geral, falta instrução explícita sobre título, descrição e escopo. Títulos devem explicar por que a mudança importa, com números quando existirem. A descrição começa pelo problema do usuário, não pela lista de arquivos alterados.
- Como descobrir os erros mais comuns dos meus agentes? Peça uma auditoria do histórico, agrupada por modelo e por ferramenta. Questões úteis incluem quais chamadas foram inúteis, por que uma tarefa simples demorou e quais regras antigas induziram a decisão errada. Use o resultado para editar os arquivos.
- Skill e arquivo de agente são a mesma coisa? Não. O arquivo de agente fica sempre disponível e define o comportamento geral. A skill é carregada sob demanda, quando o pedido combina com o gatilho dela. Por isso a descrição da skill importa tanto quanto o conteúdo.
- Como manter esses arquivos sincronizados entre várias máquinas? Theo usa um repositório de frota com markdown versionado e uma pasta universal de skills. Alterações são propagadas por acesso remoto. O ponto principal é ter uma fonte única de verdade, não máquinas configuradas à mão.
- Vale a pena investir horas editando markdown? Theo relata cerca de 6 horas de edição e 6 a 10 horas de teste, com redução de retrabalho depois. O retorno depende de quanto você usa agentes e de quanta variação existe entre seus projetos. O custo maior é de atenção, não de tokens.
- A auditoria de agentes substitui a leitura do próprio código? Não. Ela revela padrões de falha e decisões ruins que passam despercebidas no dia a dia. A revisão do código continua sendo necessária, principalmente em mudanças destrutivas ou sensíveis.
- O que priorizar se eu só tiver uma hora? Comece pelo glossário e por uma regra que impeça mudanças fora do escopo pedido. Depois, ajuste a descrição de uma skill que você usa toda semana. Esses dois pontos costumam gerar o maior ganho de legibilidade nas saídas.
Transforme o que você já explicou em vídeo em artigo
A ideia central deste texto é que clareza de instrução vale mais que volume: arquivos escritos para um agente comunicam melhor porque descrevem o problema, o limite e o vocabulário do time. O mesmo vale para o conhecimento que você já gravou em vídeo e que hoje só existe em áudio e tela.
Se você tem aulas, entrevistas, opiniões ou explicações técnicas em vídeos do YouTube, dá para converter esse material em um artigo escrito sem regravar nada. No Skala Blog você cola a URL do vídeo, gera a transcrição e recebe um artigo estruturado, pronto para revisar e publicar.