Skills no Claude Code: o que são e como criar as da sua equipe

Skills no Claude Code: o que são e como criar as da sua equipe

Uma skill no Claude Code é uma pasta com um arquivo SKILL.md, que traz um nome, uma descrição e instruções em texto, mais arquivos de apoio opcionais. Para criar a da sua equipe, crie a pasta dentro de .claude/skills no repositório, escreva uma descrição clara de quando ela deve ser usada e versione tudo no Git. O Claude passa a carregar a skill por conta própria quando o pedido combina com a descrição.

Principais pontos

• Skill é uma pasta com SKILL.md: um cabeçalho com nome e descrição, seguido das instruções em Markdown.
• A descrição é a parte mais importante, porque é ela que ajuda o Claude a decidir quando carregar a skill.
• Skills do projeto ficam em .claude/skills e viajam com o repositório, o que as torna a forma natural de compartilhar rotinas com a equipe.
• Comece por rotinas repetitivas, com critério claro de "feito", e trate a skill como código: revisão, versionamento e limites de permissão.
• Confira sempre a documentação oficial, porque o formato e os recursos do Claude Code mudam com o tempo.

O que é uma skill no Claude Code?

Segundo a documentação oficial do Claude Code, uma skill é um pacote de conhecimento e procedimento que amplia o que o Claude sabe fazer em uma tarefa específica. Em vez de repetir toda semana o mesmo parágrafo de instruções no chat, você escreve uma vez, em um arquivo, e o Claude o usa quando for relevante.

O ponto técnico que importa para quem decide é a carga sob demanda. De início, o Claude enxerga apenas o nome e a descrição de cada skill. O corpo das instruções, os modelos e os scripts só entram no contexto quando a skill é acionada. Isso permite ter muitas skills instaladas sem entupir cada conversa com texto que não vem ao caso. É a mesma lógica de economia de contexto que a Anthropic discute em seu material sobre engenharia de contexto para agentes.

Vale distinguir a skill de outros recursos que parecem parecidos:

• CLAUDE.md: instruções que ficam sempre carregadas. Serve para regras gerais do projeto, como convenções de código e comandos de teste.
• Comandos de barra (slash commands): atalhos que a pessoa dispara de forma explícita. A skill, ao contrário, é escolhida pelo próprio Claude a partir da descrição.
• Subagentes: assistentes com contexto e permissões próprios, úteis para isolar uma tarefa.
• MCP (Model Context Protocol): conexão do Claude com sistemas externos e ferramentas. Para entender o protocolo, veja a introdução ao MCP. A skill ensina o procedimento; o MCP dá o acesso.

Neste texto, o que vem da documentação oficial está descrito como tal. As sugestões de rotinas e de organização são nossa experiência de implementação e hipóteses de trabalho, não regras do produto.

Onde ficam as skills e como o Claude as encontra?

Há, em geral, três lugares onde uma skill pode morar:

• Pessoal: na pasta .claude/skills dentro do seu diretório de usuário. Vale só para você, em qualquer projeto.
• Projeto: na pasta .claude/skills dentro do repositório. Quem clona o projeto recebe as skills junto.
• Plugins: pacotes que podem reunir skills e outros recursos para distribuição mais ampla.

Para uma equipe, a opção de projeto costuma ser a melhor ponto de partida. A skill entra no mesmo fluxo de pull request que o resto do código: alguém propõe, outra pessoa revisa, o histórico fica registrado. Isso resolve de uma vez o problema clássico do conhecimento que existe só na cabeça de uma pessoa ou em um documento esquecido numa wiki.

Cada skill tem a sua própria subpasta. O nome da pasta deve descrever a rotina, em letras minúsculas e com hífens, por exemplo revisao-de-pr ou notas-de-release. Dentro dela, o arquivo SKILL.md é obrigatório e o restante é opcional: modelos, exemplos, listas de verificação e scripts.

Como criar uma skill passo a passo

Este é o roteiro que sugerimos para a primeira skill de uma equipe:

• Passo 1, escolha uma rotina: uma tarefa que se repete, que tem entrada e saída claras e que hoje depende de alguém lembrar os passos. Evite começar por algo que mexe em dados sensíveis ou em produção.
• Passo 2, escreva o procedimento como se fosse para uma pessoa nova: o que olhar primeiro, quais critérios aplicar, o que fazer quando faltar informação e o que nunca fazer.
• Passo 3, crie a pasta: dentro de .claude/skills, uma subpasta com o nome da rotina.
• Passo 4, crie o SKILL.md: no topo, o cabeçalho em YAML com os campos name e description. Abaixo, as instruções em Markdown.
• Passo 5, separe o que é longo: modelos de documento, exemplos e referências vão para arquivos ao lado, e o SKILL.md apenas diz quando consultá-los.
• Passo 6, restrinja as ferramentas: se a documentação oficial da sua versão oferecer o campo allowed-tools, use-o para limitar o que a skill pode fazer. Uma skill de revisão, por exemplo, só precisa ler arquivos.
• Passo 7, teste com pedidos reais: peça a tarefa de formas diferentes e observe se a skill é acionada e se o resultado segue o procedimento.
• Passo 8, revise e publique: abra um pull request, peça revisão de outra pessoa e só então faça merge.

A documentação oficial define limites de tamanho e de formato para nome e descrição. Consulte a página de skills do Claude Code antes de padronizar o formato para a equipe, porque esses detalhes podem mudar.

Como escrever uma boa descrição e boas instruções?

A descrição decide se a skill será usada. O Claude compara o pedido da pessoa com a descrição de cada skill disponível. Uma descrição vaga faz a skill nunca ser acionada, ou ser acionada na hora errada.

Compare dois exemplos. Uma descrição fraca seria: "Ajuda com PRs". Uma descrição melhor seria: "Revisa um pull request contra o checklist de revisão da equipe. Use quando a pessoa pedir revisão de código, revisão de PR ou análise de um diff." A segunda diz o que a skill faz e em que situações usá-la, com as palavras que a equipe realmente usa no dia a dia.

Para as instruções do corpo do arquivo, um checklist enxuto ajuda:

• Comece pelo objetivo e pelo resultado esperado, em uma ou duas frases.
• Liste os passos na ordem em que devem acontecer.
• Diga o formato da saída: tópicos, tabela de achados, texto para colar em um ticket.
• Defina o que fazer na dúvida, por exemplo perguntar antes de assumir.
• Escreva os limites de forma explícita: o que a skill não deve alterar, apagar ou enviar.
• Use exemplos curtos de entrada e saída boa, em vez de longas explicações abstratas.
• Mantenha o SKILL.md curto e mova o material de referência para arquivos separados.

O princípio é o mesmo do desenho de ferramentas para agentes: poucas instruções, claras e inequívocas, funcionam melhor que um manual extenso. A Anthropic discute isso em como escrever ferramentas eficazes para agentes.

Que rotinas da equipe viram boas skills?

Boas candidatas têm três traços: acontecem com frequência, seguem um procedimento reconhecível e têm um resultado que alguém consegue conferir. Algumas ideias, todas como sugestão de organização:

• Revisão de pull request: aplica o checklist da equipe, aponta riscos e sugere testes que faltam.
• Notas de versão: transforma a lista de commits ou de tarefas concluídas em um texto legível para quem não é técnico.
• Triagem de bugs: lê um relato, pede os dados que faltam e classifica por área e urgência segundo critérios definidos.
• Roteiro de incidente: guia o diagnóstico inicial em modo somente leitura, seguindo o runbook da equipe.
• Onboarding de repositório: explica como subir o ambiente, rodar testes e onde ficam as convenções.
• Documentação de integração: gera o rascunho de uma página padronizada a cada novo conector ou endpoint.

Para decidir se algo deve ser skill ou outro recurso, use este guia:

• Se a regra vale para todo trabalho no projeto, coloque no CLAUDE.md.
• Se a pessoa quer disparar uma ação de forma explícita e previsível, use um comando de barra.
• Se a tarefa tem procedimento próprio e deve ser acionada quando o contexto pedir, use uma skill.
• Se a tarefa precisa de acesso a um sistema externo, combine a skill com uma conexão MCP.
• Se a tarefa exige contexto isolado ou permissões diferentes, considere um subagente.

Cenário ilustrativo: uma equipe pequena de software publica uma versão por semana e, toda sexta, alguém passa um tempo montando o texto de novidades para o time comercial. Ela cria a skill notas-de-release. A descrição diz que serve para preparar notas de versão a partir das mudanças da semana. As instruções pedem agrupar por área, usar linguagem sem jargão, destacar mudanças que afetam clientes e sinalizar o que está incerto em vez de adivinhar. Um modelo de texto fica em um arquivo ao lado. A pessoa responsável continua revisando e publicando; a skill só entrega o primeiro rascunho. Depois de algumas semanas, a equipe compara o rascunho com o texto final e ajusta as instruções onde houve mais correções.

Se a rotina envolve atendimento ao cliente, lembre que o Claude Code é uma ferramenta de trabalho de desenvolvimento e operação interna. Para fluxos de atendimento em canais como o WhatsApp, o desenho é outro, com transbordo humano e registro de decisões. Veja, por exemplo, o guia sobre como integrar IA no WhatsApp da empresa.

Como manter segurança e controle sobre as skills?

Uma skill é instrução, e às vezes código executável. Por isso merece o mesmo cuidado de qualquer outro item do repositório.

• Revisão obrigatória: toda skill nova ou alterada passa por pull request. Scripts dentro da skill são lidos com atenção, linha por linha.
• Menor permissão possível: limite as ferramentas e evite dar acesso de escrita ou de rede quando a tarefa não exige.
• Sem segredos: nunca coloque chaves, senhas ou tokens no SKILL.md ou nos arquivos de apoio.
• Sem dados pessoais: exemplos devem ser fictícios. Dados reais de clientes em um repositório criam um problema de LGPD que ninguém precisa ter. Para orientação oficial, consulte a ANPD.
• Atenção a conteúdo não confiável: se a skill lê páginas, e-mails ou tickets, esse texto pode conter instruções maliciosas. As recomendações do OWASP sobre prevenção de prompt injection são um bom ponto de partida.
• Aprovação humana para ações irreversíveis: envio de mensagens, alterações em produção e exclusões devem exigir confirmação. Um modelo para isso está na política de aprovação para agentes de IA.

O nosso método se aplica de forma direta. Primeiro mapeamos a rotina como ela é feita hoje e anotamos o ponto de partida. Depois limitamos dados, ferramentas e ações. Em seguida pilotamos uma única skill, com registro do que foi pedido e do que foi corrigido, e um critério de sucesso combinado antes do início. Por fim transferimos: a equipe passa a ser dona do arquivo, e a decisão é expandir, ajustar ou parar. Para definir o critério, o artigo sobre como medir um piloto de automação com IA traz métricas e pontos de decisão.

Perguntas frequentes

Qual a diferença entre skill e CLAUDE.md? O CLAUDE.md fica sempre carregado e guarda regras gerais do projeto. A skill é carregada sob demanda, quando a descrição combina com o pedido, e guarda um procedimento específico. Se a instrução só faz sentido para uma tarefa, ela provavelmente é uma skill.

Preciso saber programar para criar uma skill? Para o caso mais simples, não. Uma skill pode ser apenas um SKILL.md com texto em Markdown e um cabeçalho com nome e descrição. Programar só entra se você quiser incluir scripts de apoio, e nesse caso a revisão por alguém técnico é indispensável.

Como compartilho uma skill com toda a equipe? Coloque a pasta em .claude/skills dentro do repositório do projeto e faça o commit. Quem atualizar o repositório recebe a skill. Para distribuição entre vários projetos, a documentação oficial descreve o uso de plugins, vale conferir o que a sua versão suporta.

Como sei se a skill está funcionando bem? Teste com pedidos reais e variados, e observe se ela é acionada e se a saída segue o procedimento. Em um piloto, registre quantas vezes o resultado precisou de correção humana e por quê, e ajuste a descrição e as instruções com base nisso. Se a rotina não melhorar depois de alguns ciclos, é um sinal legítimo para parar ou redesenhar.

Fontes

• Anthropic: Claude Code, documentação de skills
• Anthropic: Effective context engineering for AI agents
• Anthropic: Writing effective tools for agents
• OWASP: prompt injection prevention