Claude Code Skills: como criar uma habilidade própria

Uma skill do Claude Code é uma pasta com um arquivo SKILL.md que descreve uma habilidade e quando usá-la. Você escreve uma vez, e o agente passa a aplicar aquele procedimento sozinho toda vez que a situação aparece, sem você repetir a instrução. Ela se paga a partir da terceira repetição da mesma tarefa.

Funciona como um manual de procedimento que o próprio agente consulta antes de agir. Em vez de colar o mesmo prompt gigante toda conversa, você cria a skill uma vez e reusa em qualquer projeto. Aqui no blog eu já falei de subagentes e de MCP, e as skills fecham o conjunto. A base de tudo, do CLAUDE.md ao limite do plano, está no guia completo de Claude Code em português.

O que são as skills do Claude Code e por que usar?

Uma skill é uma pasta com um arquivo de instruções, o SKILL.md, e, quando precisa, arquivos de apoio: modelos, listas de verificação, exemplos de saída boa e de saída ruim. O Claude Code carrega essa pasta sozinho quando reconhece que a tarefa pedida se encaixa naquele contexto, e é isso que a diferencia do CLAUDE.md, que entra em toda sessão. Skill só gasta contexto quando é chamada.

Eu comecei sem organização nenhuma, só prompt solto no chat. Funcionava, até o dia em que precisei repetir a mesma explicação pela quinta vez porque abri uma conversa nova. Sem estrutura vira bagunça rápido, e isso vale tanto para automação quanto para prompt. Skill não é sobre ensinar a IA a pensar, é sobre fixar o jeito certo de executar. A inteligência já existe no modelo, o que falta é padrão.

Qual é a diferença entre skill, subagente e MCP?

Essa confusão é comum, e eu mesmo demorei para separar os três na cabeça. Skill é receita: um conjunto fixo de instruções sobre como fazer algo, tipo revisar um contrato ou montar uma proposta no formato que você usa sempre. Subagente é outro cérebro: roda uma tarefa com contexto isolado, muitas vezes em paralelo, para não poluir a conversa principal. MCP é conexão: dá acesso a uma ferramenta externa, um banco, uma API, um sistema de arquivos.

Os três não competem, eles se completam. Uma skill pode orientar quando usar um subagente ou quando chamar uma ferramenta MCP dentro do mesmo fluxo. A documentação oficial de skills traz a estrutura recomendada de arquivo, e a tabela abaixo é o resumo que eu uso para escolher a peça certa para cada problema.

Quando vale a pena criar uma skill própria?

Vale quando a tarefa se repete mais de três vezes com o mesmo formato esperado. Vale quando existe processo com passos fixos, tipo checklist de revisão de código antes de subir para produção ou padrão de mensagem de commit. E vale muito quando o time inteiro precisa produzir do mesmo jeito, não só você, porque padronizar é o que separa um time produtivo de um time reinventando a roda toda semana.

Não vale para tarefa única, feita uma vez e esquecida. Aí o prompt solto resolve. O sinal mais claro que eu conheço é este: se você já se pegou copiando o mesmo bloco de instrução de uma conversa para outra, aquele bloco é uma skill esperando para nascer. No meu caso, as primeiras foram revisão cruzada, plano antes de implementar e checklist de segurança, exatamente as três coisas que eu mais repetia.

Como pensar a estrutura antes de pedir para a IA?

Organiza a ideia na cabeça primeiro, porque isso evita retrabalho. Define um título curto e uma descrição clara de quando a skill deve entrar em ação, porque é essa descrição que o agente lê para decidir se aciona. Depois lista o passo a passo em linguagem simples, na ordem que você faria na mão. Inclui um exemplo de resultado bom e, se possível, um de resultado ruim, para a IA entender o que evitar.

Por fim, pensa nas exceções: o que muda quando o caso foge do padrão. Essa organização prévia é a sacada que separa a skill que funciona sempre da que funciona só às vezes. Uma descrição vaga de quando usar é o erro mais comum que eu vejo, porque faz o agente aplicar a skill no momento errado ou não aplicar quando devia. Gasta mais tempo nessa frase do que no resto.

Como pedir para o Claude Code criar a primeira skill?

Não tem mistério nem comando de terminal, é conversa, do jeito que eu ensino para quem está começando. Explica a tarefa para o agente com o máximo de detalhe: o que ele deve fazer, quando, e como o resultado final deve parecer. Pede para ele mesmo montar o rascunho seguindo a estrutura que a Anthropic recomenda. Depois lê o rascunho com calma e aponta o que precisa ajustar, como revisaria o trabalho de um estagiário novo.

Não aceita a primeira versão de cara. Pede exemplo de uso, pede que ele simule um caso real antes de fechar. O passo a passo de instalação e do CLAUDE.md, que vem antes de qualquer skill, está em Claude Code na prática. Se você ainda não tem o arquivo de memória do projeto, faz ele primeiro, porque skill sem CLAUDE.md é receita sem cozinha.

Como validar se a skill está funcionando?

Testa com casos reais, não só com o exemplo perfeito que você imaginou. Abre uma conversa nova e pede para a IA executar a mesma tarefa em cenários diferentes: um caso simples, um com informação faltando, um fora do padrão comum. Compara os resultados. Se o comportamento mudar demais de um teste para outro, a instrução ainda está vaga em algum ponto e precisa de ajuste. Skill boa entrega resultado parecido mesmo quando muda quem pede.

Quais são os erros mais comuns?

Criar skill genérica demais, tentando resolver problema grande numa instrução só. Duplicar a função de um subagente dentro de uma skill, misturando conceito e complicando à toa. Deixar a skill parada por meses sem revisão, enquanto o processo real do negócio já mudou. E não escrever com clareza quando ela deve ser usada, o que faz o agente aplicar no momento errado. Todos os quatro eu já cometi, e o último é o que mais custa.

Sem organização, cada conversa nova recomeça do zero. O prompt gigante volta a ser copiado, a inconsistência entre resultados aumenta e o tempo que a IA deveria economizar volta para a sua agenda. É a mesma lógica de automação sem estrutura: funciona bonito na demonstração e quebra quando escala. Não é sobre a IA ser incapaz, é falta de processo em cima de uma ferramenta poderosa.

Quais são as dúvidas mais frequentes?

Skill substitui subagente? Não. A skill define como fazer, o subagente executa em contexto isolado, e uma skill pode até orientar quando acionar um subagente. Precisa saber programar? Não, a criação é em linguagem natural e o próprio Claude Code monta o rascunho. Quantas skills por projeto? Não existe limite fixo, mas poucas e bem definidas valem mais do que muitas genéricas se sobrepondo, porque cada uma nova precisa resolver um problema claro.

Funciona em qualquer projeto? Funciona em qualquer contexto com tarefa repetitiva e formato esperado definido, seja código, texto comercial, revisão de documento ou atendimento. O que muda é o conteúdo da instrução, a lógica de criação é a mesma. Eu tenho skill de SEO, de design, de contrato e de contabilidade convivendo com as de código, e todas seguem a mesma estrutura. Onde cada pasta fica, o que muda no Codex e como escrever a descrição que dispara certo estão no guia de skills do Claude Code.

Por onde começar?

Se você já usa o Claude Code no dia a dia, começa com uma skill só, para uma tarefa que você repete toda semana. Testa, ajusta, e só depois pensa na segunda. Se você quer pular a parte de descobrir o que vale virar skill, eu mantenho uma loja de skills prontas com as que eu uso todo dia: revisão cruzada, plano antes de implementar, SEO, design, segurança e pesquisa. Serve como ponto de partida e como exemplo de como uma skill boa é escrita.