O Que Centenas de Skills em Produção Ensinam Sobre Engenharia de Agentes

Thariq, engenheiro da Anthropic, publicou recentemente um relato sobre como a empresa usa skills internamente. O número que ele cita: “centenas em uso ativo.” O artigo não é um tutorial. É um relatório de campo. E relatórios de campo revelam coisas que tutoriais escondem.

Três padrões se destacam. Primeiro, a unidade de valor não é o arquivo de instrução. É a pasta. Segundo, skills de verificação têm retorno desproporcional comparadas a skills de geração. Terceiro, governança em escala exige pipeline, não confiança.

Cada um desses padrões tem implicações práticas para quem está construindo sistemas de agentes hoje.

A Pasta É o Produto

A maioria das pessoas entende skills como arquivos markdown com instruções para o agente. Thariq descreve algo diferente. Na Anthropic, uma skill é uma pasta com estrutura própria: scripts, assets, configurações, hooks. O arquivo de instrução é apenas a camada visível.

Essa distinção importa porque muda o que uma skill pode fazer. Um arquivo de instrução diz ao agente como pensar. Uma pasta dá ao agente um ambiente completo para operar. Scripts determinísticos convivem com raciocínio não-determinístico. A parte testável fica separada da parte imprevisível.

Como exploramos anteriormente, essa separação é o que torna skills auditáveis. Mas o relato de Thariq adiciona uma camada: quando a skill é uma pasta, ela se torna uma unidade de engenharia de contexto. O sistema de arquivos funciona como mecanismo de progressive disclosure. O agente carrega metadados primeiro (dezenas de tokens), instruções depois (milhares), e scripts sob demanda.

Thariq propõe nove categorias: Library Reference, Product Verification, Data Fetching, Business Process, Code Scaffolding, Code Quality, CI/CD, Runbooks, Infrastructure Ops. A taxonomia é útil como ponto de partida, mas tem sobreposições visíveis. Runbooks e Infrastructure Ops, por exemplo, compartilham território. Organizações que adotarem essa classificação vão precisar adaptá-la ao próprio contexto.

Verificação Supera Geração

De todas as categorias, Thariq destaca uma com ênfase incomum: Product Verification. A frase dele é direta. “Vale a pena um engenheiro gastar uma semana inteira construindo skills de verificação excelentes.”

Uma semana. Para uma skill. A afirmação parece exagerada até que você considera o contexto. Em sistemas agênticos, gerar código é barato. Validar se o código gerado está correto, segue padrões, e não introduz regressões é o gargalo real. A geração escala com compute. A verificação escala com engenharia.

Esse insight inverte a intuição comum. A maioria das equipes investe primeiro em skills de geração (scaffolding, templates, automação de boilerplate) e trata verificação como etapa posterior. O relato da Anthropic sugere que a ordem deveria ser inversa. Construa a verificação primeiro. O retorno compõe a cada execução.

É o mesmo princípio que sustenta agentes autoaperfeiçoantes: o valor não está na execução individual, mas no loop de feedback que melhora cada execução subsequente. Skills de verificação são esse loop, codificado.

Gotchas Valem Mais Que Instruções

Thariq tem uma recomendação que contradiz a intuição de quem escreve documentação: “não declare o óbvio.” O conteúdo de maior valor dentro de uma skill, segundo ele, é a seção de Gotchas. Não as instruções gerais. Não a descrição do fluxo. Os casos de borda. As armadilhas. O que dá errado e por quê.

Um estudo da ETH Zurich (Gloaguen et al.) dá suporte empírico a essa posição. Pesquisadores analisaram a eficácia de arquivos de contexto e encontraram que versões verbosas degradam a performance do agente em aproximadamente 3% e aumentam custos em 20%. Mais contexto não é melhor contexto. Contexto preciso é melhor contexto.

A implicação para quem constrói skills: resista à tentação de documentar tudo. Documente o que surpreende. Se uma API retorna 200 mas o corpo está vazio em certas condições, isso é um Gotcha. Se o linter ignora arquivos em subpastas específicas, isso é um Gotcha. Se o deploy funciona localmente mas falha no CI por causa de variáveis de ambiente, isso é um Gotcha.

Instruções óbvias consomem contexto sem adicionar valor. Gotchas consomem pouco contexto e previnem erros caros.

Governança Não É Opcional em Escala

Quando uma organização tem meia dúzia de skills, governança é informal. Quando tem centenas, precisa de processo. Thariq descreve um pipeline com três estágios: sandbox (experimentação individual), tração (adoção orgânica por outros engenheiros), e PR (promoção formal ao repositório compartilhado).

O modelo lembra processos de promoção de código em empresas maduras. Não é acidental. Skills em escala apresentam os mesmos problemas que código em escala: duplicação, conflito de convenções, dependências não documentadas, abandono silencioso.

Administradores podem provisionar skills centralmente. Hooks do tipo PreToolUse permitem medir uso e aplicar políticas. Skills podem armazenar dados operacionais (logs, JSON, SQLite) via variáveis de ambiente dedicadas. Hooks on-demand, ativados apenas quando a skill é invocada, evitam sobrecarga no restante do sistema.

Esse ferramental de governança é necessário. Mas é importante notar o que está ausente do relato: segurança. A Check Point Research divulgou vulnerabilidades (CVE-2025-59536, CVE-2026-21852) demonstrando que skills podem ser vetores de execução remota de código e exfiltração de tokens de API. Thariq não aborda esse vetor. Para organizações avaliando adoção em escala, a superfície de ataque de skills merece análise dedicada, independente do que a Anthropic publica.

O Que Não Está No Relato

Três ausências merecem nota.

Primeira: não há métricas sobre o que “uso ativo” significa. Centenas de skills existem no repositório. Quantas são executadas diariamente? Quantas foram abandonadas? Sem esses números, o claim de escala é qualitativo.

Segunda: as lições vêm exclusivamente de skills que funcionaram. Viés de sobrevivência é esperado em relatos internos, mas limita a utilidade para quem quer evitar falhas. O que dá errado quando skills proliferam sem controle? A comunidade de praticantes já documenta “skill bloat” como problema real. Thariq não menciona.

Terceira: o relato assume uma equipe de engenharia sofisticada. Skills como pastas com hooks, scripts, e pipelines de promoção exigem maturidade operacional que a maioria das organizações ainda não tem. A distância entre “crie um SKILL.md” e “opere centenas de skills com governança” é considerável.

Lições Para Praticantes

Para quem está construindo sistemas de agentes hoje, o relato de Thariq destila em três princípios aplicáveis.

Invista em verificação antes de geração. O retorno compõe. Uma skill de verificação bem construída melhora toda execução futura do agente. Uma skill de geração melhora apenas a execução que a invoca.

Documente o inesperado, não o óbvio. Gotchas previnem erros. Instruções genéricas consomem contexto. Se você precisa escolher entre documentar o fluxo feliz e documentar os casos de borda, escolha os casos de borda.

Planeje governança desde o início. O custo de adicionar governança depois é sempre maior que o custo de incluí-la no design. Pipeline de promoção, métricas de uso, e políticas de manutenção não são luxo. São requisitos para operar skills em escala, como discutimos na análise do padrão Agent Skills.

O relato de Thariq confirma o que praticantes já percebem: skills são a unidade operacional de sistemas de agentes. Entender como uma organização sofisticada opera centenas delas é valioso. Mas adotar o padrão sem considerar segurança, manutenção, e maturidade operacional é repetir o ciclo de hype que já comprometeu outras ondas de adoção de IA.

Fontes

Thariq (Anthropic). “Lessons from Building Claude Code: How We Use Skills.” Março 2026.
ETH Zurich (Gloaguen et al.). “Study on AGENTS.md Effectiveness.” Fevereiro 2026.
Check Point Research. “RCE and API Token Exfiltration Through Claude Code.” Fevereiro 2026.

Victorino Group ajuda organizações a construir sistemas de agentes de IA com arquiteturas de skills governadas: contato@victorino.com.br | www.victorino.com.br