Documentação de Habilidades do Claude Code: A Referência Completa para Desenvolvedores

Eu não planejava me aprofundar nisso hoje. Eu só estava tentando entender por que a configuração do meu colega de Claude Code se comportava de forma tão diferente da minha — e a resposta acabou estando em uma pasta que eu mal havia notado.

O que a Documentação de Habilidades do Claude Code Aborda

A frase "documentação de habilidades do anthropic claude code" aparece em muitas pesquisas de desenvolvedores, e acho que há uma razão para isso: o sistema de habilidades está realmente espalhado por algumas superfícies diferentes, e pode levar algum tempo para juntar como elas se conectam.

Este artigo é baseado nas fontes oficiais da Anthropic. Mas ele tenta acrescentar algo que a documentação sozinha não consegue oferecer totalmente — uma camada mais lenta de entendimento, construída a partir da observação.

Onde encontrar a documentação oficial

O ponto de partida canônico é referência de habilidades do Claude Code da Anthropic, que cobre todo o ciclo de vida da habilidade, o formato SKILL.md e como o Claude descobre e carrega habilidades automaticamente.

Para entender como as habilidades se encaixam no panorama mais amplo de agentes — incluindo como elas se comparam a Projects, MCP e subagents — a Anthropic publicou um post útil no blog: Habilidades explicadas: Como habilidades se comparam a prompts, Projects, MCP e subagents. Esse me ajudou a compreender não apenas o o que, mas o quando.

O que este artigo acrescenta além da documentação oficial

A documentação oficial é precisa e bem estruturada. O que ela nem sempre captura é o padrão de pequenas surpresas — os momentos em que uma habilidade não dispara, ou dispara de forma muito ampla, ou quando você percebe que um arquivo SKILL.md e um arquivo CLAUDE.md estavam realizando funções ligeiramente diferentes que você havia confundido.

É isso que estou tentando mapear aqui.

Referência de Formato SKILL.md

Localização e nomeação de arquivos

Cada habilidade precisa de um arquivo SKILL.md com duas partes: frontmatter YAML (entre os marcadores ---) que informa ao Claude quando usar a habilidade, e conteúdo em markdown com instruções que o Claude segue quando a habilidade é acionada.

No Claude Code, as habilidades ficam em .claude/skills/<skill-name>/SKILL.md dentro de um projeto, ou em ~/.claude/skills/<skill-name>/SKILL.md para habilidades globais do usuário. O nome da pasta e o campo name no frontmatter se tornam o comando de barra — então .claude/skills/explain-code/SKILL.md com name: explain-code cria o comando /explain-code.

Habilidades definidas em .claude/skills/ dentro de diretórios adicionados via --add-dir são carregadas automaticamente e reconhecidas pela detecção de alterações em tempo real, então você pode editá-las durante uma sessão sem reiniciar. Esse comportamento me surpreendeu um pouco — eu esperava precisar de um reinício.

Tipos de instrução suportados

Habilidades fornecem ao Claude novas capacidades por meio de instruções e código. Na prática, o corpo em markdown pode conter quase tudo sobre o que Claude pode raciocinar: procedimentos passo a passo, regras de estilo, modelos de saída, terminologia de domínio, conteúdo de referência e exemplos inline. Prefira usar o modo imperativo nas instruções.

Um detalhe que vale a pena notar na documentação oficial do criador de habilidades: o campo de descrição é o principal mecanismo de acionamento — inclua tanto o que a habilidade faz QUANTO contextos específicos para quando usá-la. Todas as informações de "quando usar" vão aqui, não no corpo.

Sintaxe e estrutura do formato

O SKILL.md mínimo se parece com isto:

Plain

---
name: my-skill-name
description: A clear description of what this skill does and when to use it
---

# My Skill Name

[Instructions Claude follows when this skill is active]

Na inicialização, o agente pré-carrega o nome e a descrição de cada habilidade instalada no seu prompt do sistema. Esses metadados são o primeiro nível de divulgação progressiva: fornecem informações suficientes para que o Claude saiba quando cada habilidade deve ser usada sem carregar tudo no contexto.

Habilidades também podem incluir arquivos de suporte — documentação de referência, scripts, ativos — em subdiretórios. Ao mover instruções de preenchimento de formulários para um arquivo separado, o autor da habilidade consegue manter o núcleo da habilidade mais enxuto, confiando que Claude lerá esse arquivo apenas quando necessário.

Limites de caracteres e tamanho

Não há um limite rígido de caracteres imposto ao SKILL.md em si. A quantidade de contexto que pode ser incluída em uma habilidade é, efetivamente, ilimitada, porque a divulgação progressiva significa que Claude carrega arquivos adicionais apenas quando necessário. Mas, na prática, manter o SKILL.md focado nas instruções principais — com menos de 500 linhas — minimiza o excesso de contexto. Mova conteúdo detalhado para references/ e vincule a ele.

O que Habilidades de Código Claude Podem Instruir

Preferências de estilo e formatação

Habilidades são ideais para codificar padrões de saída: como estruturar um relatório, qual tom usar, quais cabeçalhos incluir. Você pode criar uma Habilidade de diretrizes de marca que inclua a paleta de cores da sua empresa, regras de tipografia e especificações de layout. Quando Claude cria apresentações ou documentos, aplica automaticamente esses padrões sem que você precise explicá-los toda vez.

Conhecimento específico de domínio

Isso provavelmente é onde as habilidades são mais úteis no trabalho do dia a dia. Qualquer domínio que exija que Claude saiba algo que ele não aprenderia com o treinamento geral — suas convenções internas de API, um formato de dados proprietário, um fluxo de trabalho específico de uma empresa — pode ser transformado em uma habilidade e reutilizado sem precisar repeti-lo em cada prompt.

Preferências de uso de ferramentas

As habilidades podem especificar quais ferramentas preferir, em que ordem e sob quais condições. Quando Claude invoca uma habilidade, o sistema segue um fluxo de trabalho simples: ele carrega o SKILL.md, expande-o em instruções detalhadas, injeta essas instruções como novas mensagens do usuário no contexto da conversa, modifica o contexto de execução (ferramentas permitidas, seleção de modelo) e continua a conversa com esse ambiente enriquecido.

Requisitos de estrutura de saída

Você pode definir modelos de saída muito precisos dentro de uma habilidade. O repositório GitHub de habilidades da Anthropic possui múltiplos exemplos mostrando como ancorar Claude a formatos exatos — estruturas de relatórios, padrões de mensagens de commit, layouts de arquivos de teste.

O que as Habilidades Não Podem Fazer

Executar código

SKILL.md é conteúdo de instrução, não código executável. Ele diz a Claude como abordar uma tarefa; não executa nada por si só. Scripts dentro do diretório /scripts de uma habilidade podem ser invocados por Claude durante a execução da tarefa, mas o SKILL.md em si é apenas texto.

Aprender com erros

Habilidades customizadas não são sincronizadas entre superfícies. Habilidades enviadas para uma superfície não ficam automaticamente disponíveis em outras. Mais fundamentalmente, uma habilidade não se atualiza com base no que aconteceu em uma sessão passada. As instruções são estáticas até que você as edite. Achei útil lembrar disso — uma habilidade é um instantâneo de expertise, não um ciclo de aprendizado.

Compartilhar automaticamente entre agentes ou sessões

Habilidades são limitadas às superfícies em que estão instaladas. Uma habilidade criada no Claude Code não está automaticamente disponível no Claude.ai ou através da API, a menos que você a envie separadamente.

Habilidades vs. Prompts do Sistema vs. Regras de Projeto vs. Memória

Foi aqui que passei mais tempo me confundindo. Aqui está como entendo as diferenças agora:

Mecanismo	O que faz	Escopo	Persiste entre sessões?
SKILL.md	Instruções específicas de domínio carregadas sob demanda	Projeto ou global do usuário	Sim (baseado em arquivo)
CLAUDE.md	Contexto e convenções do projeto sempre carregados	Nível do projeto	Sim (baseado em arquivo)
Prompt do sistema	Define o comportamento base do modelo	Nível API/SDK	Apenas se você definir a cada vez
Projetos (claude.ai)	Contexto persistente para um corpo de trabalho em andamento	Espaço de trabalho Claude.ai	Sim
Memória	Recordação entre conversas das preferências	Nível do usuário	Sim, se ativado

Skills ensinam Claude como fazer algo. Um Projeto pode conter todos os detalhes do lançamento do seu produto, enquanto uma skill pode ensinar a Claude os padrões de escrita da sua equipe ou o processo de revisão de código.

CLAUDE.md é um arquivo especial que Claude lê no início de cada conversa. Inclua comandos Bash, estilo de código e regras de fluxo de trabalho. Isso fornece a Claude um contexto persistente que ele não consegue inferir apenas a partir do código. A principal diferença em relação ao SKILL.md: o CLAUDE.md carrega sempre; as skills carregam quando relevante.

O prompt de sistema do Claude Code já contém cerca de 50 instruções individuais. Dependendo do modelo, isso é quase um terço das instruções que seu agente pode seguir de forma confiável — antes de regras, plugins, skills ou mensagens do usuário. Esse número me marcou. Ele muda a forma como você pensa sobre quanto colocar em cada camada.

FAQ

1 Onde está a documentação oficial das Skills do Claude Code?

A referência principal é a documentação de skills do Claude Code. Para o padrão mais amplo de Agent Skills — incluindo como skills pré-construídas e personalizadas funcionam no Claude.ai e na API — veja a visão geral das Agent Skills na documentação da plataforma Anthropic.

2 Qual formato o SKILL.md utiliza?

SKILL.md é um arquivo Markdown com frontmatter YAML. O frontmatter requer dois campos — name e description — que Claude lê no início da sessão para decidir quando carregar a skill. O corpo Markdown contém as instruções reais que Claude segue quando a skill é invocada. Campos opcionais incluem context e agent para controle avançado de execução.

3 Qual o tamanho que um arquivo SKILL.md pode ter?

Não há um limite rígido imposto. A divulgação progressiva é o princípio central de design que torna as Skills do Agente flexíveis e escaláveis — as skills permitem que Claude carregue informações apenas conforme necessário, portanto a quantidade de contexto que pode ser incorporada em uma skill é efetivamente ilimitada. Dito isso, a orientação prática mais comum recomenda manter o arquivo SKILL.md principal com menos de 500 linhas e transferir detalhes para arquivos de suporte em references/.

Ainda não tenho certeza se mapeei todos os casos extremos aqui. O comportamento de disparo da skill — quando Claude decide que uma skill é relevante versus quando não é — é mais difícil de prever do que a documentação do formato sugere. Claude tende a "subativar" skills — não usá-las quando seriam úteis. Isso é algo a ser lembrado ao escrever seu campo de descrição.

Continuarei observando como isso evolui.

Documentação de Habilidades do Código Claude: A Referência Completa para Desenvolvedores