Agent Skills da Anthropic: como empacotar uma capacidade reutilizável no Claude Code

A Anthropic documenta um formato chamado Agent Skills: pastas no sistema de arquivos que contêm instruções, scripts e materiais de referência para o Claude. A ideia, segundo a documentação oficial, é transformar um agente generalista em especialista sem repetir o mesmo prompt longo em toda conversa. A Skill fica instalada e o Claude decide sozinho quando usá-la, a partir da descrição declarada no próprio arquivo.

Isso é diferente de um prompt de sistema fixo. Prompt é instrução de uma conversa só; Skill é um pacote que carrega sob demanda, e pode ser combinado com outras Skills para tarefas de múltiplas etapas. O documento compara a estrutura a um guia de onboarding que você escreveria para um novo integrante do time: regras, exemplos e scripts auxiliares organizados em arquivos.

Os três níveis de carregamento

O ponto central da arquitetura é o que a Anthropic chama de progressive disclosure: nem todo conteúdo da Skill entra no contexto ao mesmo tempo. A documentação descreve três camadas, cada uma carregada em um momento diferente.

Na prática isso significa que dá para instalar dezenas de Skills sem penalidade de contexto: enquanto nenhuma é acionada, só o par nome/descrição ocupa espaço. Scripts são o caso mais econômico: o código do script nunca entra no contexto, só a saída que ele produz.

Montando uma Skill local no Claude Code

No Claude Code, Skills são puramente baseadas em arquivo: não existe upload via API, basta criar a pasta em .claude/skills/ (escopo de projeto) ou ~/.claude/skills/ (escopo pessoal). Um exemplo que cabe no dia a dia de um time Brasil: uma Skill que valida mensagens de commit contra Conventional Commits antes de abrir um PR.

.claude/skills/commit-lint/
├── SKILL.md
└── scripts/
    └── check_commit.py

O SKILL.md começa com o frontmatter YAML obrigatório, que define name e description. A documentação é explícita: a description é o texto contra o qual o Claude compara o pedido do usuário para decidir se aciona a Skill, então ela precisa dizer o quê e quando usar.

---
name: commit-lint
description: Valida mensagens de commit contra o padrao Conventional Commits do time. Use quando o usuario pedir para revisar, corrigir ou gerar mensagens de commit antes de um push ou PR.
---

# Commit Lint

## Instrucoes
1. Leia a mensagem de commit fornecida pelo usuario.
2. Rode `scripts/check_commit.py` passando a mensagem como argumento.
3. Se o script apontar erro, reescreva seguindo o padrao tipo(escopo): descricao.

## Exemplos
- Entrada: "ajustei o bug do login"
- Saida sugerida: "fix(auth): corrige validacao de sessao expirada no login"

O script é o que garante determinismo: em vez de o Claude "lembrar" a regra e aplicá-la de forma inconsistente, uma regex fixa decide.

import sys, re

PATTERN = r"^(feat|fix|docs|refactor|test|chore)\(.+\): .{10,}"

msg = sys.argv[1]
if re.match(PATTERN, msg):
    print("OK: mensagem valida")
else:
    print("ERRO: use tipo(escopo): descricao com pelo menos 10 caracteres")

O fluxo quando a Skill é acionada

Segundo a documentação, o ciclo segue uma sequência fixa: na inicialização, o name e a description da Skill entram no prompt de sistema. Quando o usuário pede algo como "revisa essa mensagem de commit", o Claude compara o pedido com as descrições disponíveis e, se bater, lê o SKILL.md inteiro via bash (um cat commit-lint/SKILL.md, por exemplo). A partir das instruções, ele decide quais arquivos adicionais precisa e executa o check_commit.py, recebendo só a linha de saída, nunca o código do script.

Esse comportamento é o que separa Skills de simplesmente colar um arquivo de instruções no prompt: arquivos de referência que não são necessários para a tarefa específica custam zero tokens, mesmo que a Skill tenha dezenas deles. A documentação cita como exemplo uma Skill de processamento de PDF que inclui um guia de preenchimento de formulário (FORMS.md) separado das instruções principais, carregado só quando a tarefa realmente envolve formulário.

Skill ou servidor MCP: quando usar cada um

O ângulo prático para quem já integrou servidores 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 → é entender onde as duas peças se sobrepõem e onde não. MCP é um protocolo de conexão: um servidor roda (local ou remoto), expõe tools com schema tipado, e o Claude chama essas tools em tempo real para ler ou escrever em sistemas externos. Skill não é protocolo de conexão nenhuma; é um pacote de conhecimento procedural que mora no sistema de arquivos e é lido com bash.

Na prática, as duas coisas tendem a se complementar em vez de competir. Uma Skill pode documentar como e quando chamar as tools de um servidor MCP específico do time, dando contexto de uso que o schema das tools sozinho não carrega. Quando a tarefa é puramente de convenção ou script determinístico, sem precisar de conexão persistente com sistema externo, a Skill sozinha já resolve e custa menos contexto do que manter um servidor MCP de propósito único no ar.

O que fica de fora

A documentação é clara sobre limites que valem considerar antes de levar Skills para produção. Skills não sincronizam entre superfícies: uma criada em .claude/skills/ no Claude Code não aparece na API nem no claude.ai, é preciso subir separadamente em cada lugar. No Claude API, o ambiente roda sem acesso a rede e sem instalação de pacote em tempo de execução, o que restringe o que um script dentro da Skill pode fazer ali (no Claude Code o acesso de rede é o mesmo de qualquer programa da máquina do usuário).

O alerta de segurança da própria Anthropic merece reprodução: Skills de origem externa podem instruir o Claude a invocar bash ou rede de forma que não bate com o propósito declarado. A recomendação é tratar a instalação de uma Skill como instalação de software: auditar SKILL.md, scripts e qualquer chamada de rede embutida antes de usar em ambiente com dado sensível. Para quem já audita servidores MCP de terceiros, o cuidado é o mesmo, só que agora espalhado por arquivos de texto em vez de um binário.

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