Skills do Claude Code: como escrever uma SKILL.md útil

Skills do Claude Code: como escrever uma SKILL.md útil

Para criar uma skill útil no Claude Code, você escreve uma pasta com um arquivo SKILL.md que tem duas partes: um cabeçalho com nome e descrição, e um corpo com as instruções. A descrição é a parte mais importante, porque é ela que faz o Claude decidir quando usar a skill. O restante deve ser curto, verificável e apoiado por arquivos separados quando o assunto crescer.

Principais pontos

• A descrição diz o que a skill faz e quando usá-la. É ela que o Claude lê para decidir se aciona a skill.
• O corpo do SKILL.md deve ser um procedimento: passos, critérios de pronto e o que fazer em caso de dúvida.
• Material longo (modelos, exemplos, referências, scripts) fica em arquivos de apoio, lidos apenas quando necessário.
• Skills de projeto ficam no repositório e podem ser revisadas como código, com pull request e dono definido.
• Toda skill precisa de um teste simples: pedidos que devem acioná-la e pedidos que não devem.

O que é uma skill e como o Claude Code a carrega?

Segundo a documentação do Claude Code sobre skills, uma skill é uma pasta que empacota uma capacidade: um arquivo SKILL.md e, se for preciso, outros arquivos e scripts. O Claude decide por conta própria quando usar cada skill, a partir do pedido do usuário e da descrição que você escreveu. Isso é diferente de um comando que a pessoa precisa digitar.

O ponto técnico que mais importa para quem escreve é o carregamento em etapas. No começo da sessão, o Claude enxerga só o nome e a descrição de cada skill disponível. Quando uma skill parece relevante, ele lê o corpo do SKILL.md. Os arquivos de apoio só entram quando as instruções mandam consultá-los. Essa ideia combina com o que a Anthropic descreve sobre engenharia de contexto para agentes: contexto é um recurso limitado, e o ideal é trazer a informação certa na hora certa, não tudo de uma vez. Se isso for novo para você, vale entender antes o que é a janela de contexto.

Há dois lugares comuns para guardar skills. As pessoais ficam na pasta do usuário e valem para todos os projetos dele. As de projeto ficam numa pasta dentro do repositório, e quem clonar o projeto recebe as mesmas skills. Para uma equipe, a segunda opção costuma ser a certa, porque a skill passa a ter histórico, autor e revisão. Para uma visão mais ampla do assunto, veja também Skills no Claude Code: o que são e como criar as da sua equipe.

Como escrever a descrição para a skill ser acionada na hora certa?

O cabeçalho do SKILL.md traz o campo name e o campo description. O nome identifica a skill, em letras minúsculas e hifens. A descrição é o gatilho. Se ela for vaga, a skill nunca é usada ou é usada fora de hora. Se for ampla demais, ela dispara em conversas que não têm nada a ver.

Uma boa descrição responde a duas perguntas na mesma frase: o que a skill faz e em que situações ela deve entrar. Use as palavras que a sua equipe realmente usa ao pedir a tarefa, não o nome interno do processo.

Compare dois exemplos, ambos ilustrativos:

• Fraca: Ajuda com relatórios.
• Melhor: Monta o relatório semanal de manutenção a partir da planilha exportada do sistema. Use quando o pedido citar relatório semanal, fechamento da semana ou resumo de ordens de serviço.

A segunda versão tem verbo concreto, fonte de dados e expressões que aparecem nos pedidos. Ela também ajuda a evitar disparo indevido, porque delimita o território.

Alguns cuidados práticos para a descrição:

• Uma skill, uma tarefa. Se a descrição precisa de várias frases com "ou", provavelmente são duas skills.
• Cite o tipo de arquivo ou sistema envolvido, quando existir.
• Diga quando não usar, se houver uma skill vizinha que poderia ser confundida com esta.
• Evite promessas genéricas como "melhora qualquer texto". O Claude vai tentar acioná-la para tudo.

O que colocar nas instruções do SKILL.md?

O corpo é o procedimento. Pense nele como o roteiro que você daria a um colega competente que nunca fez aquela tarefa na sua empresa. Ele sabe escrever e raciocinar, mas não sabe as suas regras, os seus formatos e os seus limites.

Uma estrutura que funciona bem:

• Objetivo em uma ou duas frases: qual é o resultado esperado.
• Entradas: o que a pessoa precisa fornecer e o que fazer se faltar algo.
• Passos em ordem, cada um com uma ação verificável.
• Formato da saída: campos, ordem, tom, tamanho.
• Limites: o que a skill nunca faz, e quando parar e pedir confirmação humana.
• Critério de pronto: como saber que terminou direito.

Duas escolhas de redação fazem diferença. A primeira é preferir instruções no imperativo e específicas, como "liste as ordens abertas há mais de uma semana", em vez de "analise o andamento". A segunda é explicar o motivo das regras mais importantes. Quando o Claude entende por que uma regra existe, ele a aplica melhor nos casos de borda do que quando só recebe uma proibição seca.

Também vale ser honesto sobre o que a skill não resolve. Se um passo depende de uma decisão de negócio, escreva que o Claude deve apresentar as opções e esperar a escolha, em vez de decidir sozinho. Isso conversa com a recomendação da Anthropic em Building effective agents: comece simples, use fluxos previsíveis onde der e reserve a autonomia para onde o julgamento é necessário.

O cabeçalho também pode restringir as ferramentas que a skill usa. O campo allowed-tools, descrito na documentação, limita o que o Claude pode fazer enquanto a skill está ativa. Uma skill de revisão que só precisa ler arquivos não deveria ter permissão para editá-los ou executar comandos. Confira na documentação atual o formato exato e o comportamento, porque esse recurso evolui.

Quando usar arquivos de apoio e scripts?

Um SKILL.md que cresce demais vira um problema duplo: consome contexto toda vez que é lido e fica difícil de revisar. A saída é dividir. O corpo mantém o fluxo principal e aponta para outros arquivos na mesma pasta, que o Claude lê só quando o passo exige.

Bons candidatos a arquivo separado:

• Modelos de saída, como o texto padrão de um relatório ou de um e-mail.
• Exemplos de entrada e saída aprovados pela equipe.
• Regras longas de um domínio, como política de nomenclatura ou checklist de revisão de código.
• Glossário de termos internos.
• Scripts para tarefas determinísticas, como validar um formato, converter uma planilha ou calcular algo que não deve depender de interpretação.

O critério para usar script é simples: se o resultado precisa ser sempre igual para a mesma entrada, não peça ao modelo para fazer à mão. Deixe o código executar e o Claude interpretar o resultado. Esse mesmo raciocínio aparece no guia da Anthropic sobre como escrever ferramentas para agentes: saídas claras e previsíveis tornam o agente mais confiável.

No SKILL.md, referencie cada arquivo de apoio dizendo quando consultá-lo. Por exemplo: "para montar o resumo final, leia o modelo de relatório da pasta de apoio". Sem essa indicação, o arquivo existe, mas ninguém o usa.

Um alerta de segurança: se a skill lê documentos externos, e-mails ou páginas, esse conteúdo pode conter instruções maliciosas. Escreva na skill que o texto lido é dado, não ordem, e leia Prompt injection: como proteger um agente de IA da empresa. Se a skill também usa ferramentas conectadas por MCP, confira Configurar MCP no Claude Code para entender escopos e permissões.

Como revisar uma skill em equipe?

Skill é instrução que muda o comportamento de uma ferramenta que escreve e executa coisas. Merece o mesmo cuidado de um script de automação. Quando ela mora no repositório, o fluxo natural é o de código: alteração em branch, pull request, revisão e aprovação por alguém responsável.

Checklist de revisão que pode ser usado no pull request:

• A descrição diz o que a skill faz e quando usá-la, com as palavras da equipe?
• Existe sobreposição com outra skill? Se sim, as descrições deixam claro quem faz o quê?
• Os passos são verificáveis, ou há frases vagas como "faça uma boa análise"?
• As ferramentas permitidas são o mínimo necessário?
• A skill trata dados pessoais? Se trata, há instrução para não copiar esses dados para a saída sem necessidade (veja a LGPD e, se houver envio a provedores fora do país, transferência internacional de dados com IA)?
• Há instrução de parada e confirmação humana antes de ações irreversíveis?
• Os arquivos de apoio estão atualizados e referenciados?
• Existe um dono nomeado e uma data combinada para revisar de novo?

O teste de aceitação deve ser parte da revisão. Escreva uma lista curta de pedidos reais: alguns que devem acionar a skill, alguns parecidos que não devem e alguns incompletos. Rode cada um e registre o resultado. É uma versão enxuta do que a Anthropic descreve em Demystifying evals for AI agents: definir tarefas, critérios de sucesso e olhar o que o agente realmente fez, não só a resposta final. Para a parte de código gerado, o texto Testes automatizados gerados por IA complementa.

Passo a passo para escrever a primeira skill

O caminho abaixo evita o erro mais comum, que é começar escrevendo instruções antes de saber qual tarefa a skill resolve.

• Escolha uma tarefa que a equipe repete e que tem formato de saída conhecido.
• Peça a duas pessoas que descrevam como fazem hoje. Anote as diferenças, porque elas mostram onde falta regra.
• Escreva a descrição primeiro, com o que faz e quando usar. Mostre a um colega e pergunte em que situações ele esperaria que ela fosse acionada.
• Escreva o corpo com objetivo, entradas, passos, formato de saída e limites.
• Mova modelos e exemplos longos para arquivos de apoio e referencie cada um.
• Defina as ferramentas mínimas permitidas.
• Rode a lista de pedidos de teste, ajuste a descrição se acionar demais ou de menos e repita.
• Faça o pull request, nomeie um dono e combine quando reler a skill.

Cenário ilustrativo: uma equipe de atendimento técnico quer que o Claude Code prepare o resumo de um chamado para passar ao próximo turno. A primeira versão da skill dizia apenas "resume chamados" e disparava até quando alguém pedia para resumir um texto qualquer. A equipe reescreveu a descrição citando passagem de turno e histórico do chamado, moveu o modelo de resumo para um arquivo de apoio e acrescentou uma regra: se faltar o número do chamado, pedir antes de resumir. Depois disso, passou a testar cinco pedidos de cada tipo antes de aprovar mudanças. O exemplo é inventado, mas mostra o ciclo: descrição precisa, corpo curto, apoio separado, teste simples.

O método que usamos em projetos de IA se aplica bem aqui, em escala pequena. Mapear: entender como a tarefa é feita hoje e qual é o ponto de partida. Limitar: definir dados acessíveis, ferramentas permitidas e ações que exigem aprovação. Pilotar: rodar uma skill em um fluxo real, com registro do que aconteceu e um critério de sucesso combinado. Transferir: deixar dono, documentação e rotina de revisão, e então decidir se amplia, ajusta ou para.

Perguntas frequentes

Quantas skills uma equipe deve ter? Comece com poucas, ligadas a tarefas repetidas e bem entendidas. Cada skill nova adiciona uma descrição que o Claude precisa avaliar, e descrições parecidas competem entre si. Só crie outra quando houver uma tarefa claramente distinta.

A skill é a mesma coisa que o arquivo CLAUDE.md? Não. O CLAUDE.md traz orientações gerais do projeto, que valem para a sessão inteira, como convenções e comandos comuns. A skill é um procedimento para uma tarefa específica e só é carregada quando o Claude entende que ela é relevante.

Minha skill não é acionada, o que verifico primeiro? Comece pela descrição: ela cita a tarefa e as palavras que as pessoas usam no pedido? Depois confira se o arquivo está na pasta certa, se o cabeçalho está bem formado e se não há outra skill com descrição parecida competindo. Teste com pedidos reais e ajuste uma coisa por vez.

Posso colocar dados de clientes dentro de uma skill? Não é recomendável. Uma skill fica em repositório e circula entre pessoas, então deve conter procedimento e modelos, não dados pessoais ou segredos. Se a tarefa precisa de dados, indique de onde lê-los com a permissão adequada e instrua a skill a usar só o necessário, respeitando a LGPD.

Fontes

• Anthropic: documentação de skills no Claude Code
• Anthropic: Effective context engineering for AI agents
• Anthropic: Building effective agents
• Anthropic: Demystifying evals for AI agents