A maioria das pessoas escreveu Skill de forma incorreta: 5 reflexões após a divulgação da metodologia interna pela Anthropic

Autor: AI Produto Aying

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

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

Lembro que, quando Skill virou moda, todo mundo adorava criar vários Skills de estilo de escrita, Skills de escrita. Parece que, só por colocar seu próprio estilo de escrita, o modelo consegue gerar de forma estável nesse estilo.

Mas depois de experimentar um pouco, percebi que muitas vezes isso simplesmente não funciona.

Porque um Skill de estilo pode conter apenas algumas milhares ou até dezenas de milhares de palavras. Quando um Skill é carregado, o contexto ocupa uma grande parte. 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 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 muitas dessas tarefas repetitivas são mais adequadas para serem sedimentadas em Scripts, e não em instruções longas.

Depois de ler este artigo da Anthropic, minha maior impressão foi que muitas pessoas estão usando Skills, mas nem sempre compreendem 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 limitar o modelo, há muita experiência envolvida nisso.

Depois de entender o funcionamento do Skill, ao revisitar Skills excelentes, percebemos que elas não resolvem problemas de prompts, mas sim questões de contexto, sedimentação de experiência e reutilização de capacidades.

Se alguém deseja 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, não repita no Skill conhecimentos que já são óbvios. O que realmente tem valor são informações que o modelo não conhece de jeito nenhum.

Dentro da Anthropic, eles frequentemente enfatizam que o que deve ser escrito em um Skill são os Gotchas, ou seja, as armadilhas comuns.

Por exemplo:

1. Esta 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 = colocar a experiência de mestres artesãos no papel.

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, refleti bastante e 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 API, condições de limite) ├── scripts/ (scripts executáveis) ├── examples/ (exemplos) ├── assets/ (modelos, imagens, materiais fixos)

Quando se chama um Skill, o modelo 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, que contém códigos de erro do Stripe, casos históricos, scripts de diagnóstico e modelos de relatórios finais.

Se tudo isso for acumulado 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 referência correspondente.

Quando precisar consultar casos históricos, vá para examples; quando precisar executar uma ação de diagnóstico, rode scripts; e, ao gerar o relatório final, use os modelos em assets.

Todo o processo é uma exposição progressiva.

A imagem abaixo, 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 com tarefas repetitivas. Deixe essas tarefas para os 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 executa, precisa refazer todo o fluxo de análise do zero.

Consultar dados, organizar dados, lidar com várias condições de limite — essas tarefas são repetitivas.

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

Além disso, usando scripts, a execução do Skill será mais precisa e economizará Tokens.

Sob essa perspectiva, os Scripts no Skill representam a sedimentação da capacidade organizacional. Cada script é o resultado de muitas armadilhas que a equipe superou, condensando as melhores práticas.

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 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 o 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á check_payment_events() é um Script, pois é uma capacidade de execução.

Se houver apenas Script, o modelo sabe como consultar, mas não sabe por quê.

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

#04 Descrição funciona mais como uma regra de roteamento

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

Porque costumam escrever uma introdução às funcionalidades, como: PR Management Skill ajuda a monitorar PRs, lidar com problemas de CI, fazer merge automaticamente.

Mas o problema é que o modelo não busca Skills por funcionalidades. Quando o Claude Code inicia, ele escaneia os nomes e descrições de todos os Skills.

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

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

A Descrição na verdade faz o papel de roteamento do Skill.

No mundo real, poucos dizem: «Me ajude a usar uma ferramenta de gerenciamento de PR». É mais comum dizer: «Fique de olho nesse PR», «O CI deu problema», etc.

Por isso, 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ó 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 uma pessoa que usa Skills, é 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 neste aspecto é bastante valiosa.

Quando a equipe é pequena, os Skills seguem o repositório de código. Ficam na pasta .claude/skills do projeto. Todos compartilham o mesmo conjunto de Skills e métodos de trabalho.

Mas, à medida que o número de Skills aumenta, surge uma nova questão.

Na inicialização do Claude Code, ele escaneia todos os Skills pelo nome e descrição, e decide qual chamar. 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 enfrentar esse problema, criam um fluxo de aprovação. Quem criou o Skill, precisa submeter uma solicitação; após aprovação, entra na biblioteca oficial. Nós também fizemos assim, mas era uma gestão pesada.

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

Deixam que novos Skills se espalhem inicialmente em um pequeno grupo, que instala e testa 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 primeiro se o Skill tem valor, mas deixam que ele seja testado em cenários reais. Quanto mais uso, mais ele entra na体系. Assim, os Skills que permanecem são realmente necessários para a equipe.