o problema
Um agente que sabe tudo desde o começo paga por tudo desde o começo. Todo procedimento, toda convenção interna, todo detalhe de formato de arquivo que o modelo talvez precise tem que estar no system prompt antes de alguém saber se a conversa vai chegar lá. A janela de contexto é finita e é a mesma que o trabalho de verdade vai usar. Quanto mais especialista você tenta deixar o agente, menos espaço sobra para a tarefa.
A alternativa até aqui era o prompt: instrução de nível de conversa, boa para tarefa avulsa. O custo é a repetição. Cada conversa nova recomeça do zero, e quem sabe como a empresa preenche um formulário ou nomeia uma planilha explica de novo toda vez. O conhecimento fica preso num chat: não versionado, não composto com outro, não auditável.
a ideia
Uma skill é uma pasta no filesystem. Dentro dela, um SKILL.md com frontmatter YAML e o que mais for útil: outros markdowns, scripts executáveis, esquemas de banco, documentação de API, exemplos. A documentação usa a analogia do guia de onboarding que você escreveria para alguém novo no time — você não despeja tudo no primeiro dia, você entrega o índice e diz onde está o resto.
O que faz isso caber no contexto é progressive disclosure: a informação entra em estágios, conforme a necessidade aparece. O modelo não recebe a skill, ele recebe o endereço dela e um resumo de uma linha. Se o pedido bater com o resumo, ele vai ler o arquivo. É a diferença entre carregar uma biblioteca e carregar o índice remissivo dela.
como funciona
São três níveis, cada um carregado num momento diferente.
Nível 1, sempre carregado: o frontmatter. name e description entram no system prompt na inicialização, a cerca de 100 tokens por skill.
---
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.
---name aceita no máximo 64 caracteres, só minúsculas, números e hífen, e não pode conter as palavras reservadas “anthropic” e “claude”. description vai até 1.024 caracteres e é a peça que decide tudo: é contra ela que o pedido do usuário é comparado. Por isso ela precisa dizer o quê e quando, não só o quê.
Nível 2, no gatilho: o corpo do SKILL.md, abaixo de 5.000 tokens, com o procedimento em prosa. O modelo lê o arquivo com bash — um cat — e só nesse momento o conteúdo entra na janela.
Nível 3, sob demanda: os arquivos ao redor. Se o SKILL.md aponta para FORMS.md ou para um esquema de tabela, o modelo lê aquele arquivo específico e ignora os outros. Se aponta para scripts/fill_form.py, o modelo executa o script via bash e recebe só a saída — o código-fonte nunca ocupa contexto. É daí que vem a afirmação de que não há limite prático para o conteúdo empacotado: dezenas de arquivos de referência custam zero até serem abertos.
O lugar da pasta muda por superfície. No Claude Code, ~/.claude/skills/ para pessoal e .claude/skills/ para projeto, sem upload nenhum. Na API, você sobe pelos endpoints /v1/skills e referencia o skill_id no parâmetro container, com a code execution tool ligada — é o container dela que hospeda a skill. No claude.ai, zip pelas configurações.
o que isso custou
A superfície de ataque é o ponto que a própria documentação levanta primeiro. Uma skill dá ao agente instruções e código; uma skill maliciosa dirige o agente a usar ferramentas de um jeito que não combina com o propósito declarado. O conselho é tratar como instalação de software: auditar todos os arquivos, desconfiar de skills que buscam dados em URL externa, lembrar que uma dependência externa confiável hoje pode mudar amanhã. O scanning de conteúdo existe para Enterprise, mas não cobre o que sobe pela Skills API nem pelo Console.
A fragmentação é o segundo custo. Skills não sincronizam entre superfícies: o que está no claude.ai não está na API, o que está na API não está no claude.ai, e o Claude Code é um terceiro mundo baseado em arquivo. O escopo de compartilhamento também é diferente em cada uma — individual no claude.ai, workspace inteiro na API — e o claude.ai não tem distribuição centralizada por admin.
O runtime restringe o que dá para escrever. Na API não há rede nem instalação de pacote em runtime: só o que já vem no container. No Claude Code é o oposto, acesso total de rede, com a recomendação de instalar pacote localmente para não sujar a máquina de quem usa. A mesma skill não roda igual nos dois lugares. E o recurso está fora dos acordos de zero data retention.
onde isso aparece hoje
A Anthropic entrega skills prontas para os quatro formatos de documento — pptx, xlsx, docx e pdf — na API, no claude.ai, na Claude Platform na AWS e no Microsoft Foundry. Não no Claude Code, que em vez disso já vem com a Claude API skill, uma skill open source com referência de API e SDK para oito linguagens. O repositório anthropics/skills publica esse material. No Claude Code, os Plugins são a via para distribuir skills para um time.