Tutorial Oficial de Habilidades de Agente da Anthropic: Notas Completas do Curso de 6 Lições

A Anthropic finalmente lançou um vídeo tutorial oficial sobre Agent Skills, composto por 6 lições com duração total de 22 minutos. Ele cobre todo o ciclo de vida das Skills, desde o que são até como criar, configurar setups com múltiplos arquivos, diferenciá-las de outros recursos, compartilhá-las e solucionar problemas.

O maior valor deste tutorial não é apenas ensinar como escrever uma Skill, mas explicar a filosofia de design e os mecanismos subjacentes das Skills. Muitos problemas que as pessoas encontram ao usar Skills decorrem de uma compreensão insuficiente desses mecanismos.

Que Problemas as Skills Resolvem?

Toda vez que você explica os padrões de codificação da sua equipe para o Claude, você está se repetindo. Em toda revisão de PR, você tem que redescobrir como quer que o feedback seja organizado. Em toda mensagem de commit, você tem que lembrar o Claude do seu formato preferido.

As Skills são projetadas para eliminar essa repetição. Uma Skill é um arquivo Markdown que ensina ao Claude como fazer algo uma vez, e o Claude aplica automaticamente esse conhecimento em situações relevantes.

Mais precisamente, uma Agent Skill é uma pasta contendo instruções, scripts e recursos. O Claude pode descobrir e utilizar automaticamente esses itens para concluir o trabalho com mais precisão e eficiência.

O mecanismo central é o campo description. Quando o Claude inicia, ele carrega os nomes e descrições de todas as Skills. Quando você faz uma solicitação, o Claude realiza uma correspondência semântica entre sua solicitação e as descrições de todas as Skills disponíveis para encontrar e ativar a correspondente. Somente após a ativação, o conteúdo completo da Skill é carregado na janela de contexto.

Isso é fundamentalmente diferente do claude.md. O conteúdo do claude.md é carregado em todas as conversas, independentemente do que você está fazendo. Uma Skill é carregada apenas quando necessário; sua lista de verificação de revisão de PR não precisa estar no contexto durante a depuração, aparecendo apenas quando você realmente solicita uma revisão.

Quando você deve usar uma Skill? Se você se pega explicando repetidamente a mesma coisa para o Claude, essa é uma Skill esperando para ser desenvolvida.

Criando Sua Primeira Skill do Zero

Criar uma Skill requer apenas dois passos: criar um diretório e escrever um arquivo.

Passo um: Crie um diretório com o nome da Skill em ~/.claude/skills/. Colocá-lo aqui significa que é uma Skill de nível pessoal, disponível em todos os projetos.

Passo dois: Crie um arquivo SKILL.md no diretório. O arquivo é dividido em duas partes, separadas por três travessões. A parte superior são metadados YAML contendo name e description. A parte inferior contém as instruções específicas para o Claude seguir.

Quando o Claude Code inicia, ele verifica quatro locais em busca de Skills: caminhos empresariais, diretório de Skills pessoais, diretório de Skills do projeto e plugins instalados. Ele carrega apenas o nome e a descrição de cada Skill, não o conteúdo completo.

Quando você envia uma solicitação, o Claude compara a solicitação com todas as descrições de Skills. Se a intenção corresponder, ele primeiro pedirá que você confirme se deseja carregar a Skill. Somente após a confirmação ele lê o arquivo completo e executa as instruções. Esta etapa de confirmação mantém você ciente de qual contexto o Claude está usando.

Se existirem Skills com o mesmo nome, a prioridade do maior para o menor é: Nível Empresarial (managed-settings.json), Nível Pessoal (~/.claude/skills), Nível de Projeto (project/.claude/skills) e Nível de Plugin (project/.claude-plugins/skills).

Isso significa que uma empresa pode impor padrões por meio de Skills de nível empresarial, enquanto permite que indivíduos personalizem por meio de Skills com nomes diferentes. Se sua empresa tem uma Skill de revisão de código empresarial, você pode criar uma Skill pessoal chamada front-end-pr-review para complementar, em vez de sobrescrevê-la.

Configuração Avançada: Campos de Metadados e Divulgação Progressiva

Skills básicas precisam apenas de name e description, mas várias configurações avançadas podem tornar as Skills mais poderosas.

O campo allowed-tools pode limitar quais ferramentas o Claude pode usar quando a Skill está ativa. Por exemplo, se você tem uma Skill de análise somente leitura, pode proibir edição, escrita e comandos Bash. Se este campo for omitido, a Skill não impõe restrições, e o Claude usa o modelo de permissão normal.

O campo model pode especificar qual versão do modelo Claude usar.

A forma como a description é escrita determina diretamente se uma Skill pode ser acionada corretamente. Uma boa descrição deve responder a duas perguntas: O que esta Skill faz? Quando o Claude deve usá-la? Se uma Skill não acionar, adicione mais palavras-chave que correspondam à formulação de suas solicitações.

O conceito avançado mais importante é a divulgação progressiva. As Skills compartilham a janela de contexto com sua conversa. Se você colocar tudo em um SKILL.md de 20.000 linhas, ele consumirá um espaço de contexto massivo.

A abordagem correta é: coloque instruções essenciais no SKILL.md e materiais de referência detalhados em arquivos separados, que o Claude lê apenas quando necessário. A estrutura de diretórios recomendada para padrões abertos é: uma pasta scripts para código executável, references para documentos de referência e resources para arquivos de dados como imagens e modelos. Use links no SKILL.md para referenciar esses arquivos.

Regra chave: SKILL.md não deve exceder 500 linhas. Se exceder, deve ser dividido. Scripts podem ser executados diretamente sem carregar seu conteúdo no contexto; apenas a saída consome tokens. Então, diga ao Claude para executar o script em vez de lê-lo. Isso é particularmente útil para validação de ambiente e transformação de dados, pois o código de script testado é mais confiável do que a geração no momento.

Diferenças Entre Skills e Outros Recursos do Claude Code

Skills vs. claude.md: claude.md é sempre carregado em todas as conversas para padrões e regras do projeto que sempre se aplicam, como "Este projeto usa o modo estrito do TypeScript." As Skills são carregadas sob demanda, ativadas apenas quando o Claude corresponde a uma solicitação.

Skills vs. Sub Agents: As Skills adicionam conhecimento à conversa atual; uma vez ativadas, as instruções são adicionadas ao contexto existente. Os Sub Agents são executados em um contexto independente, completando tarefas e submetendo resultados separadamente, completamente isolados da conversa principal.

Skills vs. Hooks: Hooks são orientados a eventos, acionando quando eventos específicos ocorrem, como o Claude executar um Linter toda vez que um arquivo é salvo. As Skills são orientadas a solicitações, ativando com base nas perguntas que você faz.

Skills vs. MCP: O MCP fornece conexões de ferramentas externas, permitindo que o Claude chame serviços como Gmail ou Notion. As Skills fornecem conhecimento e fluxos de trabalho, dizendo ao Claude como usar essas ferramentas para concluir tarefas específicas.

Resumo em uma frase: claude.md contém instruções sempre ativas, Skills contêm conhecimento com correspondência automática, Sub Agents executam tarefas delegadas em contextos isolados, Hooks respondem a eventos e MCP se conecta a ferramentas externas. Eles podem ser usados em combinação.

Compartilhando Skills: De Indivíduos para Equipes para Organizações

O valor das Skills está em compartilhar. Uma Skill de revisão de PR usada apenas por você é útil, mas uma Skill compartilhada pela equipe pode padronizar revisões de código e fornecer uma experiência consistente.

Três maneiras de compartilhar:

A primeira é o diretório do projeto. Faça commit da Skill no diretório .claude/skills do repositório de código. Qualquer pessoa que clonar o repositório obtém automaticamente essas Skills sem instalação extra. As atualizações são recebidas no próximo pull. Isso é adequado para padrões de codificação da equipe e fluxos de trabalho específicos do projeto.

A segunda são plugins. Pense nos plugins como uma forma de distribuir Skills entre projetos. Uma vez enviado para uma loja de aplicativos, outros usuários podem baixá-los e instalá-los. Se sua Skill é genérica e não específica de um projeto, esta é a melhor escolha para membros da comunidade.

A terceira é a implantação empresarial. Os administradores enviam Skills para toda a organização por meio de configurações gerenciadas. As Skills de nível empresarial têm a prioridade mais alta e sobrescreverão Skills pessoais e de projeto com o mesmo nome. Isso é usado para padrões obrigatórios, requisitos de segurança e fluxos de trabalho de conformidade.

Uma nota importante: Sub Agents não herdam automaticamente suas Skills. Quando você delega uma tarefa a um sub-agente, ele começa com um contexto novo. Agentes integrados (Explorer, Plan, Verify) não podem acessar Skills; apenas sub-agentes personalizados que você define podem usá-las, e elas devem ser listadas explicitamente em agent.md.

Para criar um sub-agente personalizado com Skills, crie um arquivo agent.md no diretório .claude/agents e adicione um campo skills listando os nomes das Skills necessárias. Liste apenas Skills que são sempre relevantes para o objetivo do sub-agente, pois essas Skills serão carregadas quando o sub-agente iniciar.

Guia de Solução de Problemas: Seis Razões Pelas Quais as Skills Falham e Suas Soluções

Os problemas com Skills geralmente se enquadram em seis categorias:

1. Skill não acionando: A razão é quase sempre uma description mal escrita. O Claude usa correspondência semântica; sua solicitação precisa estar alinhada com o significado da descrição. Se não houver sobreposição suficiente, não haverá correspondência. Solução: Compare a descrição com a formulação da sua solicitação e adicione frases de acionamento que os usuários realmente dizem, como "me ajude a analisar", "por que isso está lento" ou "acelere isso".

1. Skill falhando ao carregar: Verifique caminhos e nomes de arquivos. SKILL.md deve estar dentro de um diretório nomeado, não diretamente na raiz das skills. O nome do arquivo deve ser exatamente SKILL.md em maiúsculas. Execute claude --debug para visualizar erros de carregamento.

1. Claude usando a Skill errada: Isso significa que você tem várias Skills com descrições muito semelhantes, tornando impossível para o Claude distingui-las. Solução: Torne cada descrição o mais específica possível para ajudar o Claude a decidir quando usar qual.

1. Skill pessoal sendo ignorada: Uma Skill de prioridade mais alta (como uma empresarial) com o mesmo nome pode estar a sobrescrevendo. Verifique os quatro níveis de prioridade. Solução: Renomeie sua Skill para algo mais único.

1. Plugin instalado, mas Skill não visível: Limpe o cache com rm ~/.claude/plugins/cache, reinicie o Claude Code e reinstale. Se ainda não funcionar, a estrutura de diretórios do plugin pode estar errada; use a ferramenta de validação skills-ref validate para verificar.

1. Skill carregada, mas falhando durante a execução: Se a Skill usa pacotes externos, certifique-se de que estejam instalados. Adicione informações de dependência à descrição da Skill.

A Anthropic também fornece uma ferramenta de validação chamada skills-ref para verificar se a estrutura de arquivos e a sintaxe YAML da Skill estão corretas. Recomenda-se instalá-la via uv para o método mais rápido.