SWE-Skills-Bench - Utilidade real de skills em agentes de IA
SWE-Skills-Bench: Do Agent Skills Actually Help in Real-World Software Engineering?
Pesquisa apresentada por Han et al. (março de 2026) que questiona a eficácia real de “agent skills” — pacotes estruturados de conhecimento procedural injetados em tempo de inferência — em tarefas de engenharia de software.
O benchmark avalia 49 skills públicas reais contra 565 instâncias de tarefas em seis subdomínios da engenharia de software (Deployment & DevOps, Analytics & Monitoring, API Development, Data Science & ML, Security & Testing, e Developer Tools), usando repositórios GitHub autênticos fixados em commits específicos e critérios de aceitação explícitos.
Principais descobertas:
- 39 de 49 skills (80%) não produzem nenhuma melhora na taxa de sucesso
- Ganho médio de apenas +1,2% em pass rate
- 7 skills especializadas produzem ganhos significativos (até +30%)
- 3 skills degrada performance (até -10%) por incompatibilidade com contexto do projeto
- Overhead de tokens varia de -77,6% (economia) a +451% sem melhora de acurácia
A pesquisa usa um framework determinístico que mapeia critérios de aceitação para testes executáveis e avaliação pareada (com e sem skill).
Caracterização das Melhores e Piores Skills
Embora o paper não especifique nominalmente cada uma das 7 melhores ou 3 piores skills nos resumos públicos, a pesquisa revela padrões críticos sobre quais tipos funcionam e quais falham:
Skills que Funcionam Bem (+30%)
Skills especializadas e bem focadas que:
- Endereçam procedimentos concretos e específicos do domínio
- Possuem exemplos de código exatos e versioning preciso
- Resolvem problemas em que o modelo carece de conhecimento pré-treino
- Ocupam espaço de contexto mínimo (documentação compacta)
- Usam triggers e descrições claras e não-ambíguas
A pesquisa posterior “Most Agent Skills Fail. Here’s How to Write Ones That Don’t” complementa, recomendando:
- Manter descriptions curtas mas específicas (evitar “helps with documents”)
- Nomear cenários de disparo concretos (ex: “log data into Elasticsearch”)
- Estrutura compacta vs. documentação abrangente (+18,9pp vs +5,7pp em SkillsBench)
- 2-3 skills por tarefa são ótimos (+20pp); 4+ mostram retornos diminutos
Skills que Degradam Performance (-10%)
Skills que prejudicam performance:
- Orientação desatualizada que conflita com o contexto atual do projeto
- Incompatibilidade de versão: documentação referencia bibliotecas/APIs antigas
- Ambiguidade no escopo: triggers muito amplos causam invocação incorreta
- Documentação excessiva: agentes não conseguem extrair informação relevante
- Procedimentos genéricos em domínios onde o modelo já tem cobertura forte
Padrão Emergente: Dependência de Domínio
Skills funcionam melhor em domínios que carecem de conhecimento procedural pré-treino:
- DevOps, CI/CD, Infrastructure — alto potencial (skills concretizam procedimentos específicos)
- Procedimentos de segurança — moderado-alto (conhecimento procedural de hardening)
- Procedimentos de negócio — alto (workflows específicos do contexto)
- Software Engineering genérico — baixo (+4,5pp em SkillsBench) — modelo já conhece padrões comuns
- Padrões de código bem conhecidos — prejudicial (skill distrai do contexto real)
Referências complementares: Most Agent Skills Fail
SkillsBench: Benchmarking How Well Agent Skills Work Across Diverse Tasks
Benchmark mais amplo que avalia skills em 86 tarefas distribuídas entre 11 domínios profissionais diferentes. Usa avaliação pareada (“vanilla” vs “skills-augmented”) com 7 configurações de agent-modelo.
Resultados em SkillsBench:
- Ganho médio de 16,2 pontos percentuais com skills curados manualmente
- Distribuição altamente desigual: Healthcare (+51,9pp) vs Software Engineering (+4,5pp)
- Skills auto-gerados produzem benefício negligenciável ou negativo — LLMs não conseguem sintetizar confiável a expertise procedural que deveriam consumir
Skill Injection: Fundamentos e Implementação
Skill injection é o processo de fornecer a um agente LLM um pacote discreto de conhecimento procedural ou de domínio. Implementado através de documentos estruturados (SKILL.md, manifestos YAML) contendo:
- Metadados (nome, descrição, versão, domínio)
- Corpo procedural: instruções em Markdown, templates de código, padrões de API, regras de negócio
- Artefatos executáveis: scripts Python/Bash e configurações
Em SWE-Skills-Bench, a injeção segue passos controlados: curação de skills, geração de instâncias, verificação determinística e avaliação pareada com métricas explícitas de pass/fail, tokens e custo.
Agent Skills: Definição Formal e Taxonomia
Survey que formaliza skills como artefatos procedurais reutilizáveis que codificam conhecimento “como fazer” — não apenas “o quê” pode ser feito, mas “quando” agir, “como” executar, heurísticas, modos de falha e critérios de conclusão.
Skills funcionam como memória procedural para agentes — compilando automaticamente habilidades repetitivas em sub-rotinas executáveis, habilitando ação fluida e contextualizada.
Formalmente representados como tuplas com: condições de ativação, instruções procedurais, restrições de aplicabilidade, interfaces de ferramentas, política de execução e efeitos esperados.
SWE-bench: Benchmark de Resolução de Issues em Engenharia de Software
Benchmark de referência mantido por Stanford e Princeton que avalia se LLMs e agentes conseguem resolver issues reais do GitHub. Diferente de SWE-Skills-Bench (que mede utilidade marginal de skills), SWE-bench mede capacidade absoluta de resolver problemas.
Tarefas envolvem: navegação em repositórios grandes, produção de patches corretos e mínimos, passagem nos testes existentes do projeto. Métrica: % Resolved (percentagem de instâncias resolvidas).
Variações: SWE-bench Verified (500 filtradas manualmente), Multilingual (300 em 9 linguagens), Lite, e Multimodal.
Avaliação e Testes de Agent Skills
OpenAI recomenda usar Evals para medir consistentemente a qualidade de agent skills ao longo do tempo — não apenas “se o resultado parece melhor”, mas verificações determinísticas como:
- O agente invocou o skill?
- Executou os comandos esperados?
- Seguiu as convenções solicitadas?
Evals para skills são testes end-to-end leves: executar o agente, gravar o que aconteceu, escore contra regras pequenas. Captura JSONL de traços com codex exec --json e executa verificações determinísticas sobre eventos.