Skill de agente também precisa passar por code review · Centelha

Uma coisa engraçada acontece quando o time começa a usar agente de código todo dia.

No começo, a gente repete instrução na conversa:

Antes de mexer, leia o README.
Rode os testes.
Não altere arquivo gerado.
Use o padrão que já existe no projeto.

Depois de alguns dias, alguém cansa. Faz sentido. Ninguém quer digitar a mesma regra em toda tarefa. Aí nasce um arquivo do tipo SKILL.md, um prompt de projeto, uma instrução para MCP, um guia local para "como o agente deve trabalhar aqui".

Parece só organização.

Mas, na prática, esse arquivo começa a decidir muita coisa: quais comandos o agente tenta primeiro, quais arquivos ele considera fonte de verdade, quando ele acha que terminou, como ele reage a erro, que tipo de ferramenta pode chamar e quais atalhos viram comportamento padrão.

Isso já não é nota solta. É parte do sistema de desenvolvimento.

E se muda o comportamento do sistema, precisa passar por review.

Skill não é documentação neutra

Documentação comum explica algo para uma pessoa.

Uma skill de agente faz mais do que isso. Ela instrui uma máquina que pode ler arquivo, editar código, abrir terminal, rodar teste, chamar ferramenta, insistir em um plano e declarar a tarefa como pronta.

Claro que ela ainda é texto. Só que é texto com efeito operacional.

Um SKILL.md ruim não precisa ter nada obviamente malicioso para causar problema. Basta carregar uma suposição errada:

"sempre rode npm install antes de investigar";
"se o teste falhar, atualize o snapshot";
"ignore mudanças em arquivos gerados";
"publique o resultado quando o build passar";
"use a ferramenta X para buscar contexto externo";
"em caso de erro, tente novamente com permissões maiores".

Separadas, essas frases podem parecer razoáveis. Dentro de um projeto real, cada uma delas pode ser perigosa, inútil ou simplesmente velha.

O ponto não é tratar toda skill como ameaça. É tratar como artefato de projeto. Do mesmo jeito que um script de build, uma configuração de CI ou um hook de commit.

O review precisa olhar o que a skill permite

Quando uma skill entra em um repositório, eu não revisaria só a redação.

Eu olharia cinco coisas.

Primeiro: comandos.

Tem comando sugerido? Tem shell? Tem instalação de dependência? Tem curl, npx, script de setup, migration, deploy, limpeza de arquivo, escrita fora do diretório do projeto? Se tem, isso precisa estar explícito e fazer sentido para aquele repo.

Segundo: permissões.

A skill pede acesso a rede, browser, banco, secret, sistema de arquivos inteiro ou ferramenta externa? Às vezes é necessário. Mas "necessário" precisa ser explicado. Permissão ampla sem motivo vira fé.

Terceiro: critério de pronto.

Essa parte é mais sutil. Muita instrução de agente fala algo como "finalize quando os testes passarem". Só que teste passando não cobre tudo. Pode faltar lint, revisão visual, migração, atualização de documentação, checagem de contrato, validação manual ou só uma explicação decente do que mudou.

Quarto: recuperação de erro.

O que a skill manda fazer quando algo falha? Parar e explicar? Abrir um plano? Tentar alternativa menor? Ou sair instalando coisa e mexendo em configuração até alguma coisa passar?

Quinto: suposição local.

Skill copiada de outro projeto costuma trazer poeira junto. Nome de pacote antigo, porta local errada, stack diferente, ferramenta que o time não usa mais, comando que funcionava no Mac de alguém. Agente segue instrução velha com a mesma confiança com que segue instrução boa.

Copiar skill é copiar decisão invisível

Esse é o detalhe que mais me incomoda.

Quando copiamos um utilitário de outro projeto, pelo menos parece código. O diff mostra função, import, teste, dependência.

Quando copiamos uma skill, dá uma falsa sensação de baixo risco porque é "só texto".

Mas aquele texto pode embutir decisões de processo:

que tipo de fonte o agente deve priorizar;
quando ele pode editar sem perguntar;
que arquivos ele deve ignorar;
como ele interpreta falha intermitente;
qual ferramenta tem mais autoridade;
quanto esforço ele deve gastar antes de pedir ajuda.

Isso afeta o trabalho tanto quanto um script. Às vezes mais, porque o agente vai aplicar essa instrução em tarefas diferentes, com variações que ninguém previu.

O review, então, não deveria perguntar apenas "o texto está claro?".

Deveria perguntar: "se um agente obedecer isso literalmente, o que ele pode fazer de errado?".

Review demais também atrapalha

Tem um risco do outro lado: transformar prompt em cerimônia.

Se cada frase de uma skill precisar de uma RFC, ninguém vai manter nada. O time volta para prompt jogado no chat, ou pior, cada pessoa cria sua instrução local e ninguém sabe qual trilho está guiando o agente.

Eu gosto de uma regra proporcional:

Quanto mais poder operacional a skill dá ao agente, mais review ela merece.

Uma skill que só define tom de escrita ou formato de resposta pode passar por uma revisão simples.

Uma skill que manda rodar comandos, alterar arquivos, publicar conteúdo, mexer em dependência, chamar ferramenta externa ou declarar tarefa concluída precisa de mais cuidado.

Não é burocracia. É calibragem.

Um checklist pequeno para PR de skill

Se amanhã alguém abrir um PR adicionando uma skill ao projeto, eu usaria algo assim:

quem é o dono dessa skill?
qual problema repetitivo ela resolve?
que comandos ela sugere ou autoriza?
que permissões ela pressupõe?
quais arquivos ela manda priorizar?
o que conta como tarefa pronta?
o que o agente deve fazer quando falhar?
a skill foi testada em uma tarefa pequena?
existe algo específico demais do ambiente de uma pessoa?
alguma instrução antiga deveria ser removida junto?

Repara que não é um checklist gigante.

A ideia é forçar uma leitura que normalmente não acontece quando o arquivo parece "só documentação".

Também vale pedir uma descrição curta no PR:

Esta skill orienta o agente a revisar mudanças de frontend.
Ela permite leitura do projeto e execução de testes locais.
Não autoriza instalação de dependências, deploy nem escrita fora do diretório.
Foi testada em um ajuste pequeno de componente.

Isso muda o nível da conversa. Quem revisa deixa de discutir estilo de prompt e passa a revisar comportamento esperado.

Versionar comportamento é diferente de empilhar instrução

Outro cuidado: skill envelhece.

O projeto troca framework, muda script, remove ferramenta, altera política de teste, adiciona monorepo, troca CI, muda o jeito de publicar. Se a skill não acompanha isso, ela vira um manual antigo que o agente ainda leva a sério.

O pior padrão é empilhar regra nova sem apagar regra velha:

Use yarn.
Agora use pnpm.
Se falhar, tente npm.
Mas preserve o lockfile antigo.

Para humano, isso já é chato. Para agente, é convite para improviso.

Skill boa precisa de poda. Se uma instrução perdeu validade, remova. Se uma decisão mudou, explique. Se uma permissão ficou perigosa, reduza. Se a skill ficou grande demais, divida.

O histórico do Git ajuda muito aqui. Dá para ver quando o comportamento do agente mudou e por quê.

O rastro também importa

Quando um agente abre um PR, o diff mostra o código, mas nem sempre mostra o trilho que produziu aquele código.

Se a mudança veio guiada por uma skill específica, isso deveria aparecer em algum lugar: descrição do PR, nota de execução, comentário curto, log interno, tanto faz. O formato depende do time.

O importante é conseguir responder depois:

qual instrução guiou o agente?
ele seguiu uma skill revisada ou improvisou?
que validações foram exigidas?
que parte ainda dependeu de julgamento humano?

Sem esse rastro, o review fica meio cego. A pessoa olha o resultado final, mas não entende que tipo de autonomia foi concedida para chegar ali.

O objetivo não é desconfiar de tudo

Eu gosto de agentes justamente porque eles tiram trabalho repetitivo da frente. Uma skill bem feita é ótima. Ela reduz contexto jogado fora, padroniza cuidado básico e evita que cada tarefa comece do zero.

Mas a confiança precisa morar no processo, não no carisma do modelo.

Agente obediente com skill ruim continua sendo problema. Agente bom com instrução velha também. E uma skill copiada de fora pode carregar decisões que não combinam com seu repo, sua equipe, suas permissões ou seu jeito de validar mudança.

Então eu trataria assim:

se a skill só ajuda a escrever melhor, revise como documentação.

se a skill muda como o agente opera, revise como parte do código.

Esse hábito pequeno evita uma categoria bem chata de bug: aquela automação que ninguém lembra de ter aprovado, mas que todo mundo passa a obedecer porque "sempre foi assim".

Notas de fonte

"From Registry to Repository: How AI Agent Skills Are Written, Adapted, and Maintained" - arXiv, 2026.
"Prompt Injection as Role Confusion" - cobertura da Tom's Hardware sobre confusão de papéis em modelos.
"Detecting AI Coding Agents in Open Source" - arXiv, 2026.
"Towards a Benchmark for Dependency Decision-Making" - arXiv, 2026.
Windows Central sobre terminal com agentes e gerenciamento de sessões.