As habilidades se tornaram um dos pontos de extensão mais utilizados no Claude Code. Elas são 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, da 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 no conceito de habilidades, recomendo ler nossa documentação ou assistir ao nosso mais novo curso sobre novo Skilljar sobre Habilidades de Agente. Este post vai assumir 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.
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, percebemos 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. Elas podem ser tanto para bibliotecas internas quanto para bibliotecas comuns com as quais o Claude Code às vezes tem dificuldade. Essas habilidades geralmente incluem uma pasta com 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 interna: casos extremos, armadilhas, etc.
- internal-platform-cli — cada subcomando do seu wrapper de 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 combinadas 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 ter um engenheiro dedicando 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 sobre o 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 UI 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
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. Processos de Negócio 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 se manter consistente e refletir sobre execuções anteriores do fluxo de trabalho.
Exemplos:
- standup-post — agrega seu rastreador de tickets, atividade do GitHub e Slack anterior → standup formatado, apenas deltas
- create-<sistema-de-ticket>-ticket — impõe esquema (valores de enum válidos, campos obrigatórios) mais fluxo de trabalho pós-criação (notificar revisor, link no Slack)
- weekly-recap — PRs mesclados + tickets fechados + deploys → post de resumo formatado
5. Scaffolding de Código e Modelos
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 puramente cobertos por código.
Exemplos:
- new-<framework>-workflow — cria um novo serviço/workflow/handler com suas anotações
- new-migration — seu modelo de arquivo de migração mais pegadinhas comuns
- create-app — novo aplicativo interno com sua autenticação, registro e configuração de deploy pré-conectados
6. Qualidade e Revisão de Código
Habilidades que impõem qualidade de código dentro da 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 — gera um subagente com olhos novos para criticar, implementa correções, itera até que as descobertas se degradem a detalhes insignificantes
- 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 da 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 merge → ativa auto-merge
- deploy-<serviço> — build → teste de fumaça → rollout gradual de tráfego com comparação de taxa de erro → auto-rollback em caso de regressão
- cherry-pick-prod — worktree isolado → cherry-pick → resolução de conflitos → PR com modelo
8. Runbooks
Habilidades que pegam um sintoma (como um thread do Slack, alerta ou assinatura de erro), percorrem uma investigação com 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 de sempre → formata uma descoberta
- log-correlator — dado um ID de solicitaçã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 trabalho de aprovação de dependências da organização
- cost-investigation — "por que nossa conta de armazenamento/egresso disparou" com os buckets e padrões de consulta específicos
Dicas para Criar Habilidades
Depois de decidir qual habilidade criar, como escrevê-la? 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 Diga o Óbvio
O Claude Code sabe muito sobre sua base de código, e Claude sabe muito sobre codificação, incluindo muitas opiniões padrão. Se você está publicando uma habilidade que é principalmente sobre conhecimento, tente se concentrar em informações que tirem Claude de sua maneira normal de pensar.
A habilidade de design de 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á nos 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ções detalhadas e exemplos de uso em references/api.md.
Outro exemplo: se sua saída final é um arquivo markdown, você pode incluir um arquivo de modelo 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ê vai querer ter 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
Algumas habilidades podem precisar ser configuradas com contexto do usuário. Por exemplo, se você está criando uma habilidade que posta seu standup no Slack, você pode querer que Claude pergunte em qual canal do Slack postar.
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 configuração não estiver definida, o agente pode então perguntar ao usuário pelas informações.
Se você quiser que o agente apresente perguntas de múltipla escolha estruturadas, você pode instruir Claude a usar a ferramenta AskUserQuestion.
O Campo de 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. Esta listagem é o que Claude examina para decidir "existe uma habilidade para esta solicitação?" O que significa que o campo de 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 qualquer coisa, desde um arquivo de log de texto simples somente para anexação ou arquivos JSON, até algo mais complicado como um banco de dados SQLite.
Por exemplo, uma habilidade de 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 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 este:
Claude pode então gerar scripts em tempo real 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 pelo tempo 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:
- /careful — bloqueia rm -rf, DROP TABLE, force-push, kubectl delete via correspondência PreToolUse no Bash. Você só quer isso quando sabe que está tocando em produção — tê-lo sempre ativo te enlouqueceria
- /freeze — bloqueia qualquer Edição/Escrita 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.
Existem 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 fazer upload 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 toda habilidade que é verificada também adiciona um pouco ao contexto do modelo. Conforme 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 fazer upload dela para uma pasta sandbox no GitHub e apontar as pessoas para ela no Slack ou em outros fóruns.
Depois que uma habilidade ganha tração (o que cabe ao proprietário da habilidade decidir), eles podem enviar um PR para movê-la para o mercado.
Um aviso de alerta: pode ser muito fácil criar habilidades ruins ou redundantes, então 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 faz upload de 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 em 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á se saindo, 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ão 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 nós estamos descobrindo como usá-las da melhor forma.
Pense nisso mais como uma coleção de dicas úteis que vimos funcionar do que como 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.
