Agent Skills da Anthropic: como criar, instalar e versionar skills para o Claude Code

A Anthropic documenta os Agent Skills como pacotes de instruções e scripts que o Claude carrega sob demanda. Comparamos a estrutura de um Skill com um 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 → server equivalente para entender onde cada abordagem compensa.

A documentação oficial da Anthropic (docs.claude.com) já trata os Agent Skills como parte padrão do Claude Platform: no claude.ai, na API, no Claude Code e, via Skills API, também na Claude Platform on AWS↳AWS20 conteúdosE-mails de verificação com AWS SES + Lambda (Node.js) e Terraform: do zero ao envioDevSecOps · out 2025Codex na AWS: chegada do agente da OpenAI à nuvem da AmazonDevSecOps · abr 2026Salesforce e AWS ampliam colaboração em IA, CRM e marketplaceDevSecOps · nov 2023Ver tudo em DevSecOps → e no Microsoft Foundry. Com o recurso consolidado nessas superfícies, a pergunta que interessa a quem desenvolve não é mais "o que é isso", e sim "quando vale a pena usar em vez de um MCP server".

A resposta curta, na prática: Skill é pacote de conhecimento; MCP é integração com sistema externo. A resposta longa exige entender como o Claude carrega esse pacote por baixo dos panos.

O que é, de fato, um Agent Skill

Um Skill é um diretório no filesystem que o Claude acessa com bash, como se navegasse em pastas do seu computador. Dentro dele vive pelo menos um arquivo SKILL.md com YAML frontmatter (name e description), podendo incluir arquivos markdown adicionais, scripts executáveis e materiais de referência (schemas, templates, documentação de API).

A diferença central para um prompt reaproveitável é que o Skill não precisa ser colado manualmente em cada conversa: uma vez instalado, o Claude decide sozinho quando usá-lo, comparando o pedido do usuário com o campo description do frontmatter.

Os três níveis de carregamento

A documentação chama isso de progressive disclosure, e é o conceito que sustenta toda a proposta de eficiência de contexto:

Na prática, isso significa que é possível instalar dezenas de Skills sem penalidade de contexto: só o name e a description ficam residentes. O corpo do SKILL.md só entra na janela quando o pedido do usuário casa com a descrição, e um script como validate_form.py roda inteiro via bash sem que seu código jamais apareça no contexto, só a saída.

Criando um Skill para o Claude Code: o roteiro

Num projeto típico, o caminho que eu seguiria para empacotar uma regra de revisão de API começaria pela estrutura de diretório, dentro de .claude/skills/ na raiz do repositório:

api-contract-check/
  SKILL.md
  REFERENCE.md
  scripts/
    validate_contract.py

O SKILL.md ficaria assim:

---
name: api-contract-check
description: Verifica se mudanças em uma rota respeitam o contrato definido em openapi.yaml. Use quando o pedido envolver alterar parâmetros, tipos de resposta ou status codes de um endpoint REST.
---

# Verificação de contrato de API

## Instruções
1. Leia `openapi.yaml` na raiz do repositório.
2. Rode `scripts/validate_contract.py` passando o diff do endpoint alterado.
3. Se o script reportar quebra de contrato, liste os campos afetados antes de seguir com a mudança.

## Referência
Para exceções de versionamento de API, veja REFERENCE.md.

O name segue as regras da Anthropic: até 64 caracteres, só minúsculas, números e hífen, sem as palavras "claude" ou "anthropic". A description é o campo que decide se o Skill dispara ou não, então precisa dizer o quê e quando, não só o quê.

Com o arquivo salvo em .claude/skills/api-contract-check/, o Claude Code descobre e usa o Skill automaticamente na próxima sessão, sem upload, sem endpoint de API: é leitura de filesystem.

Versionar um Skill é versionar um arquivo

Esse é o ponto onde o Claude Code se diferencia das outras superfícies. Como o Skill vive dentro do próprio repositório (.claude/skills/), ele entra no git add, aparece no diff do pull request e é revisado como qualquer outro arquivo de configuração do projeto.

Isso resolve um problema real das outras duas formas de distribuição que a documentação descreve. No claude.ai, Skills são individuais por usuário, sem gestão centralizada por admin. Na API, Skills são compartilhados por workspace inteiro, mas exigem upload via /v1/skills toda vez que mudam. Nenhuma das duas sincroniza com as outras: a Anthropic é explícita sobre isso, chamando de cross-surface availability a ausência de sincronização entre claude.ai, API e Claude Code.

Para compartilhar um Skill do Claude Code além do próprio time que clona o repositório, a documentação aponta os Claude Code Plugins como mecanismo de distribuição, mas isso já é outra camada de empacotamento sobre a mesma ideia de diretório com SKILL.md.

Skill ou MCP server?

Um MCP server resolve um problema diferente: ele expõe tools, resources e prompts através de um protocolo, geralmente rodando como processo separado (stdio ou HTTP), com schema de entrada validado e, na maioria das implementações, acesso de rede e estado entre chamadas. É a peça certa quando o Claude precisa conversar com um sistema vivo: banco de dados↳Banco de dados134 conteúdosSQL ou NoSQL: eis a questão!!Data · mar 2020Banco de dados: como organizar e dar segurança para milhões de dados de loteriasData · mai 20215 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data →, API de terceiro, fila de mensagens.

Um Skill não substitui isso. Ele não mantém conexão, não expõe schema tipado e, na API, roda num container sandbox sem acesso à rede e sem instalação de pacotes em tempo de execução, segundo a própria seção de limitações da documentação.

Em resumo: se o objetivo é "faça essa tarefa sempre do mesmo jeito, com os mesmos passos", é Skill. Se o objetivo é "converse com esse sistema que muda em tempo real", é MCP.

Onde cada abordagem quebra

Um Skill quebra quando o problema exige rede ou estado que o ambiente não oferece. Na API, qualquer script que dependa de uma chamada HTTP externa falha, porque o container Skills roda sem acesso à internet; e qualquer pacote Python↳Python56 conteúdosVSCode + Python + Alexa: Desenvolva e teste skills para alexa localmente com pythonDev (Back & Front) · out 2025Dominando decoradores em Python: um guia completo com exemplosDev (Back & Front) · jan 2025Desenvolvimento de software: diferenças entre Python, JavaScript e JavaGestão Dev & TI · nov 2024Ver tudo em Dev (Back & Front) → não pré-instalado também falha, porque não há instalação em runtime. No claude.ai, o acesso de rede varia conforme a configuração do administrador, então um Skill que funciona para um usuário pode não funcionar para outro.

Um MCP server quebra de outra forma: exige manter um processo rodando, cuidar de autenticação, lidar com timeout e versionamento de protocolo, e todo esse boilerplate existe mesmo para expor uma regra de negócio simples que um SKILL.md de dez linhas resolveria sem servidor nenhum.

Caraterística, não defeito: instalar um Skill malicioso tem o mesmo risco de instalar um MCP server malicioso, mas auditar é mais simples no primeiro caso. A documentação recomenda tratar Skills como instalação de software, revisando SKILL.md, scripts e qualquer chamada de rede embutida antes de usar em produção, principalmente quando a fonte não é a própria Anthropic.

O que fica em aberto

A Anthropic lista Skill content scanning como recurso disponível apenas para organizações Enterprise, e só para uploads via claude.ai e Claude Cowork, não para a Skills API nem para o Claude Console. Isso deixa times menores dependendo de revisão manual, exatamente o ponto em que um MCP server customizado, por rodar em infraestrutura própria, pode oferecer mais controle de acesso.

Para quem já usa Claude Code no dia a dia, a estrutura .claude/skills/ versionada em git parece o caminho mais barato para padronizar workflows de equipe: não exige subir servidor, não exige conta de API separada, e o SKILL.md fica legível em qualquer revisão de código.

Fonte: Documentação oficial da Anthropic — Agent Skills