Habilidades de Agentes Explicadas: O Que São, Como Usá-las e Como Diferem do MCP

Um guia de princípios fundamentais sobre as Habilidades do Agente de Claude: como funcionam, como construir uma com o criador de habilidades e como diferem dos servidores MCP.

Principais Conclusões

• Uma habilidade é uma pasta, não uma funcionalidade: Uma Habilidade do Agente é um diretório com um arquivo SKILL.md mais scripts e recursos opcionais. Ela ensina a Claude um procedimento uma vez, para que você não precise reexplicá-lo a cada conversa.
• Divulgação progressiva mantém os custos baixos: Claude carrega apenas o nome e a descrição de uma habilidade na inicialização (~100 tokens cada), lê as instruções completas apenas quando seu pedido corresponde e acessa arquivos agrupados somente se a tarefa precisar deles.
• Escreva uma vez, execute em qualquer lugar: O mesmo formato SKILL.md funciona em claude.ai, Claude Code, o SDK do Agente e a API. Como a Anthropic o publicou como um padrão aberto, ferramentas como Codex, OpenCode e Cursor também o leem - as habilidades não estão bloqueadas para Claude.
• o criador de habilidades cria habilidades para você: Há uma habilidade cuja única função é autorar habilidades. Ela entrevista você sobre o fluxo de trabalho, estrutura a pasta e escreve um SKILL.md bem formatado.
• Habilidades e MCP não são rivais: Habilidades são a receita (o que fazer e como). MCP é a cozinha (conexões ao vivo com ferramentas e dados). Você as usa juntas.

Você já explicou a mesma coisa para Claude pela quinta vez? O formato de compromisso da sua equipe. A maneira como sua empresa cria um relatório em PDF. Os passos exatos para formatar uma reunião. Você cola o mesmo bloco de instruções em um novo chat, novamente, porque o modelo não tem memória das quatro últimas.

A questão é: essa repetição não é uma limitação do modelo. É um problema de embalagem. O conhecimento já existe na sua cabeça, ele apenas não tem um lugar onde Claude possa acessá-lo sob demanda.

Essa é a lacuna que as Habilidades do Agente preenchem. A Anthropic as lançou em 16 de outubro de 2025, e a ideia é refrescantemente simples. Uma habilidade é uma pasta que você entrega ao agente, e ele lê essa pasta apenas quando a tarefa exige. Sem ajuste fino, sem SDK de plugin, sem reexplicações.

Vamos detalhar isso a partir de princípios fundamentais: o que uma habilidade realmente é, como funciona, como usar uma (e gerar a sua) e por que é uma coisa diferente de um servidor MCP, não um concorrente.

O que é realmente uma Habilidade do Agente

Esqueça a moldura de marketing por um segundo. Fundamentalmente, uma Habilidade do Agente é um diretório em um sistema de arquivos. Em sua raiz, há um arquivo obrigatório, SKILL.md, e essa é a habilidade mínima viável.

A própria analogia da Anthropic é a melhor: uma habilidade é o guia de integração que você escreveria para um novo colega de equipe - as instruções, material de referência e, às vezes, scripts que eles precisam para fazer um trabalho específico da maneira que sua equipe faz.

SKILL.md tem duas partes. Primeiro, um bloco de frontmatter YAML com dois campos obrigatórios: um name e uma description. Em segundo lugar, o corpo, que é markdown simples dizendo a Claude como realizar a tarefa.

---
name: processamento-pdf
description: "Extrair texto e tabelas de PDFs, preencher formulários, mesclar documentos. Use quando trabalhando com arquivos PDF ou formulários."
---

# Processamento de PDF
## Início rápido
Use pdfplumber para extrair texto...

Esse campo description está fazendo mais trabalho do que parece. Ele é o gatilho, o texto que Claude compara ao seu pedido para decidir se a habilidade é relevante. Portanto, ele deve indicar tanto o que a habilidade faz quanto quando usá-la. Descrições vagas significam que a habilidade nunca é acionada. (As regras são rigorosas: name tem um limite de 64 caracteres em minúsculas e hifens, description de 1.024.)

Além de SKILL.md, uma habilidade pode agrupar o que for necessário para o trabalho: arquivos markdown extras (FORMS.md, REFERENCE.md), scripts executáveis (fill_form.py) ou recursos brutos como esquemas e modelos. Nenhum deles é obrigatório - a habilidade mais simples e útil é um único arquivo.

Como as Habilidades Funcionam: Divulgação Progressiva

Aqui é onde fica interessante. Se você instalar vinte habilidades, pode esperar vinte manuais lotados na janela de contexto de Claude antes de digitar uma palavra, um desastre tanto para custo quanto para foco.

A questão fundamental que as habilidades resolvem é a economia de contexto, e o mecanismo é chamado de divulgação progressiva. Claude carrega informações em três níveis, cada um em um momento diferente.

1. Metadados (sempre carregados). Na inicialização, Claude lê apenas o name e a description de cada habilidade instalada, aproximadamente 100 tokens cada, em seu prompt de sistema. É isso. Vinte habilidades custam alguns milhares de tokens no total, e Claude agora sabe o que está disponível sem conhecer os detalhes.

2. Instruções (carregadas quando acionadas). Quando seu pedido corresponde à descrição de uma habilidade, Claude executa um comando bash para ler o corpo completo de SKILL.md do disco. Somente agora as instruções reais, mantidas em cerca de 5k tokens, entram na janela de contexto.

3. Recursos e código (carregados conforme necessário). Arquivos agrupados não custam tokens até que Claude realmente os abra. Precisa do esquema de vendas, mas não do guia de formulários? Claude lê apenas o esquema. Uma habilidade pode enviar dezenas de arquivos de referência sem penalidade de contexto para aqueles que uma tarefa específica nunca acessa.

A parte de manipulação de scripts é a que eu mais gosto. Quando uma habilidade inclui validate_form.py,