Agent Skills: 10 Skills Que Todo Time Deveria Versionar

Agent Skills são uma das ideias mais práticas do desenvolvimento agêntico atual. Em vez de colocar todas as regras em um prompt gigante, você cria pequenos módulos de comportamento: uma skill para revisar código, outra para debugar, outra para escrever testes, outra para validar browser, outra para preparar release.

O Radar da Thoughtworks colocou Agent Skills em Trial, e isso faz sentido. A prática está madura o suficiente para times experimentarem em projeto real, mas ainda nova o bastante para exigir cuidado. Skills podem aumentar consistência, mas também podem virar nova superfície de supply chain se forem copiadas sem revisão.

O ponto mais importante: skill não é só prompt bonitinho. Uma skill pode conter instruções, exemplos, scripts, comandos, critérios de qualidade e fluxo de decisão. Ela transforma conhecimento operacional do time em artefato reutilizável.

Este post é um guia prático das 10 skills que eu versionaria primeiro em um time de engenharia usando agentes de código. Não são as skills mais chamativas. São as que reduzem retrabalho.

---

1. Code Review Skill

A primeira skill que eu criaria é code review. Todo time tem preferências de revisão que vivem na cabeça dos seniors: evitar patch grande, preservar contratos, exigir teste, não criar abstração sem uso, respeitar padrões locais. O agente precisa aprender isso de forma explícita.

Uma boa code review skill deve conter checklist do time, exemplos de comentários bons, prioridade de achados e regras de severidade. Ela também deve separar bug real de opinião de estilo. Agente que comenta tudo vira ruído e perde credibilidade.

Essa skill serve em dois momentos. Antes do humano revisar, o agente faz uma passada inicial. Depois, quando o humano deixa feedback, a skill ajuda o agente a interpretar comentário de forma objetiva.

O ganho é imediato: menos PR chegando cru, menos revisão repetitiva e mais consistência no padrão de qualidade.

---

2. Systematic Debugging Skill

Agentes são tentados a corrigir antes de diagnosticar. Isso também acontece com humanos, mas agentes fazem em escala. Uma debugging skill precisa forçar ordem: reproduzir, observar, isolar, formular hipótese, testar hipótese e só então alterar código.

Essa skill deve ensinar o agente a coletar evidências: logs, stack trace, inputs, ambiente, commit recente, rota afetada, comando que falha. Também deve proibir "fix por palpite" quando não há reprodução.

Em sistemas reais, isso economiza muito tempo. O agente deixa de sair editando arquivos e começa a investigar como um dev bom. A diferença de qualidade é gritante.

Se eu tivesse que escolher só três skills para começar, debugging estaria nelas.

---

3. Test-Driven Development Skill

TDD com agente não precisa ser religião. Mas a ideia de escrever teste que falha antes do patch é extremamente útil para evitar implementação fantasiosa.

A skill deve orientar: defina comportamento, escreva teste mínimo que falha, implemente menor mudança, rode teste, refatore se necessário. Para bugfix, isso é ainda mais forte: primeiro reproduza bug em teste. Depois corrija.

Também vale incluir padrões locais: framework de teste, nomenclatura, factories, fixtures, mocks, comandos e exemplos de testes bons. Agente copia exemplos. Dê bons exemplos.

Essa skill reduz um dos problemas mais comuns em PRs de agentes: teste feliz que só confirma a solução inventada pelo próprio agente.

---

4. Browser Validation Skill

Para frontend, review de arquivo não basta. O agente precisa abrir rota real, interagir, verificar layout, console, rede e responsividade. Uma browser validation skill transforma isso em ritual.

Ela deve dizer quais viewports testar, como capturar screenshot, como checar console errors, como validar estados vazios/loading/erro e como comparar comportamento esperado.

Em apps complexos, essa skill evita uma categoria inteira de "funcionou no diff, quebrou na tela". Ela também força o agente a lidar com realidade do runtime, não só com TypeScript verde.

Se o time usa Playwright, Cypress ou Browser plugin, a skill deve apontar comandos e padrões. Se não usa, ainda pode ter checklist manual com screenshots.

---

5. API Contract Skill

Agentes quebram contrato quando não sabem onde está a fonte de verdade. Uma API contract skill deve orientar leitura de OpenAPI, schema, types compartilhados, DTOs, migrations e consumidores.

Ela também deve definir regra simples: antes de mudar request/response, identificar todos os consumidores. Antes de alterar erro, verificar UI. Antes de mudar enum, buscar persistência e filtros.

Essa skill é especialmente útil em projetos fullstack. O agente que mexe no backend precisa entender impacto no frontend. O agente que mexe no frontend precisa verificar se rota existe.

Parece básico, mas evita muito PR que compila em uma camada e quebra outra.

---

6. Release Notes Skill

Release notes parecem trabalho administrativo, mas são uma excelente forma de forçar síntese. Se o agente não consegue explicar o que mudou, risco, rollback e validação, talvez ele não entendeu o próprio patch.

Uma release notes skill deve gerar resumo para humano, mudanças técnicas, impacto de produto, flags, migrations, risco, plano de rollback e validação executada.

Isso ajuda muito em times que usam agentes para várias pequenas mudanças. O histórico fica menos opaco e o deploy deixa de depender de memória oral.

Também facilita comunicação com produto, suporte e operação.

---

7. Security Review Skill

Uma security review skill não substitui scanner, mas ajuda a orientar olhar do agente. Ela deve cobrir secrets, autorização, autenticação, validação de input, SSRF, redirects, logging sensível, dependências e permissões.

O segredo é ser específica para o stack. Segurança genérica demais vira checklist decorativo. Em um app Next.js com Supabase, os riscos são diferentes de um backend Java com Kafka e banco legado.

Essa skill também deve dizer quando escalar para humano. Mudança em auth, pagamento, dados pessoais, infra ou criptografia não deve passar apenas por revisão automática.

Em desenvolvimento agêntico, segurança precisa entrar antes do merge, não depois do incidente.

---

8. Migration Skill

Migrations são perigosas porque combinam código, dados e irreversibilidade. Uma migration skill deve forçar o agente a pensar em forward/backward compatibility, rollback, volume de dados, lock, índice, nullable, backfill e deploy em etapas.

Ela deve conter exemplos de migrations aprovadas no projeto e comandos para validar localmente. Também deve impedir mudança destrutiva sem aprovação explícita.

Essa skill é uma das que mais protegem produção. Agentes tendem a tratar schema como arquivo comum. Não é. Schema é contrato vivo com dados reais.

Se o time usa Flyway, Prisma, Rails, Liquibase ou SQL puro, a skill precisa refletir o processo real.

---

9. Onboarding Skill

Skills também servem para humanos. Uma onboarding skill pode ensinar agente e dev novo ao mesmo tempo: arquitetura, comandos, pastas, padrões, decisões, como rodar local, como debugar, como abrir PR.

O Radar cita "skills as executable onboarding documentation" em Assess, e essa ideia é forte. Documentação que o agente consegue executar tende a ser mais precisa do que documentação escrita só para leitura.

Essa skill deve ser curta, prática e atualizada junto com o repo. Se virar manual gigante, ninguém usa e o agente carrega ruído.

Bom onboarding é um multiplicador de produtividade humana e agêntica.

---

10. Incident Playbook Skill

Quando algo quebra, agente pode ajudar muito, mas só se seguir processo. Uma incident skill deve orientar coleta de sinais, checagem de status, logs, métricas, rollback, comunicação e pós-mortem.

Ela não deve autorizar ações destrutivas sozinha. O valor está em acelerar diagnóstico e preparar opções, não em deixar agente brincar de SRE autônomo sem supervisão.

Em times pequenos, essa skill vale ouro. Ela reduz pânico, padroniza resposta e ajuda a capturar aprendizado depois.

Também conecta bem com DORA metrics: MTTR melhora quando resposta a incidente é repetível.

---

Governança de Skills

Agora a parte menos divertida e mais importante: skills precisam de governança. Se qualquer pessoa instala qualquer skill de qualquer lugar, você criou uma nova supply chain invisível.

Uma skill pode conter instrução maliciosa, comando perigoso, dependência insegura ou regra incompatível com o projeto. E como skills parecem "só texto", muita gente baixa guarda.

Minha regra: skill usada em projeto de trabalho deve ser versionada, revisada e ter dono. Mudança em skill deve passar por PR. Skill com script deve ter revisão ainda mais rígida. Skill externa deve ser tratada como dependência.

Esse é o preço de transformar conhecimento em ferramenta. Vale a pena, mas não é grátis.

---

Principais Aprendizados

• Agent Skills transformam conhecimento de time em comportamento reutilizável.
• As primeiras skills devem reduzir retrabalho, não impressionar em demo.
• Code review, debugging e TDD são candidatas fortes para começar.
• Skills com scripts são dependências executáveis e precisam de governança.
• Skill boa é curta, específica, versionada e testada no fluxo real.

---

Conclusão

Agent Skills são uma das melhores respostas para o problema de consistência em desenvolvimento agêntico. Elas fazem o agente parar de depender apenas do prompt atual e passam a carregar práticas do time de forma modular.

Mas o ganho vem com responsabilidade. Skill sem dono vira prompt solto com nome bonito. Skill com script sem revisão vira risco de supply chain. Skill longa demais vira context bloat.

Comece pequeno. Versione três skills. Use em PR real. Meça se reduziu retrabalho. Depois expanda. O time não precisa de uma biblioteca infinita de skills. Precisa das skills certas, no lugar certo, com revisão certa.

---

Fontes e Referências

• Thoughtworks Technology Radar Vol. 34
• AI agent skills as supply chain risk - TechRadar
• Superpowers - GitHub
• Superpowers skills catalog
• SWE-Skills-Bench: Do Agent Skills Actually Help?
• Harness engineering for coding agent users - Martin Fowler

---

Sugestão de Imagens

Capa (agent_skills_top_10_cover.png): prateleira de skills versionadas como módulos: review, debug, test, browser, API, release, security, migration, onboarding, incident.

Inline 1: tabela das 10 skills com objetivo, gatilho e risco.

Inline 2: fluxo de governança: skill externa -> review -> versionamento -> uso pelo agente.