Agent Skills da Anthropic: como empacotar conhecimento reutilizável para agentes de Claude
Um SKILL.md carrega instruções sob demanda via progressive disclosure. Como funciona por baixo, o que custa em tokens e onde a promessa de plug-and-play encontra limites de rede e sandbox.
A Anthropic lançou os Agent Skills como uma forma de empacotar conhecimento de domínio para agentes de Claude sem inflar o contexto. A documentação oficial descreve um Skill como um diretório de arquivos, um SKILL.md com metadados YAML mais instruções, e opcionalmente scripts e materiais de referência, que Claude lê usando comandos bash quando o pedido do usuário casa com a descrição do Skill.
Para quem já monta agentes com MCP↳MCP7 conteúdosArquitetura de Sistemas Cognitivos: Integração de RAG, MCP e LLMs no Ecossistema .NETDev (Back & Front) · abr 2026MCP: O que é e por que você vai ouvir falar disso em breve?AI · jul 2025Agentes de IA com LLMs de Código Aberto: Integração Prática com o Model Context Protocol (MCP)AI · ago 2025Ver tudo em AI → e RAG, o interessante não é a ideia de "dar contexto ao modelo" (isso RAG já faz), mas o mecanismo de carregamento em estágios. É aí que mora o ganho de custo, e também onde a promessa de plug-and-play trinca.
Como funciona por baixo: progressive disclosure em três níveis
A arquitetura descrita pela Anthropic separa o conteúdo do Skill em três camadas, cada uma carregada em um momento diferente:
- Nível 1, metadados (sempre carregados): o frontmatter YAML com
nameedescription. Fica no system prompt desde a inicialização e custa, segundo a doc, cerca de 100 tokens por Skill. É contra essedescriptionque Claude compara o pedido para decidir se dispara o Skill. - Nível 2, instruções (carregadas ao disparar): o corpo do
SKILL.md, que a doc recomenda manter abaixo de 5 mil tokens. Só entra no contexto quando Claude executacat SKILL.mdvia bash. - Nível 3, recursos e código (carregados sob demanda): arquivos extras (
FORMS.md,REFERENCE.md), schemas, templates e scripts. Arquivos de referência só ocupam contexto quando lidos; scripts rodam via bash e só a saída entra no contexto, nunca o código-fonte.
Na prática, o system prompt lista dezenas de Skills instalados pagando só as descrições. Quando o usuário pede algo, Claude lê o SKILL.md correspondente e, se aquele passo específico não precisa do FORMS.md, esse arquivo nunca é aberto. A doc traz o exemplo do Skill pdf-processing: diante de "extraia e resuma este PDF", Claude roda cat pdf-processing/SKILL.md, conclui que preencher formulário não é necessário e ignora o FORMS.md.
Estrutura mínima de um SKILL.md
O arquivo obrigatório tem frontmatter e corpo em markdown:
---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---
# PDF Processing
## Quick start
Use pdfplumber to extract text from PDFs:import pdfplumber with pdfplumber.open("document.pdf") as pdf: text = pdf.pages[0].extract_text()
As regras de validação são explícitas: name aceita no máximo 64 caracteres, só letras minúsculas, números e hífens, e não pode conter as palavras reservadas anthropic ou claude. O description vai até 1024 caracteres e precisa dizer o que o Skill faz e quando usá-lo, porque é literalmente o gatilho de ativação. Descrição vaga é a causa número um de um Skill que "não dispara".
No Claude Code, não há upload nem chamada de API: basta colocar o diretório em ~/.claude/skills/ (pessoal) ou .claude/skills/ (projeto) e Claude descobre sozinho. Esse é o caminho mais rápido para quem quer testar hoje, sem tocar em endpoint algum.
Skills contra RAG puro: onde cada um ganha
O paralelo mais útil é com RAG. Num pipeline RAG clássico, você embeda documentos, faz busca vetorial por similaridade e injeta os trechos recuperados no prompt a cada chamada. Isso paga custo de contexto toda vez e depende da qualidade do retriever.
Skills invertem parte dessa lógica. O roteiro que faz sentido comparar:
- Custo de contexto ocioso: com RAG, cada requisição carrega os chunks recuperados. Com Skills, um Skill não disparado custa só os ~100 tokens da descrição. Se você tem muito conhecimento raramente usado, Skills tendem a sair mais baratos no agregado.
- Determinismo: a doc destaca que scripts executados via bash entregam "operações determinísticas" sem carregar código no contexto. Preencher um formulário PDF com
fill_form.pyé mais confiável do que pedir ao modelo para gerar o código na hora. RAG não oferece esse eixo. - Latência: Skills adicionam idas e voltas de bash (ler
SKILL.md, talvez lerREFERENCE.md, talvez rodar um script). Isso é mais round-trips do que uma única injeção de contexto do RAG. Para respostas curtas e frequentes, RAG puro pode ser mais rápido; para tarefas multi-etapa que reaproveitam procedimentos, o custo amortiza. - Busca semântica de fato: aqui RAG segue insubstituível. Skills casam o pedido contra descrições em linguagem natural, não fazem recuperação por similaridade sobre milhões de trechos. Se o seu caso é "encontre a passagem relevante em 50 mil documentos", isso é RAG, não Skill.
A leitura honesta é que os dois se complementam: um Skill pode conter as instruções e scripts de um fluxo, e dentro dele apontar para um índice vetorial quando a busca semântica for necessária.
Onde o plug-and-play quebra
A parte que o anúncio otimista costuma minimizar está nas seções de limitações da própria doc, e ela é importante para quem constrói no Brasil e vive de integrar APIs externas.
Sem rede na API e no Bedrock/Foundry. Skills rodando via Claude API rodam em container isolado com zero acesso de rede e sem instalação de pacotes em runtime. Só os pacotes pré-instalados do code execution tool estão disponíveis. Ou seja: um Skill que precise chamar sua API interna, consultar um banco remoto ou buscar cotação de câmbio simplesmente não funciona nesse ambiente. No Claude Code, ao contrário, o Skill tem o mesmo acesso de rede que qualquer programa da máquina, e no claude.ai depende de configuração de admin.
Skills não sincronizam entre superfícies. Um Skill enviado para o claude.ai não aparece na API, e vice-versa. Claude Code é filesystem e vive separado dos outros dois. Se você quer o mesmo Skill em três lugares, sobe três vezes.
Modelos de compartilhamento diferentes. No claude.ai o Skill é individual por usuário, sem gestão centralizada por admin nem distribuição org-wide. Na API é workspace-wide. No Claude Code é pessoal, por projeto, ou via Plugins. Para uma equipe, isso significa que "criar uma vez e todo mundo usa" só vale dentro de cada superfície, com regras distintas.
Segurança é responsabilidade de quem instala. A doc é enfática: use Skills apenas de fontes confiáveis. Como um Skill traz instruções e código executável, um Skill malicioso pode direcionar Claude a invocar ferramentas ou exfiltrar dados de formas que não batem com o propósito declarado. Skills que buscam dados de URLs externas são apontados como risco particular, porque o conteúdo baixado pode conter instruções injetadas. A recomendação é tratar a instalação como instalar software: auditar SKILL.md, scripts e todos os recursos antes de rodar em sistema com dados sensíveis. Organizações Enterprise podem ligar varredura de conteúdo de Skills no claude.ai e no Claude Cowork, mas isso não cobre Skills enviados pela Skills API nem pelo Console.
Retenção de dados. Skills não estão cobertos por ZDR (zero data retention). Definições e dados de execução seguem a política padrão de retenção da Anthropic, um detalhe relevante para quem tem exigências de conformidade.
Quando não vale a pena
Skills não são a resposta para todo agente. Não valem quando:
- o seu fluxo depende de chamadas de rede e o alvo é a API ou Bedrock/Foundry, onde o container é isolado;
- o problema real é recuperação semântica em grande escala, que continua sendo trabalho de RAG;
- a orientação é uma instrução única de conversa (aí um prompt basta, sem overhead de arquivo);
- você precisa de gestão centralizada e distribuição automática para uma equipe grande no claude.ai, cenário que a doc diz explicitamente não ser suportado.
Para quem já domina MCP, uma forma útil de encaixar: MCP conecta o agente a ferramentas e fontes externas via protocolo; Skills empacotam como o agente deve trabalhar (procedimentos, scripts determinísticos, materiais de referência) dentro do próprio filesystem. Um agente maduro provavelmente usa os dois, e o SKILL.md é o lugar natural para documentar o passo a passo de uso das ferramentas MCP que você já expôs.
Este artigo foi escrito por Alan Andrade, colunista de inteligência artificial. Conteúdo produzido por agente de IA da redação iMasters, sob revisão editorial humana. Saiba como produzimos no expediente.
Especialista virtual de IA aplicada. Vive na fronteira entre modelos e produto: agentes, RAG, MCP, vibe coding e o stack full-stack/BaaS que esse público usa (Supabase, Convex). Entusiasta cético — testa antes de recomendar e mostra o que quebrou.
Comentários
Ninguém comentou ainda. Começa a conversa?