A Anthropic finalmente divulgou sua metodologia interna de Skill

Li uma postagem no blog escrito pela equipe da Anthropic 《Lessons from building Claude Code: How we use skills》. Essa deve ser a análise mais aprofundada que vi até agora sobre Skills na prática.

Skill na verdade não é algo complicado, mas fazer um Skill bem feito, eu acho, também não é tão fácil assim.

Lembro que, quando Skills começaram a ficar populares, todo mundo adorava criar Skills de estilos de escrita, Skills de escrita. Parece que, só colocando seu estilo de escrita dentro, o modelo consegue manter esse estilo de forma estável na saída.

Mas depois de testar por conta própria, percebi que muitas vezes isso simplesmente não funciona.

Porque um Skill de estilo pode conter milhares ou até dezenas de milhares de palavras. Quando você carrega um Skill, o contexto ocupa uma grande parte da memória. Com o contexto pesado, a capacidade de raciocínio do modelo tende a diminuir.

No final, frequentemente acontece o seguinte: o estilo é aprendido, mas o conteúdo fica superficial, e a capacidade de análise também enfraquece.

Há também uma situação comum.

Muita gente escreve Skills incluindo várias instruções operacionais. Tipo: o que fazer na primeira etapa, na segunda, na terceira. E aí, ao rodar, o modelo não executa de forma estável.

Depois de refletir, percebi que muitas dessas tarefas repetitivas são mais adequadas para serem sedimentadas como Scripts, e não como instruções longas.

Depois de ler esse artigo da Anthropic, minha maior impressão é que muitas pessoas usam Skills, mas nem sempre entendem realmente o que é um Skill.

Na essência, Skill é uma forma de Engenharia de Contexto. Quando colocar conhecimento dentro de um Skill, quando dividir em Referências, quando escrever um Script, quando usar Gotchas para limitar o modelo — tudo isso envolve muita experiência.

Depois de entender o funcionamento do Skill, ao olhar para Skills excelentes, percebe-se que elas não resolvem problemas de prompt, mas sim questões de contexto, sedimentação de experiência e reutilização de capacidades.

Se alguém quer estudar Skills profundamente, recomendo especialmente duas artigos:

#01 Não escreva besteiras

Na essência, Skill é sedimentar o “conhecimento tácito” da organização. Portanto, dentro do Skill, não repita conhecimentos óbvios que já são de conhecimento comum. O que realmente tem valor são informações que o modelo não conhece de fato.

A equipe da Anthropic costuma enfatizar que o que deve ser escrito em um Skill são os Gotchas, ou seja, as armadilhas comuns.

Por exemplo:

1. Essa tabela não deve ser ordenada por created_at

2. Staging retornar 200 não significa sucesso

3. request_id e trace_id são a mesma coisa

Porque essas informações geralmente estão na experiência dos funcionários. Então, é importante lembrar qual é a essência do Skill.

Skill = colocar a experiência do especialista no papel.

Através do Skill, sedimenta-se a experiência que antes ficava dispersa na cabeça de diferentes pessoas.

#02 Skill na verdade é Engenharia de Contexto

Essa talvez seja uma das ideias mais profundas da Anthropic.

Skill não é um arquivo markdown, mas uma pasta. Para quem já usou Skills, parece óbvio.

Mas, refletindo esses dias, percebi que eles querem usar a estrutura de pasta para expressar a ideia de Engenharia de Contexto.

Vamos revisar a estrutura típica de um Skill:

skill/  ├── SKILL.md  ├── references/ (explicações detalhadas, referências de API, condições de limite)  ├── scripts/ (scripts executáveis)  ├── examples/ (exemplos)  ├── assets/ (modelos, imagens, materiais fixos)

Quando o modelo acessa um Skill, ele primeiro lê o SKILL.md. Se colocarmos todas as informações nesse arquivo, logo o contexto explode.

Por exemplo, um Skill de resolução de problemas de pagamento pode conter códigos de erro do Stripe, casos históricos, scripts de diagnóstico e modelos de relatórios finais.

Se tudo isso estiver no SKILL.md, toda vez que o Skill for chamado, o Claude precisa reler tudo.

Mesmo que o usuário só queira entender um código de erro ou verificar por que um pagamento não foi atualizado, muitas informações inúteis também entram no contexto.

A abordagem da Anthropic é completamente diferente.

O SKILL.md funciona mais como uma página de navegação. Sua função é informar ao modelo que, ao encontrar um erro do Stripe, ele deve consultar a pasta references para obter detalhes.

Quando precisar consultar casos históricos, deve olhar na pasta examples. Para executar ações de diagnóstico, rodar scripts na pasta scripts. E, ao gerar relatórios finais, usar os modelos na pasta assets.

Todo esse processo é uma exposição gradual.

A imagem abaixo, recomendo fortemente que todos salvem.

#03 Use scripts sempre que possível

Não deixe o modelo gastar seu limitado contexto e capacidade de raciocínio com tarefas repetitivas. Passe essas tarefas para scripts.

Por exemplo, muitos escrevem Skills assim:

1. Consultar dados de registro; 2. Consultar dados de pagamento; 3. Calcular taxa de conversão; 4. Analisar causas de anomalias.

Claro que essa abordagem funciona. O modelo consegue fazer. Mas, toda vez que roda, precisa refazer todo o fluxo de análise do zero.

Buscar dados, organizar, tratar limites — tudo isso é repetitivo.

Como essas tarefas já foram validadas muitas vezes, por que reinventar a roda toda vez? Melhor fornecer um script específico.

Além disso, usando scripts, a execução do Skill fica mais precisa e econômica em tokens.

De certa forma, os Scripts dentro do Skill representam a sedimentação da capacidade organizacional. Cada script é o resultado de muitas armadilhas que a equipe já superou, uma prática recomendada.

Ao consolidar essas habilidades, o Claude pode trabalhar sempre com base na experiência acumulada, sem precisar começar do zero toda vez.

Por isso, cada vez mais vejo que Instructions e Scripts no Skill resolvem problemas em níveis diferentes.

Instructions oferecem experiência e julgamento; Scripts oferecem capacidade e execução.

Por exemplo, em um Skill de resolução de problemas de pagamento, pode haver uma instrução assim:

Se Stripe retornar 200, não considere o pagamento como bem-sucedido sem verificar a tabela payment_events.

Isso é uma Instruction, pois é uma recomendação baseada na experiência. Já a função check_payment_events() é um Script, pois realiza uma ação de execução.

Se houver só Script, o modelo sabe como verificar, mas não sabe por quê.

Se houver só Instruction, o modelo sabe o que fazer, mas precisa reimplementar toda vez. Os dois juntos são essenciais.

#04 Descrição como uma regra de roteamento

Muita gente escreve a descrição do Skill de forma errada por padrão.

Porque costumam focar na funcionalidade. Por exemplo: PR Management Skill ajuda a monitorar PRs, lidar com CI, fazer merge automático.

Mas o problema é que o modelo não busca Skills por funcionalidades, e sim por nomes e descrições.

Quando o Claude Code inicia, ele escaneia todos os nomes e descrições de Skills para decidir qual carregar.

Portanto, o mais importante na descrição não é o que o Skill faz, mas em que situação deve ser carregado.

A descrição funciona como uma rota, indicando ao modelo quando usar aquele Skill.

Na vida real, ninguém costuma dizer: “Por favor, chame uma ferramenta de gerenciamento de PR”. É mais comum: “Me ajuda a monitorar esse PR, o CI deu problema, etc.”

Então, uma boa descrição deve focar na intenção do usuário, não em listar funcionalidades.

Posso até usar um método simples para verificar isso.

Depois de escrever a descrição, apague o Skill inteiro, deixando só a linha da descrição. Pergunte a si mesmo: ao ver a questão do usuário, o modelo consegue entender quando deve usar esse Skill?

Se não conseguir, provavelmente precisa ajustar.

#05 Gestão e distribuição de Skills

Outro ponto importante é a gestão de Skills.

Para uma pessoa que usa poucos Skills, é simples: escreve, mantém, atualiza por conta própria. Mas acredito que a maioria das equipes enfrentará o mesmo problema.

Quando o número de Skills passa de alguns para dezenas ou centenas, como gerenciar? Como atualizar? Como distribuir para a equipe?

A experiência da Anthropic nesse aspecto é bastante valiosa.

Em times pequenos, Skills seguem o repositório de código, na pasta .claude/skills do projeto. Todos compartilham a mesma base de Skills e métodos de trabalho.

Mas, com o aumento do número de Skills, surge uma nova questão.

Na inicialização do Claude Code, ele escaneia todos os nomes e descrições para decidir qual Skill usar. Quanto mais Skills, maior o custo de roteamento.

Por isso, a Anthropic começou a criar um Marketplace. Mas, mais interessante, é como eles gerenciam esse Marketplace.

Muitas empresas criam processos de aprovação: quem criou o Skill, precisa submeter uma solicitação; após aprovação, entra na biblioteca oficial. Já fizemos assim também, mas é muito burocrático.

A equipe da Anthropic é mais ágil.

Deixam os Skills iniciais rodando em um ambiente controlado, para que colegas possam instalar, testar por conta própria.

Se mais pessoas começarem a usar, é sinal de que o Skill resolve um problema real. Nesse momento, o autor pode submetê-lo ao Marketplace oficial.

Eles não avaliam o valor do Skill antes, mas deixam que ele seja testado na prática. Quanto mais uso, mais ele entra na rotina oficial. Assim, os Skills que permanecem são realmente úteis para a equipe.