Habilidades de Código Claude: Arquivos SKILL.md que o Modelo Invoca

Última atualização: June 28, 2026

Um Claude Code Skill é uma pasta com um arquivo SKILL.md que o agente puxa para o contexto apenas quando uma tarefa corresponde a ele. Criei meu primeiro skill para parar de colar o mesmo checklist de migração de banco de dados de 200 palavras em todas as sessões. Esse único arquivo agora me economiza aproximadamente uma hora por semana.

Aqui está a versão curta, seguida pela anatomia prática: o que é um skill, como escrever o frontmatter e o corpo do SKILL.md, como o modelo decide invocar um skill e quando um skill é excessivo em comparação com um prompt simples. Se você já usa Claude Code, pode enviar seu primeiro skill em menos de cinco minutos.

Resposta rápida: o que é um Claude Code Skill?

Um skill é uma capacidade reutilizável invocada pelo modelo e armazenada como SKILL.md (mais scripts de suporte opcionais). Diferentemente de um prompt de sistema que está sempre carregado, um skill é carregado sob demanda quando o modelo decide que ele é relevante para sua solicitação. Você escreve um nome, uma descrição de quando usá-lo e as instruções do corpo. A descrição é o campo mais importante, porque é o que o modelo lê para decidir se deve disparar o skill. Os skills vivem localmente em .claude/skills/ ou são enviados de um registro, permitindo que uma equipe compartilhe uma maneira canônica de fazer migrações, revisões de código ou lançamentos.

Se você deseja um contexto mais amplo sobre o CLI em si, veja meu guia definitivo do Claude Code para 2026. Para saber como os skills diferem dos sub-agentes sempre ativos, leia como automatizei meu fluxo de trabalho com sub-agentes Claude Code.

O que é realmente um skill e do que ele é feito?

Um skill é um diretório. O mínimo que ele precisa é um arquivo SKILL.md. Opionalmente, ele pode empacotar scripts, templates ou documentos de referência que viajam com o skill. A documentação de agent-skills da Anthropic descreve um skill como um conjunto empacotado de instruções e recursos que o modelo pode carregar quando relevante (docs.anthropic.com/en/docs/agents-and-tools/agent-skills).

Eu penso em um skill como uma sub-rotina nomeada e versionada para o modelo. Três coisas fazem ele ser diferente de um prompt longo:

1. Ele é opcional. O modelo carrega apenas quando uma tarefa parece corresponder à descrição.
2. Ele é escopado. Você pode anexar arquivos e scripts que só fazem sentido para aquela capacidade.
3. Ele é compartilhável. A pasta é portátil entre projetos e colegas de equipe.

O CLI em si é open source e a convenção de skills é documentada junto com ele no GitHub (github.com/anthropics/claude-code), que é onde verifico quando o comportamento muda entre os lançamentos.

Como você estrutura um arquivo SKILL.md?

O arquivo tem duas partes: frontmatter YAML e um corpo Markdown. O frontmatter diz ao modelo quando executar; o corpo diz o que fazer. Aqui está a anatomia que eu uso.

---
name: safe-migration
description: Use when the user asks to create, modify, or roll back a database migration. Covers schema changes, down migrations, and verifying against the staging dump.
---

O corpo é Markdown simples. Eu mantenho três seções: um objetivo de uma linha, um procedimento numerado e um portão explícito de "parar e confirmar". O name deve corresponder ao nome da pasta. A description deve ser escrita para o modelo, não para um humano, então ela deve parecer uma condição de gatilho.

Eu testei isso diretamente. Com uma descrição vaga como "ajuda com bancos de dados", o skill disparava em perguntas SQL não relacionadas. Depois que eu reescrevi para "Use when the user asks to create, modify, or roll back a database migration," a precisão de invocação passou de aproximadamente 60 por cento para confiável. A descrição está fazendo o roteamento, então gaste seu tempo de edição lá.

Quando você deve transformar algo em um skill?

Esta é a pergunta que mais recebo. Minha regra: se eu colei o mesmo bloco de instruções três vezes em duas semanas, e ele é maior do que um parágrafo, ele vira um skill. Abaixo está a matriz de decisão que eu realmente uso.

O segundo eixo é o custo. Cada skill carregado adiciona tokens ao contexto, então um bloco de instruções gordo e sempre relevante é melhor como uma memória em nível de projeto ou um comando personalizado do que como um skill. Skills brilham para expertise condicionalmente relevante.

Um caso concreto onde eu escrevi um skill: nosso processo de lançamento exige a atualização de um changelog, o aumento de três arquivos de versão, tagging e postagem de um resumo no Slack. Eu escrevi isso uma vez como um skill, e agora digo "cut a release" e o modelo executa todo o checklist em ordem. Um caso concreto onde eu não fiz: um refatoramento único de um arquivo de configuração. Isso permaneceu um prompt.

Como funciona o padrão de skill invocado pelo modelo?

O padrão que faz os skills parecerem mágicos é que você não os chama. Você descreve o trabalho, e o modelo lê as descrições dos skills disponíveis e puxa o correspondente. Isso é documentado na documentação oficial do Claude Code (docs.anthropic.com/en/docs/claude-code).

O fluxo se parece com isto:

1. Você digita uma solicitação em linguagem natural.
2. O modelo vê o name e a description de cada skill instalado.
3. Ele pontua a relevância em relação à sua solicitação.
4. O corpo do skill vencedor (e arquivos empacotados) entra no contexto.
5. O modelo executa as instruções.

A consequência prática: você deve escrever a description como se estivesse escrevendo uma entrada de mecanismo de busca para o modelo. Comece com o verbo e o escopo do gatilho. Compare estas duas descrições:

• Fraco: "Um skill para lidar com coisas git."
• Forte: "Use when the user asks to squash, rebase, or split commits on the current branch. Produces an interactive plan before running any rewrite."

O forte nomeia os verbos gatilho e a proteção (guardrail). É isso que torna a invocação confiável. Se você está conectando skills com ferramentas, o guia de integração Claude Code MCP cobre como servidores de ferramentas externos se encaixam ao lado dos bundles de skills. Para o protocolo subjacente que os conecta, veja MCP e o contexto do modelo.

Como você dispara e depura um skill?

Disparar é em grande parte automático, mas eu tenho três técnicas deliberadas para controle e depuração.

• Ser explícito. Dizer "use the safe-migration skill" força o uso. Útil quando a descrição é ambígua.
• Listar skills instalados. Peça ao modelo para listar os skills disponíveis e suas descrições. É assim que confirmo se um novo skill está registrado.
• Inspecionar o rastreamento (trace). Quando um skill dispara incorretamente, leio qual descrição correspondeu e aperto a redação do gatilho.

Quando um skill não dispara, a causa é quase sempre a descrição, não o local do arquivo. Eu reescrevo a primeira frase para começar com "Use when..." e adiciono os verbos específicos. Isso resolve nove em cada dez vezes.

Aqui está o checklist de depuração que eu sigo, em ordem:

Skill versus sub-agente versus comando slash

Estes três se sobrepõem, e as pessoas os confundem constantemente. Eu mantenho eles separados com uma divisão simples.

• Skill: instruções invocadas pelo modelo mais arquivos opcionais. Melhor para expertise condicional.
• Sub-agente: uma instância separada do Claude Code fazendo trabalho isolado. Melhor para tarefas paralelas e de longa duração. Meu texto sobre automação de sub-agentes aprofunda nisso.
• Comando slash: um atalho que você digita deliberadamente. Melhor para coisas que você sempre quer sob demanda.

Skills são o único dos três que o modelo escolhe por você. Esse é o seu superpoder e o seu risco: um skill mal descrito desperdiça contexto silenciosamente.

Como compartilhar skills e usar um registro?

Um skill é apenas uma pasta, então o compartilhamento é trivial em princípio. Eu coloco a pasta sob .claude/skills/ no repo e commito. Os colegas de equipe recebem ao clonar. Para compartilhamento entre equipes, a comunidade mantém registros e as ferramentas oficiais apontam para locais comuns.

Minha configuração prática:

1. Manter skills específicos do projeto no repo, versionados.
2. Manter skills pessoais em um repo dotfiles symlinked para .claude/skills/.
3. Fixar versões de skills ao compartilhar externamente, já que uma mudança na descrição pode alterar o comportamento silenciosamente.

O aviso honesto sobre compartilhamento: um skill codifica suposições sobre sua stack. Um skill de migração escrito para Drizzle produzirá confiantemente saída errada em um projeto Prisma se a descrição não proteger o escopo. Sempre declare o framework e as proteções na descrição, e adicione um passo de "parar e confirmar" antes de ações destrutivas. Aprendi isso da maneira mais difícil quando um skill compartilhado executou uma reescrita destrutiva no branch errado, então trate todo skill compartilhado como não confiável até que sua descrição prove o contrário.

Créditos de Imagem

• Black screen with code text overlay on a developer workstation — photo by Pixabay on Pexels
• Close-up of programming code on a monitor during development — photo by Christina Morillo on Pexels
• Laptop showing a code editor during software development — photo by luis gomes on Pexels