Por Devy — yoDEV.dev
Teu agente de IA não escreve testes. Não cria specs. Não revisa seu próprio código. Não porque não saiba — mas porque ninguém disse que ele tinha que fazer isso.
Esse é o problema que Addy Osmani — engineering lead do Google Chrome — decidiu resolver. O resultado se chama agent-skills, um framework open source que já tem 33K estrelas no GitHub e está mudando como os times trabalham com agentes de IA em produção.
O problema: os agentes pegam o caminho mais curto
Quando você pede a um agente de IA que implemente uma feature, ele faz exatamente isso: implementa a feature. Não pergunta se você tem um spec. Não escreve o teste antes do código. Não avalia se a mudança ultrapassa um limite de segurança. Não considera o quão legível vai ser o PR para seu time.
Pega o caminho mais curto até “pronto” e declara vitória.
Isso não é um bug do modelo — é um problema de falta de processo. Um engenheiro sênior não apenas escreve o código: valida suposições, divide o trabalho em chunks revisáveis, escolhe a solução entediante em vez da engenhosa, e deixa evidência de que o resultado está correto. Esses passos não aparecem no diff, mas fazem a diferença entre software confiável e software que quebra em produção.
agent-skills coloca esse andaime no agente de forma explícita.
O que é uma “skill”
Uma skill é um arquivo Markdown com frontmatter que é injetado no contexto do agente quando a situação exige. Mas fique atento à distinção-chave que Osmani faz: uma skill não é documentação de referência. É um workflow.
Não é “tudo o que você deveria saber sobre testes.” É uma sequência de passos que o agente segue, com checkpoints que geram evidência e critérios de saída definidos. A diferença importa: se você coloca um ensaio de 2.000 palavras sobre boas práticas no contexto, o agente gera texto plausível e pula os testes. Se você coloca um workflow (escreva o teste que falha, execute, veja como falha, escreva o código mínimo para passar, refatore), o agente tem algo concreto para executar — e você tem algo concreto para verificar.
Processo em vez de prosa. Workflows em vez de referência. Passos com critérios de saída em vez de ensaios sem eles.
As 21 skills do pacote
O repositório inclui 21 skills organizadas em torno de seis fases do ciclo de desenvolvimento, com sete slash commands como pontos de entrada:
| Fase | Comando | O que faz |
|---|---|---|
| Definir | /spec |
Cria um SPEC.md antes de tocar em uma linha de código |
| Planejar | /plan |
Decompõe o trabalho em tarefas atômicas |
| Construir | /build |
Implementa em vertical slices com feature flags |
| Verificar | /test |
TDD rigoroso: Red → Green → Refactor |
| Revisar | /review |
Code review em cinco eixos com rótulos de severidade |
| Entregar | /ship |
Deploy seguro com checklist de lançamento |
Além disso, /code-simplify percorre todo o ciclo para limpar o código gerado por IA antes de chegar a um PR.
As skills são ativadas automaticamente de acordo com o contexto: se você está projetando uma API, a skill api-and-interface-design é ativada. Se você está construindo UI, a skill frontend-ui-engineering é ativada. Você não precisa invocá-las manualmente.
As cinco ideias centrais que vale a pena roubar
1. Processo em vez de prosa
Já mencionamos, mas é a ideia mais importante do projeto. Se seu time tem um handbook de 200 páginas, ninguém lê sob pressão de tempo. Um pequeno conjunto de workflows com checkpoints, sim.
2. Tabelas anti-racionalização
Essa é a decisão de design mais original do repo. Cada skill inclui uma tabela com as desculpas comuns que um agente (ou um engenheiro cansado) usa para pular o workflow, junto com uma refutação escrita. Por exemplo:
- “Essa tarefa é simples demais para precisar de um spec.” → Os critérios de aceitação se aplicam do mesmo jeito. Cinco linhas está bom. Zero linhas, não.
- “Vou escrever os testes depois.” → “Depois” é a palavra-chave. Depois não existe. Escreva o teste que falha primeiro.
- “Os testes passam, vamos entregar.” → Testes que passam são evidência, não prova. Você revisou o runtime? Um humano leu o diff?
LLMs são excelentes racionalizando. Essas tabelas são refutações pré-escritas para mentiras que o agente ainda não contou.
3. A verificação é inegociável
Cada skill termina com evidência concreta: testes que passam, build limpo, um revisor que dá o OK. “Parece correto” nunca é suficiente. Sem evidência, a tarefa não está concluída.
4. Progressive disclosure
Não carregue as 21 skills no contexto no início da sessão. Uma meta-skill (using-agent-skills) funciona como roteador e decide qual skill se aplica à tarefa atual. Assim você pode ter uma biblioteca de 21 skills em um slot de 5K tokens sem saturar o contexto.
5. Disciplina de escopo
A meta-skill tem uma regra inegociável: toque apenas no que foi pedido. Não refatore sistemas adjacentes. Não delete código que você não entende completamente. Não comece a reescrever um arquivo porque encontrou um TODO.
Isso parece óbvio até você ver um agente decidir que corrigir um bug requer modernizar três arquivos não relacionados. Disciplina de escopo é o fator mais determinante para saber se o PR de um agente é mergeável ou precisa ser desfeito.
O DNA da Engenharia Google
As skills estão saturadas de práticas de Software Engineering at Google e da cultura de engenharia pública do Google. Algumas referências concretas:
- Lei de Hyrum em
api-and-interface-design— todo comportamento observável de sua API será dependendido eventualmente - A Regra Beyoncé e a pirâmide de testes (80/15/5) em
test-driven-development— se você gostou, escreva um teste - DAMP em vez de DRY em testes — os testes do Google são explicitamente mais legíveis que DRY
- PRs de ~100 linhas com rótulos Critical/Nit/Optional/FYI em
code-review-and-quality - A Cerca de Chesterton em
code-simplification— não delete algo até entender por que está lá - Trunk-based development e commits atômicos em
git-workflow-and-versioning
Nenhuma dessas ideias é nova. O ponto é que nenhuma delas vem ativada por padrão no agente.
Como instalar no Claude Code
A forma mais direta se você usa Claude Code:
/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills
Com isso você tem os slash commands (/spec, /plan, /build, /test, /review, /ship, /code-simplify) e as skills são ativadas automaticamente de acordo com o contexto.
Para Cursor: copie o conteúdo de qualquer SKILL.md em .cursor/rules/.
Para Windsurf: o repositório inclui integração com o Rules Engine do Windsurf — há um PR ativo (#134) que moderniza essa integração.
Para Gemini CLI: tem seu próprio caminho de instalação documentado no README.
Sem instalar nada: clone o repo, navegue até skills/ e copie o conteúdo do SKILL.md relevante diretamente em sua conversa. As skills são Markdown plano — funcionam em qualquer ferramenta que aceite um system prompt.
O modo “roubar a ideia sem instalar nada”
Osmani descreve três modos de uso. O terceiro — e o que ele mais recomenda para começar — é usar as skills como especificação do que significa codear bem com IA, sem instalar nada.
Leia code-review-and-quality.md e aplique o framework de cinco eixos ao processo de review de seu time. Leia test-driven-development.md e use-o para resolver o próximo “precisamos escrever o teste primeiro?” com um junior. Leia a meta-skill e roube esses cinco pontos para seu próprio CLAUDE.md:
- Valide suposições antes de construir
- Pare e pergunte quando os requisitos se contradizem
- Reclame quando apropriado — o agente não é uma máquina de “sim”
- Prefira a solução entediante e óbvia
- Toque apenas no que foi pedido
Essa é uma cultura de engenharia útil em cinco linhas.
O projeto irmão: awesome-agent-skills
A comunidade já adotou o formato e o estendeu. O repositório VoltAgent/awesome-agent-skills adiciona mais de 1.200 skills contribuídas por equipes de desenvolvimento de diferentes ferramentas e frameworks — e também está em tendência esta semana.
Se o pacote oficial de 21 skills não cobre seu stack específico (digamos, skills para trabalhar com Supabase, ou para projetos Django, ou para pipelines de dados com dbt), é provável que alguém já tenha contribuído algo nesse repositório.
Por que isso importa agora
O desafio do momento não é conseguir que o agente gere código — isso já funciona. O desafio é conseguir que o código gerado seja auditável, reproduzível e integrável sem que um senior tenha que reescrever a metade.
agent-skills ataca exatamente esse problema. Não com prompts mágicos nem com um modelo maior, mas com o mais simples: dar ao agente os mesmos workflows que um engenheiro experiente se força a seguir porque aprendeu com os incidentes que causa pulá-los.
33K estrelas em poucas semanas desde o lançamento sugerem que muita gente estava esperando exatamente isso.
Já usa algum tipo de CLAUDE.md ou arquivo de regras para guiar seu agente? Quais workflows custaram mais para o agente aprender a seguir? Nos conte nos comentários.