As habilidades se tornaram um dos pontos de extensão mais usados no Claude Code. Elas são flexíveis, flexíveis, fáceis de criar e simples de distribuir.
Mas essa flexibilidade também dificulta saber o que funciona melhor. Que tipo de habilidades vale a pena criar? Qual é o segredo para escrever uma boa habilidade? Quando você as compartilha com outras pessoas?
Nós, na Anthropic, usamos habilidades extensivamente no Claude Code, com centenas delas em uso ativo. Estas são as lições que aprendemos sobre como usar habilidades para acelerar nosso desenvolvimento.
O que são Habilidades?
Se você é novo em habilidades, eu recomendo ler nossa documentação ou assistir ao nosso mais novo curso sobre novo Skilljar sobre Habilidades de Agente. Este post pressupõe que você já tem alguma familiaridade com habilidades.
Um equívoco comum que ouvimos sobre habilidades é que elas são "apenas arquivos markdown", mas a parte mais interessante das habilidades é que elas não são apenas arquivos de texto. Elas são pastas que podem incluir scripts, assets, dados, etc. que o agente pode descobrir, explorar e manipular.
No Claude Code, as habilidades também têm uma ampla variedade de opções de configuração, incluindo o registro de hooks dinâmicos registráveis.
Descobrimos que algumas das habilidades mais interessantes no Claude Code usam essas opções de configuração e a estrutura de pastas de forma criativa.
Tipos de Habilidades
Depois de catalogar todas as nossas habilidades, notamos que elas se agrupam em algumas categorias recorrentes. As melhores habilidades se encaixam perfeitamente em uma; as mais confusas abrangem várias. Esta não é uma lista definitiva, mas é uma boa maneira de pensar se você está perdendo alguma dentro da sua organização.
1. Referência de Biblioteca e API
Habilidades que explicam como usar corretamente uma biblioteca, CLI ou SDKs. Podem ser tanto para bibliotecas internas quanto para bibliotecas comuns com as quais o Claude Code às vezes tem dificuldades. Essas habilidades geralmente incluem uma pasta de trechos de código de referência e uma lista de pegadinhas para Claude evitar ao escrever um script.
Exemplos:
- billing-lib — sua biblioteca de faturamento interno: casos extremos, armadilhas, etc.
- internal-platform-cli — cada subcomando do seu wrapper CLI interno com exemplos de quando usá-los
- frontend-design — tornar Claude melhor no seu sistema de design
2. Verificação de Produto
Habilidades que descrevem como testar ou verificar se seu código está funcionando. Elas são frequentemente emparelhadas com uma ferramenta externa como Playwright, tmux, etc. para realizar a verificação.
Habilidades de verificação são extremamente úteis para garantir que a saída do Claude esteja correta. Pode valer a pena fazer um engenheiro gastar uma semana apenas para tornar suas habilidades de verificação excelentes.
Considere técnicas como fazer Claude gravar um vídeo de sua saída para que você possa ver exatamente o que ele testou, ou impor asserções programáticas no estado em cada etapa. Isso geralmente é feito incluindo uma variedade de scripts na habilidade.
Exemplos:
- signup-flow-driver — percorre cadastro → verificação de e-mail → integração em um navegador headless, com hooks para afirmar o estado em cada etapa
- checkout-verifier — aciona a interface de checkout com cartões de teste do Stripe, verifica se a fatura realmente cai no estado correto
- tmux-cli-driver — para testes interativos de CLI onde a coisa que você está verificando precisa de um TTY
/terminal
3. Busca e Análise de Dados
Habilidades que se conectam às suas pilhas de dados e monitoramento. Essas habilidades podem incluir bibliotecas para buscar seus dados com credenciais, IDs de dashboard específicos, etc., bem como instruções sobre fluxos de trabalho comuns ou maneiras de obter dados.
Exemplos:
- funnel-query — "quais eventos eu junto para ver cadastro → ativação → pago" mais a tabela que realmente tem o user_id canônico
- cohort-compare — comparar a retenção ou conversão de duas coortes, sinalizar deltas estatisticamente significativos, vincular às definições de segmento
- grafana — UIDs da fonte de dados, nomes de cluster, tabela de consulta problema → dashboard
4. Processo de Negócios e Automação de Equipe
Habilidades que automatizam fluxos de trabalho repetitivos em um único comando. Essas habilidades geralmente são instruções bastante simples, mas podem ter dependências mais complicadas em outras habilidades ou MCPs. Para essas habilidades, salvar resultados anteriores em arquivos de log pode ajudar o modelo a ser consistente e refletir sobre execu sobre execuções anteriores do fluxo de trabalho.
Exemplos:
- standup-post — agrega seu rastreador de tickets, atividade no GitHub e Slack anterior → standup formatado, apenas deltas
- create-<sistema-de-tickets>-ticket — impõe esquema (valores de enum válidos, campos obrigatórios) mais fluxo de pós-criação (notificar revisor, link no Slack)
- weekly-recap — PRs mesclados + tickets fechados + deploys → recapitulação semanal formatada
5. Scaffolding e Templates de Código
Habilidades que geram boilerplate de framework para uma função específica na base de código. Você pode combinar essas habilidades com scripts que podem ser compostos. Elas são especialmente úteis quando seu scaffolding tem requisitos de linguagem natural que não podem ser cobertos puramente por código.
Exemplos:
- new-<framework>-workflow — cria um novo serviço/fluxo de trabalho/handler com suas anotações
- new-migration — seu template de arquivo de migração mais as pegadinhas comuns
- create-app — novo aplicativo interno com sua configuração de autenticação, registro e deploy pré-configurada
6. Qualidade e Revisão de Código
Habilidades que impõem qualidade de código dentro de sua organização e ajudam a revisar código. Elas podem incluir scripts ou ferramentas determinísticas para máxima robustez. Você pode querer executar essas habilidades automaticamente como parte de hooks ou dentro de uma GitHub Action.
- adversarial-review — cria um subagente de olhos frescos para criticar, implementa correções, itera até que os achados sejam reduzidos a pequenos ajustes
- code-style — impõe estilo de código, especialmente estilos que Claude não faz bem por padrão.
- testing-practices — instruções sobre como escrever testes e o que testar.
7. CI/CD e Deploy
Habilidades que ajudam você a buscar, enviar e implantar código dentro de sua base de código. Essas habilidades podem referenciar outras habilidades para coletar dados.
Exemplos:
- babysit-pr — monitora um PR → tenta novamente CI instável → resolve conflitos de mesclagem → ativa auto-merge
- deploy-<serviço> — construir → teste de fumaça → rollout gradual de tráfego com comparação de taxa de erro → rollback automático em caso de regressão
- cherry-pick-prod — worktree isolado → cherry-pick → resolução de conflitos → PR com template
8. Runbooks
Habilidades que pegam um sintoma (como uma thread do Slack, alerta ou assinatura de erro), percorrem uma investigação em várias ferramentas e produzem um relatório estruturado.
Exemplos:
- <serviço>-debugging — mapeia sintomas → ferramentas → padrões de consulta para seus serviços de maior tráfego
- oncall-runner — busca o alerta → verifica os suspeitos usuais → formata um achado
- log-correlator — dado um ID de requisição, puxa logs correspondentes de todos os sistemas que podem ter tocado nela
9. Operações de Infraestrutura
Habilidades que realizam manutenção de rotina e procedimentos operacionais — alguns dos quais envolvem ações destrutivas que se beneficiam de proteções. Elas facilitam para os engenheiros seguirem as melhores práticas em operações críticas.
Exemplos:
- <recurso>-orphans — encontra pods/volumes órfãos → posta no Slack → período de espera → usuário confirma → limpeza em cascata
- dependency-management — seu fluxo de aprovação de dependência da organização
- cost-investigation — "por que nossa conta de armazenamento/saída disparou" com os buckets e padrões de consulta específicos
Dicas para Criar Habilidades
Depois de decidir qual habilidade criar, como você a escreve? Estas são algumas das melhores práticas, dicas e truques que descobrimos.
Também lançamos recentemente o Skill Creator para facilitar a criação de habilidades no Claude Code.
Não Declare o Óbvio
O Claude Code sabe muito sobre sua base de código, e Claude sabe muito sobre programação, incluindo muitas opiniões padrão. Se você está publicando uma habilidade que é principalmente sobre conhecimento, tente focar em informações que tirem Claude de sua forma normal de pensar.
A habilidade de design frontend é um ótimo exemplo — foi construída por um dos engenheiros da Anthropic iterando com clientes para melhorar o gosto de design do Claude, evitando padrões clássicos como a fonte Inter e gradientes roxos.
Crie uma Seção de Pegadinhas
O conteúdo de maior sinal em qualquer habilidade é a seção de Pegadinhas. Essas seções devem ser construídas a partir de pontos de falha comuns que Claude encontra ao usar sua habilidade. Idealmente, você atualizará sua habilidade ao longo do tempo para capturar essas pegadinhas.
Use o Sistema de Arquivos e Divulgação Progressiva
Como dissemos antes, uma habilidade é uma pasta, não apenas um arquivo markdown. Você deve pensar em todo o sistema de arquivos como uma forma de engenharia de contexto e divulgação progressiva. Diga a Claude quais arquivos estão em sua habilidade, e ele os lerá em momentos apropriados.
A forma mais simples de divulgação progressiva é apontar para outros arquivos markdown para Claude usar. Por exemplo, você pode dividir assinaturas de função detalhadas e exemplos de uso em references/api.md.
Outro exemplo: se sua saída final for um arquivo markdown, você pode incluir um arquivo de template para ele em assets/ para copiar e usar.
Você pode ter pastas de referências, scripts, exemplos, etc., que ajudam Claude a trabalhar de forma mais eficaz.
Evite Engessar Claude
Claude geralmente tentará seguir suas instruções e, como as Habilidades são tão reutilizáveis, você deve tomar cuidado para não ser muito específico em suas instruções. Dê a Claude as informações de que ele precisa, mas dê a ele a flexibilidade para se adaptar à situação. Por exemplo:
Pense na Configuração Inicial
Algumas habilidades podem precisar ser configuradas com contexto do usuário. Por exemplo, se você está criando uma habilidade que publica seu standup no Slack, pode querer que Claude pergunte em qual canal do Slack publicá-lo.
Um bom padrão para fazer isso é armazenar essas informações de configuração em um arquivo config.json no diretório da habilidade, como no exemplo acima. Se a config não estiver configurada, o agente pode então perguntar ao usuário as informações.
Se você quiser que o agente apresente questões de múltipla escolha estruturadas, pode instruir Claude a usar a ferramenta AskUserQuestion.
O Campo Descrição é Para o Modelo
Quando o Claude Code inicia uma sessão, ele constrói uma listagem de cada habilidade disponível com sua descrição. Essa listagem é o que Claude examina para decidir "existe uma habilidade para esta solicitação?" O que significa que o campo descrição não é um resumo — é uma descrição de quando acionar esta habilidade.
Memória e Armazenamento de Dados
Algumas habilidades podem incluir uma forma de memória armazenando dados dentro delas. Você pode armazenar dados em algo tão simples quanto um arquivo de log de texto somente anexado ou arquivos JSON, ou tão complexo quanto um banco de dados SQLite.
Por exemplo, uma habilidade standup-post pode manter um standups.log com cada post que escreveu, o que significa que na próxima vez que você executá-la, Claude lê seu próprio histórico e pode dizer o que mudou desde ontem.
Os dados armazenados no diretório da habilidade podem ser excluídos quando você atualiza a habilidade, então você deve armazená-los em uma pasta estável. Atualmente, fornecemos \${**CLAUDE_PLUGIN_DATA**}\ como uma pasta estável por plugin para armazenar dados.
Armazene Scripts e Gere Código
Uma das ferramentas mais poderosas que você pode dar a Claude é código. Dar scripts e bibliotecas a Claude permite que ele gaste suas rodadas de interação em composição, decidindo o que fazer a seguir, em vez de reconstruir boilerplate.
Por exemplo, em sua habilidade de ciência de dados, você pode ter uma biblioteca de funções para buscar dados de sua fonte de eventos. Para que Claude possa fazer análises complexas, você pode dar a ele um conjunto de funções auxiliares como estas:
Claude pode então gerar scripts dinamicamente para compor essa funcionalidade e fazer análises mais avançadas para prompts como "O que aconteceu na terça-feira?"
Hooks Sob Demanda
As habilidades podem incluir hooks que são ativados apenas quando a habilidade é chamada e duram pela duração da sessão. Use isso para hooks mais opinativos que você não quer executar o tempo todo, mas são extremamente úteis às vezes.
Por exemplo:
- /cuidado — bloqueia rm -rf, DROP TABLE, força-push, kubectl delete através do matcher PreToolUse no Bash. Você só quer isso quando sabe que está tocando em produção — tê-lo sempre ativo te enlouqueceria
- /congelar — bloqueia qualquer Editar/Escrever que não esteja em um diretório específico. Útil
- ao depurar: "Quero adicionar logs, mas fico acidentalmente 'corrigindo' coisas não relacionadas"
Distribuindo Habilidades
Um dos maiores benefícios das Habilidades é que você pode compartilhá-las com o resto da sua equipe.
Há duas maneiras de compartilhar habilidades com outras pessoas:
- verificar suas habilidades em seu repositório (em ./.claude/skills)
- criar um plugin e ter um mercado de plugins Claude Code onde os usuários podem carregar e instalar plugins (leia mais na documentação aqui)
Para equipes menores trabalhando em relativamente poucos repositórios, verificar suas habilidades nos repositórios funciona bem. Mas cada habilidade verificada também adiciona um pouco ao contexto do modelo. À medida que você escala, um mercado de plugins interno permite distribuir habilidades e deixar sua equipe decidir quais instalar.
Gerenciando um Mercado
Como você decide quais habilidades vão para um mercado? Como as pessoas as submetem?
Não temos uma equipe centralizada que decide; em vez disso, tentamos encontrar as habilidades mais úteis organicamente. Se você tem uma habilidade que quer que as pessoas experimentem, pode carregá-la em uma pasta sandbox no GitHub e apontar as pessoas para ela no Slack ou outros fóruns.
Depois que uma habilidade ganhou tração (o que cabe ao proprietário da habilidade decidir), eles podem fazer um PR para movê-la para o mercado.
Um aviso: pode ser muito fácil criar habilidades ruins ou redundantes, portanto, garantir que você tenha algum método de curadoria antes do lançamento é importante.
Compondo Habilidades
Você pode querer ter habilidades que dependem umas das outras. Por exemplo, você pode ter uma habilidade de upload de arquivo que envia um arquivo e uma habilidade de geração de CSV que cria um CSV e o envia. Esse tipo de gerenciamento de dependência ainda não é nativo dos mercados ou habilidades, mas você pode simplesmente referenciar outras habilidades pelo nome, e o modelo as invocará se estiverem instaladas.
Medindo Habilidades
Para entender como uma habilidade está indo, usamos um hook PreToolUse que nos permite registrar o uso da habilidade dentro da empresa (código de exemplo aqui). Isso significa que podemos encontrar habilidades que sã populares ou que estão sendo subutilizadas em comparação com nossas expectativas.
Conclusão
As Habilidades são ferramentas incrivelmente poderosas e flexíveis para agentes, mas ainda é cedo e todos estamos descobrindo como usá-las da melhor forma.
Pense nisso mais como uma coleção de dicas úteis que vimos funcionar, do que um guia definitivo. A melhor maneira de entender as habilidades é começar, experimentar e ver o que funciona para você. A maioria das nossas começou com algumas linhas e uma única pegadinha, e melhorou porque as pessoas continuaram adicionando a elas à medida que Claude encontrava novos casos extremos.
Espero que isso tenha sido útil. Me avise se tiver alguma dúvida.
