Agent Skills: como montar uma habilidade local no Claude Code
A Anthropic formalizou um padrão de pastas com SKILL.md para empacotar conhecimento reutilizável no Claude. O iMasters monta uma skill do zero e compara o resultado com o que já se fazia via MCP.
A Anthropic publicou a documentação oficial de Agent Skills, um formato para empacotar instruções, scripts e materiais de referência que o Claude passa a usar automaticamente quando o pedido do usuário combina com aquela capacidade. Não é um recurso novo isolado: é a formalização de um padrão de pastas que já existia informalmente em quem usava Claude Code para automatizar tarefas repetitivas, agora com regras de nomenclatura, limites de tamanho e um modelo de carregamento em camadas descrito em detalhe pela própria empresa.
O pulo do gato, segundo a documentação, é o carregamento progressivo: uma Skill não entra inteira no contexto só por existir. Ela é lida em três níveis, e cada nível custa um preço de token diferente.
Os três níveis de uma Skill
Toda Skill é uma pasta com um arquivo SKILL.md obrigatório, que começa com um front-matter YAML:
---
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.
---Esse bloco é o Nível 1: fica sempre carregado no system prompt, custa cerca de 100 tokens por Skill segundo a Anthropic, e é o texto contra o qual o Claude compara o pedido do usuário para decidir se aciona a Skill ou não. Na prática, isso significa que a qualidade da description é o fator que decide se a Skill dispara ou fica muda: ela precisa dizer o que a Skill faz E quando usá-la, porque é literalmente o único texto disponível até o gatilho acontecer.
O Nível 2 é o corpo do SKILL.md: instruções, workflows, exemplos de código. Só entra no contexto quando a descrição bate com o pedido, e a documentação recomenda mantê-lo abaixo de 5 mil tokens.
O Nível 3 são os arquivos anexos: scripts 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) →, PDFs de referência, esquemas de 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 →. Esses só são lidos se as instruções do Nível 2 mandarem o Claude abri-los, e scripts executáveis nunca entram no contexto como código: o Claude roda o script via bash e recebe só a saída. Isso quer dizer que uma Skill pode carregar um script de 500 linhas de validação e custar zero tokens de contexto até o momento em que é de fato executada.
Montando uma Skill local no Claude Code
O caminho mais direto para testar isso na prática é pelo Claude Code, porque ali as Skills são só arquivos no disco, sem upload nem API: bastaria criar a pasta em ~/.claude/skills/ (pessoal) ou .claude/skills/ na raiz do projeto (compartilhada com o time via versionamento).
mkdir -p .claude/skills/changelog-writer
cd .claude/skills/changelog-writerDentro dela, um SKILL.md mínimo seguindo exatamente o esqueleto que a Anthropic documenta:
---
name: changelog-writer
description: Gera entradas de changelog a partir do diff de commits recentes. Use quando o usuário pedir para atualizar o CHANGELOG.md ou resumir mudanças de uma branch.
---
# Changelog Writer
## Instructions
1. Rode `scripts/collect_diff.sh` para pegar os commits desde a última tag.
2. Agrupe por tipo (feat, fix, chore) usando o padrão Conventional Commits.
3. Escreva a entrada no topo do CHANGELOG.md, sem remover histórico.
## Examples
Entrada: "### Added\n- Suporte a filtro por data na API de relatórios"E um script em scripts/collect_diff.sh que faz o trabalho determinístico (rodar git log, filtrar por tag) sem que o Claude precise gerar esse comando na hora. É exatamente o caso de uso que a documentação chama de "operações determinísticas sem custo de contexto": o script roda, devolve texto puro, e só esse texto entra na conversa.
A partir daí, o funcionamento é automático: dentro de uma sessão do Claude Code, ao pedir algo como "atualiza o changelog com os commits da última semana", o Claude reconhece a descrição da Skill, lê o SKILL.md, executa o script e segue as instruções. Não há comando explícito para "ativar" a Skill, o gatilho é inteiramente por correspondência semântica entre o pedido e a description, o que torna a redação dessa linha o ponto mais sensível de todo o processo.
Onde isso se parece (e não se parece) com MCP
Quem já monta 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 → para dar ao Claude acesso a bancos de dados, APIs internas ou ferramentas de terceiros vai notar sobreposição de propósito, mas a arquitetura é diferente em pontos que importam na hora de escolher qual usar.
Um servidor MCP é um processo separado, rodando um protocolo, expondo tools com schema JSON estrito, e ficando ativo (ou pelo menos declarado) durante toda a sessão. Isso tem custo: as definições de tools de todo servidor MCP conectado ocupam contexto do início ao fim da conversa, não importa se são usadas ou não. Uma Skill, pelo desenho descrito pela Anthropic, custa só a metadata (~100 tokens) até ser efetivamente acionada, o que abre espaço para instalar dezenas delas sem penalidade de contexto.
Em compensação, MCP é protocolo aberto e portátil: o mesmo servidor funciona no Claude Desktop, em outros clientes compatíveis com MCP e em produtos de terceiros. Skills, pelo menos por enquanto, não sincronizam entre superfícies: uma Skill criada no Claude Code não aparece automaticamente no claude.ai, e uma Skill enviada pela API não fica disponível no claude.ai nem vice-versa. A documentação é explícita sobre isso na seção de limitações: é preciso subir a Skill separadamente para cada superfície onde ela deve funcionar.
Há também diferença de ambiente de execução. No Claude Code, uma Skill tem o mesmo acesso de rede que qualquer programa do usuário, o que é conveniente mas também é o ponto mais sensível de segurança. Já uma Skill rodando via API executa dentro do container da ferramenta de execução de código, sem acesso à rede e sem instalação de pacotes em tempo real, só com o que já vem pré-instalado nesse sandbox.
Onde a promessa quebra
A própria documentação da Anthropic lista os pontos que travam o discurso de "empacote uma vez, use em todo lugar". O primeiro já foi citado: Skills não sincronizam entre claude.ai, API e Claude Code, então times que usam o Claude em mais de uma superfície replicam a mesma pasta em três lugares, cada um com seu ciclo de atualização.
O segundo é segurança, tratado com um tom de alerta incomum para documentação técnica: uma Skill maliciosa pode instruir o Claude a rodar bash de forma que não corresponde ao que a description promete, e a recomendação oficial é tratar Skills de terceiros como se fosse instalar software desconhecido, auditando SKILL.md, scripts e qualquer chamada de rede embutida antes de usar. Isso pesa mais ainda no Claude Code, onde a Skill herda o acesso de rede completo da máquina do desenvolvedor, diferente do sandbox isolado da API.
O terceiro é o gatilho semântico: como não existe um comando explícito de invocação, uma description mal escrita simplesmente não dispara a Skill, e o desenvolvedor não recebe erro nenhum, o Claude só segue sem usá-la. Isso torna a fase de escrita da descrição menos trivial do que parece, e explica por que a própria Anthropic dedica um guia à parte só para isso (o Skill authoring best practices citado na documentação).
Para quem já mantém servidores MCP funcionando, a Skill não é substituto automático: ela resolve bem o caso de conhecimento procedural e scripts determinísticos que hoje viram um prompt gigante repetido em toda conversa, mas não substitui a necessidade de expor um sistema externo vivo, com autenticação e estado, que é o terreno onde o MCP continua sendo a peça mais adequada.
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.
