o problema
Modelos ficaram bons o bastante para operar um ambiente computacional inteiro. Claude Code roda comandos, lê e escreve arquivos, executa código. O que ele não tem é o que a Anthropic chama de conhecimento procedural e contexto organizacional: como a sua empresa nomeia branches, qual o passo a passo do seu fechamento contábil, que biblioteca você usa para mexer em PDF. Isso não está nos pesos e não vai estar.
A saída até então era construir um agente sob medida para cada caso de uso, ou empurrar tudo para o system prompt. O primeiro caminho produz coisas fragmentadas, que ninguém reaproveita nem compartilha. O segundo esbarra na janela de contexto: você paga token por todo conhecimento que carregou, inclusive o que a tarefa da vez não usa. E você tem que adivinhar antes o que o agente vai precisar depois.
a ideia
Uma skill é uma pasta. Dentro dela, um arquivo SKILL.md com instruções, e opcionalmente outros arquivos e scripts. O agente descobre essas pastas e carrega o conteúdo delas quando julga necessário.
A analogia dos autores é guia de onboarding de funcionário novo — não um manual que ele decora antes de começar, mas um material organizado que ele consulta na parte certa quando cai a tarefa. O princípio que sustenta isso tem nome no texto: progressive disclosure. Como um manual bem feito, que começa no sumário, passa pelos capítulos e termina no apêndice, a skill entrega informação em camadas, e o agente escolhe até onde descer.
como funciona
São três níveis, e vale entender a separação.
O primeiro é o frontmatter. Todo SKILL.md começa com YAML contendo name e description, ambos obrigatórios. No startup, o agente pré-carrega esses dois campos de cada skill instalada no system prompt — nada além disso. É o suficiente para ele saber que a skill existe e quando ela serve.
---
name: pdf
description: extrai texto, preenche formulários e manipula arquivos PDF
---O segundo nível é o corpo do SKILL.md. Se a tarefa parece pedir a skill, o agente lê o arquivo inteiro para o contexto. No exemplo do post, ele faz isso invocando a ferramenta Bash sobre pdf/SKILL.md — não há mecanismo especial de carregamento, é leitura de arquivo.
O terceiro nível são os arquivos vizinhos, referenciados por nome a partir do SKILL.md. A skill de PDF do exemplo tem reference.md e forms.md. Quem escreveu tirou as instruções de preenchimento de formulário do arquivo principal e as pôs em forms.md, confiando que o Claude só vai abrir esse arquivo quando de fato for preencher um formulário. O núcleo fica enxuto; o detalhe fica a um passo de distância.
Skills também carregam código executável. A mesma skill de PDF traz um script Python que lê o arquivo e extrai os campos do formulário. O agente roda o script sem carregar nem o script nem o PDF no contexto — e o resultado é determinístico, o que a geração de token não garante.
Para escrever as suas, o post dá quatro orientações: comece pela avaliação, rodando o agente em tarefas representativas para achar onde ele trava; quebre o SKILL.md em arquivos separados quando ele crescer, principalmente se os caminhos forem mutuamente exclusivos; observe as trajetórias reais em vez de antecipar o que o agente precisa; e peça ao próprio Claude para registrar na skill o que deu certo e o que deu errado.
o que isso custou
O post é honesto sobre segurança e não tem como não ser: uma skill é instrução e código rodando no seu ambiente. Uma skill maliciosa pode abrir vulnerabilidade, exfiltrar dado ou levar o agente a agir onde não devia. A recomendação é instalar apenas de fonte confiável e, fora disso, auditar arquivo por arquivo, com atenção a dependências, recursos empacotados e qualquer trecho que mande o agente falar com rede externa.
Há um custo de projeto também. A skill só dispara se o name e a description fizerem o agente reconhecer a situação — o acerto do gatilho é responsabilidade de quem escreve, e o texto pede vigilância contra trajetórias inesperadas e contra dependência excessiva de certos contextos. Descobrir o que o agente realmente precisa é iterativo, não se especifica na primeira tentativa.
E o modelo inteiro pressupõe agente com filesystem e execução de código. Sem isso, a divulgação progressiva não existe: sobra empurrar texto para o contexto, que era o problema original. O post também não mede nada — não há benchmark, não há comparação, não há número de economia de token. É uma proposta de convenção, e deve ser lida assim.
onde isso aparece hoje
Skills funcionam hoje no Claude.ai, no Claude Code, no Agent SDK e na Claude Developer Platform. Em dezembro de 2025 a Anthropic publicou o formato como padrão aberto, com portabilidade entre plataformas como objetivo declarado. Os próprios autores apontam a relação com MCP: os dois se complementam, com skills ensinando workflows mais complexos que envolvem ferramentas externas. E deixam registrado o passo seguinte que pretendem dar — agentes criando, editando e avaliando as próprias skills, codificando os padrões de comportamento que já funcionaram.