A Anthropic finalmente revelou publicamente a sua metodologia interna de Skill

Li uma postagem do blog escrito pela equipe da Anthropic intitulada 《Lessons from building Claude Code: How we use skills》. Esta deve ser a análise de prática mais aprofundada que já vi até agora sobre Skill.

Skill na verdade não é algo complicado, mas realmente querer fazer um Skill bem feito, acho que não é tão fácil assim.

Lembro que, quando o Skill ficou popular, todo mundo gostava de criar vários Skills de estilo de escrita, Skills de escrita. Parece que, só ao inserir seu próprio estilo de escrita, o modelo consegue gerar de forma estável nesse estilo.

Mas depois de experimentar por minha conta, percebi que muitas vezes isso simplesmente não funciona.

Porque um estilo de escrita Skill pode conter apenas algumas milhares ou até dezenas de milhares de palavras. Quando um Skill é carregado, o contexto ocupa uma grande parte dele. Com o contexto pesado, a capacidade de raciocínio do modelo tende a diminuir.

No final, frequentemente ocorre uma situação: o estilo é aprendido, mas o conteúdo fica superficial, e a capacidade de análise também enfraquece.

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

Muita gente ao criar Skills gosta de inserir várias instruções operacionais. Primeiro passo, fazer isso; segundo passo, fazer aquilo; terceiro passo, fazer aquilo outro. E, ao rodar, percebe que a execução do modelo não é estável.

Depois, comecei a entender lentamente que muitos desses trabalhos repetitivos são mais adequados para serem sedimentados em Scripts, e não escritos como instruções longas.

Depois de ler este artigo da Anthropic, minha maior impressão é que muitas pessoas estão usando Skills, mas talvez não compreendam realmente o que é um Skill.

Na essência, Skill é uma forma de Engenharia de Contexto. Quando deve-se colocar conhecimento dentro de um Skill, quando deve-se dividir em Referências, quando deve-se escrever como Script, quando usar Gotchas para restringir o modelo — há muita experiência envolvida nisso.

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 é a sedimentação do "conhecimento tácito" dentro de uma organização. Portanto, não repita no Skill conhecimentos que já são óbvios. O que realmente tem valor são informações que o modelo em si não conhece.

Dentro da Anthropic, eles frequentemente enfatizam que o que deve ser escrito no 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, é fundamental lembrar qual é a essência do Skill.

Skill = escrever a experiência de mestres e veteranos.

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

#02 Skill na verdade é Engenharia de Contexto

Este talvez seja um dos conceitos mais profundos da Anthropic.

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

Mas, nestes dias, refletindo repetidamente, percebi lentamente: 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 se chama um Skill, o primeiro arquivo que o modelo lê é o SKILL.md. Se colocarmos todas as informações nesse arquivo, logo o contexto explode.

Por exemplo, imagine um Skill de resolução de problemas de pagamento, que contém tanto códigos de erro do Stripe, quanto casos históricos, scripts de diagnóstico e modelos de relatórios finais.

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

Mesmo que o usuário só queira entender o significado de um código de erro ou verificar por que um status de pagamento não foi atualizado, muitas informações inúteis também serão carregadas 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 a explicação correspondente.

Quando precisar consultar casos históricos, procurar na pasta examples; quando precisar executar ações de diagnóstico, rodar scripts; e, ao gerar o relatório final, usar os modelos na pasta assets.

Todo o processo é uma exposição progressiva.

Esta imagem aqui, recomendo fortemente que todos salvem.

#03 Use scripts sempre que possível

Não deixe o modelo desperdiçar seu limitado contexto e capacidade de raciocínio em tarefas repetitivas. Passe essas tarefas para scripts.

Por exemplo, muitas pessoas ao criar Skills fazem 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, a cada execução, ele precisa refazer todo o fluxo de análise do zero.

Buscar dados, organizar, tratar condições de borda — tudo isso é repetitivo.

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

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

Sob esse ponto de vista, os Scripts dentro do Skill representam a sedimentação da capacidade organizacional. Cada script é o resultado de muitas armadilhas e melhores práticas que a equipe aprendeu ao longo do tempo.

Ao consolidar essas capacidades, o Claude pode trabalhar sempre com base nessas experiências, ao invés de começar do zero toda vez.

Por isso, cada vez mais vejo que, dentro do Skill, Instructions e Scripts 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 experiência. Já a função check_payment_events() é um Script, pois é uma capacidade de execução.

Se houver só Script, o modelo sabe como fazer a consulta, mas não 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 apresentação das funcionalidades, como: PR Management Skill ajuda a monitorar PRs, lidar com problemas de CI, fazer merge automático.

Mas o problema é que o modelo não busca Skills por funcionalidades, ao iniciar o Claude Code, ele escaneia os nomes e as Descrições de todos os Skills.

Depois, com base na questão do usuário, decide qual Skill carregar.

Portanto, o mais importante na Descrição não é o que o Skill faz, mas em que circunstâncias deve ser carregado.

A Descrição funciona como uma espécie de roteador do Skill.

Na vida real, poucos dizem: “Me ajude a usar uma ferramenta de gerenciamento de PR”. É mais comum: “Me ajuda a monitorar esse PR”, ou “O CI deu problema”.

Assim, uma boa Descrição deve focar em descrever a intenção do usuário, não listar funcionalidades.

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

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

Se não conseguir, provavelmente ainda precisa ajustar.

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

Outro ponto importante é a gestão de Skills.

Para um usuário individual, é simples: criar alguns Skills, manter, atualizar. 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 gerenciá-los? Como atualizar? Como distribuir para os membros da equipe?

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

Quando a equipe é pequena, os Skills ficam no repositório de código, na pasta .claude/skills do projeto. Todos compartilham a mesma coleção 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 Skills pelo nome e descrição, e decide qual usar. Quanto mais Skills, maior o custo de roteamento.

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

Muitas empresas, ao enfrentarem esse problema, criam processos de aprovação. Quem criou o Skill, precisa submeter para aprovação; após revisão, entra na biblioteca oficial. Nós também fizemos assim antes, mas era muito burocrático.

Percebi que a organização da Anthropic é bem mais leve.

Deixam que novos Skills se espalhem inicialmente em pequenos grupos, que os colegas instalem e testem por conta própria.

Se mais pessoas começarem a usar, indica que o Skill resolve um problema real. Então, o autor pode submetê-lo ao Marketplace oficial.

Eles não avaliam se o Skill tem valor antes, mas deixam que ele seja testado na prática. Quanto mais uso, mais ele entra na estrutura oficial. Assim, os Skills que permanecem são aqueles realmente necessários pela equipe.