Agent Skills e SKILL.md: progressive disclosure, medido

O Capítulo 14 definiu a regra para a segunda metade deste curso — conexões, tentativas novamente e cancelamento são TypeScript — e declarou cinco exceções. Esta é uma delas, e o motivo não é preferência.

Uma skill é um arquivo Markdown. Não um arquivo que configura um programa, não um arquivo que um programa compila: um documento que o modelo lê, do mesmo modo como lê a mensagem que você digitou. Dar a este capítulo uma linguagem de programação significaria não ter entendido o formato, e esse mal-entendido é o mais comum sobre skills. Tudo abaixo é Markdown e YAML, mais um pequeno script shell que existe justamente para mostrar onde código pertence e onde não pertence dentro de uma skill.

Aqui está uma instrução real: como uma empresa escreve suas notas de versão. É um procedimento, não uma preferência — tem um conjunto ordenado de etapas, uma taxonomia, uma voz, um template e um script que coleta a matéria-prima.

Coloque tudo isso no system prompt, como a maioria das equipes faz, e a aritmética do Capítulo 16 assume o controle. Um system prompt é um prefixo, e um prefixo é pago em toda chamada. Medido com o200k_base sobre a pasta escrita para este capítulo:

whole thing pasted into the system prompt   1,716 x 40  =  68,640 input tokens   $0.1373
as a skill, activated once on turn 12          46 x 40
                                            + 324 (SKILL.md body)
                                            + 665 (two reference files read)
                                                        =   2,829 input tokens   $0.0057
as a skill, never activated at all             46 x 40  =   1,840 input tokens   $0.0037

Vinte e quatro vezes mais barato quando é usado, trinta e sete vezes mais barato quando não é. As tarifas são as do Capítulo 16: $2,00 por milhão de input tokens.

Agora a objeção honesta, porque um capítulo que a ignorasse seria propaganda. Prompt caching fecha quase toda a lacuna de dinheiro. Um system prompt é estável e fica no início, o que o torna o melhor candidato a cache que existe; a $0,20 por milhão para input em cache, os mesmos 68.640 tokens custam $0,0168 em vez de $0,1373. Ainda três vezes a skill, mas já não uma ordem de grandeza diferente.

O dinheiro nunca foi o argumento mais forte. Este é:

O cache torna um prefixo permanente mais barato. Ele não o torna menor.

No turno 40, a versão com system prompt ainda tem 1.716 tokens de política de notas de versão sentados na window durante uma conversa sobre algo completamente diferente, competindo pelo que o Capítulo 24 chamou de orçamento de attention do modelo. A versão com skill tem 46. Faça cache da coisa errada e você comprou um desconto em uma distração.

Escrito como fórmula, com $n$ turnos, $L_1$ os metadados, $L_2$ o corpo, $L_3$ o pacote inteiro e $R$ o conjunto de arquivos empacotados efetivamente lidos:

Todo este capítulo é a diferença entre multiplicar o segundo termo por $n$ e multiplicá-lo por um ou por zero.

Uma skill é um diretório. A especificação é curta o bastante para ser apresentada por completo:

release-notes/
├── SKILL.md          # required: YAML frontmatter + Markdown instructions
├── scripts/          # optional: executable code
├── references/       # optional: documentation read on demand
├── assets/           # optional: templates, schemas, examples
└── ...               # anything else you like

SKILL.md deve começar com YAML frontmatter, e exatamente dois campos são obrigatórios: name e description.¹ Outros quatro são opcionais e nenhum outro é definido:

Aqui está a skill de notas de versão, completa, com o corpo em menos de trinta linhas:

---
name: release-notes
description: Write the release notes for a tagged version in this company's house style. Use when preparing a release, drafting a changelog entry, or when someone asks for the notes for a version number or a tag.
allowed-tools: Bash(git log:*) Bash(git tag:*) Read
---

# Release notes

## Procedure

1. Run `scripts/collect.sh <previous-tag> <new-tag>`. It prints one line per merged
   pull request: number, title, author and the labels.
2. Drop every line whose labels contain `internal`, `ci` or `chore`.
3. Put each surviving line into exactly one of the four categories in
   [references/categories.md](references/categories.md). A change that seems to fit two
   belongs in the higher one; the order in that file is the order of precedence.
4. Rewrite each line as a sentence in the voice defined in
   [references/voice.md](references/voice.md). The pull request title is a note to
   the team; the release note is a note to a stranger.
5. Check the result against [references/examples.md](references/examples.md).

## The one rule that is not negotiable

Every note says what a person can now do, or what stopped happening to them. If a
sentence can only be understood by someone who has read the diff, it is not finished.

Leia o que esse corpo é. Ele não é a política — é um sumário com uma ordem de operações. A política vive em três arquivos que ele nomeia e não inclui. E o passo um entrega trabalho a um script, porque o código de um script nunca entra na context window: só a saída dele entra.²

O modelo de carregamento tem um nome e três estágios. A especificação os declara com um orçamento de tokens associado:¹

1. Metadados, cerca de 100 tokens: name e description, carregados na inicialização para toda skill instalada.
2. Instruções, recomendado abaixo de 5.000 tokens: o corpo de SKILL.md, carregado quando a skill é ativada.
3. Recursos, conforme necessário: arquivos empacotados, carregados apenas quando algo os exige.

A documentação de referência coloca uma quarta coluna na mesma tabela — quando carregado, custo em tokens, conteúdo — e a linha que importa é a terceira: nenhum até ser acessado.³ A frase que resume o capítulo inteiro também está lá:

Files don't consume context until accessed, so Skills can include comprehensive API documentation, large datasets, or extensive examples. There's no context penalty for bundled content that isn't used.³

A tabela medida no começo deste capítulo é essa afirmação verificada contra cinco skills que ninguém escreveu para este artigo. Duas linhas merecem ser lidas uma contra a outra.

next-best-practices tem um corpo de 966 tokens que aponta para dezenove arquivos com 19.374 tokens. Peça para corrigir um erro de hidratação e o agent lê o corpo mais hydration-error.md: 1.409 tokens de 20.340, um fator de quatorze, e os outros dezoito arquivos nunca são abertos.

next-cache-components tem um corpo de 2.334 tokens e nenhum arquivo empacotado. É uma skill válida e bem escrita, e não tem nível 3 a revelar. Esse é o limite honesto da técnica: progressive disclosure só economiza se houver algo a adiar. Uma skill cujo conhecimento não se decompõe paga o corpo inteiro na ativação, e a única alavanca restante é não ativá-la.

O nível 1 é uma decisão de roteamento tomada a partir de uma frase. Nada mais sobre uma skill influencia se ela será aberta — não a qualidade do corpo, não os exemplos, não os scripts. Portanto, a descrição não é documentação. Ela é a superfície de consulta, e pode estar errada.

A especificação diz isso na forma de um bom exemplo e de um ruim, e o ruim tem quatro palavras: description: Helps with PDFs.¹ Vale medir em vez de aceitar.

Seis skills, cada uma com uma descrição plausível que diz o que faz e quando usar. Vinte e quatro solicitações, quatro por skill, formuladas como uma pessoa as formularia e sem nunca nomear a skill. O modelo vê as seis linhas no system prompt e deve responder com um nome ou com NONE. Greedy decoding, para que reproduza. Depois, as mesmas vinte e quatro solicitações com as mesmas seis skills, e as descrições reduzidas ao assunto cru.

rich   - sql-review: Review a SQL migration for locks, missing indexes and unsafe
         defaults before it runs on the production database. Use when someone adds
         or changes a migration, an index, or a table column.
thin   - sql-review: Helps with SQL.

rich   295 tokens of level 1 for six skills   18/24 correct = 75.0 %  [55.1, 88.0]
thin    81 tokens of level 1 for six skills   10/24 correct = 41.7 %  [24.5, 61.2]

paired: rich only 9, thin only 1, two-sided sign test p = 0.0215
answered NONE: rich 1 of 24, thin 9 of 24

Leia os intervalos primeiro, como o Capítulo 4 insistiu e o Capítulo 29 voltará a insistir: eles se sobrepõem, e vinte e quatro casos não conseguem ranquear dois sistemas apenas por seus agregados. A comparação pareada é o que decide, e é o instrumento do Capítulo 15: dos dez casos em que os dois braços discordaram, nove foram para as descrições ricas e um para as finas. Isso fica estabelecido no limiar usual.

Agora leia a última linha, que é o achado real. Com descrições finas, o modelo respondeu NONE em nove de vinte e quatro solicitações. Não a skill errada: nenhuma skill. Aqui estão quatro delas, literalmente:

"Check this migration before I run it against production."     -> release-notes
"Will this CREATE INDEX lock writes?"                          -> NONE
"Is this ALTER TABLE safe to deploy at peak traffic?"          -> NONE
"Is 'seamless and powerful' allowed in the app store listing?" -> next-best-practices

Uma skill sql-review perfeita estava instalada, com corpo, exemplos e checklist, e nunca foi aberta, três vezes seguidas, nas três perguntas para as quais foi escrita. Os níveis 2 e 3 são irrelevantes para uma skill que o nível 1 nunca alcança.

O custo de corrigir isso: 214 tokens, a diferença entre 295 e 81, espalhada por seis skills. É o achado do Capítulo 18 chegando pelo outro lado. Lá, mudar apenas a descrição de uma ferramenta levou a formatação de datas de 2 acertos em 24 para 24 em 24. Aqui, mudar apenas a descrição de uma skill leva a ativação de 10 em 24 para 18. Nos dois casos, a correção mais barata do sistema é uma frase, e nos dois casos a frase precisa nomear o gatilho e não só o assunto: não o que a coisa é, mas o que o usuário terá acabado de dizer quando ela se aplica.

Uma ressalva que este capítulo deve aos próprios padrões. Este é um modelo de meio bilhão de parâmetros, e um modelo de frontier roteia muito melhor do que 75%. Leia o mecanismo, não a magnitude: o sinal de roteamento tem uma frase de comprimento independentemente do modelo que o lê, e nenhum modelo consegue selecionar com base em informação que você não colocou nessa frase.

A segunda falha é o oposto da primeira. A skill é encontrada, os níveis estão corretamente separados, e o agent lê tudo mesmo assim.

vercel-react-best-practices é uma skill genuinamente bem construída. Seu corpo de 1.670 tokens é uma tabela de prioridade de oito categorias e uma referência rápida que nomeia 70 arquivos de regras, uma linha cada. As regras estão no disco ao lado dela: 70 arquivos, o menor com 132 tokens, mediana de 319, o maior com 1.052. Faça uma pergunta sobre barrel imports e o custo honesto é o corpo mais um arquivo — abaixo de 2.400 tokens contra um pacote de 53.670.

Então a última linha do corpo diz isto:

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`

AGENTS.md tem 26.362 tokens. É a concatenação dos 70 arquivos de regras: a soma deles é 25.784, e a diferença são os títulos entre eles. Então a skill oferece ao agent uma escolha entre ler uma regra mediana de 319 tokens e ler o mesmo conteúdo, todo ele, a oitenta e três vezes o preço — e oferece essa escolha em uma frase sem custo anexado e sem condição sobre quando aceitá-la.

Isso não é um bug e o arquivo não está errado; um documento compilado é genuinamente útil para uma pessoa, e para um agent que recebeu a tarefa de auditar um codebase inteiro. É um arquivo de nível 3 com convite de nível 2, e a lição se generaliza além desta skill: todo caminho para fora de um SKILL.md deve dizer quanto custa e quando vale a pena, porque o modelo não tem como saber que um nome de arquivo é oitenta e três vezes mais caro do que o nome de arquivo acima dele.

A mesma pasta traz uma lição menor sobre desatualização. O corpo diz “70 regras em 8 categorias” e lista 70; o diretório rules/ contém 72 arquivos, dos quais dois são scaffolding (_template.md e _sections.md); e o sidecar metadata.json diz “40+ regras”. Três contagens do mesmo conjunto em uma pasta, uma delas correta, uma aritmética e uma remanescente de uma versão anterior. Uma skill é um documento, e documentos apodrecem exatamente como um comentário de código que se afastou do código ao lado dele — com a diferença de que este é lido por uma máquina que não vai franzir a testa.

A especificação aberta define seis campos de frontmatter. A implementação de referência, Claude Code, aceita vinte.² Vale conhecer cinco grupos pelo nome, porque é neles que o formato deixa de ser apenas um documento:

Argumentos (arguments, argument-hint) permitem que uma pessoa passe valores que são substituídos no corpo, o que torna uma skill utilizável como comando de barra. Escopo (paths) limita a ativação a arquivos que correspondem a um glob. E injeção dinâmica de context é o que muda o modelo mental: uma linha da forma !`git diff HEAD` roda antes de o corpo ser enviado, e sua saída é substituída no texto. O documento é um template, e parte dele é computada no momento da leitura.

Agora a armadilha, e ela é declarada na mesma documentação: fora do Claude Code — no produto web, pela Skills API, no empacotamento — somente os seis campos especificados são permitidos, e qualquer outro campo é um erro fatal no upload.² Então uma skill que funciona perfeitamente em um produto falha ao ser instalada em outro do mesmo fornecedor, e falha no frontmatter, não em algo que você poderia testar lendo a prosa. Se você pretende que uma skill seja portátil, os seis campos são o orçamento inteiro. Se não pretende, diga isso em compatibility, que existe exatamente para isso.

Quatro coisas são confundidas entre si o tempo todo, e a confusão não é pedantismo de vocabulário: escolher errado custa dinheiro em todo turno, ou custa uma garantia que você achava ter.

As duas linhas em negrito são a distinção inteira. Uma skill é lida; uma ferramenta é invocada. Uma skill é prosa que chega à context window e compete por attention com todo o resto ali; o modelo pode segui-la, interpretá-la errado ou ignorá-la, e nada no sistema percebe. Uma ferramenta é uma chamada que sai completamente das mãos do modelo: seu código recebe argumentos, valida, verifica permissões e decide. O Capítulo 18 colocou isso como o modelo propondo e seu código dispondo, e essa divisão é exatamente o que uma skill não tem.

Então, seis casos reais, resolvidos:

A história é curta, excepcionalmente bem datada, e é a parte que quase ninguém conta.

Agent Skills foram publicadas em 16 de outubro de 2025 como recurso de um fornecedor, definidas naquele anúncio como “organized folders of instructions, scripts, and resources that agents can discover and load dynamically to perform better at specific tasks”, com os três níveis descritos por uma analogia que vale guardar: “like a well-organized manual that starts with a table of contents, then specific chapters, and finally a detailed appendix”.⁴

Em 18 de dezembro de 2025, a mesma página foi atualizada para anunciar o formato como um padrão aberto, com especificação própria em agentskills.io, governança aberta a contribuições e um validador de referência.³ Lido em 7 de setembro de 2026, o showcase de clientes do padrão lista quarenta e seis produtos — editores, terminais, plataformas cloud e runtimes mobile, incluindo os coding agents first-party da Anthropic, OpenAI, Google e Mistral — cada um linkando sua própria documentação de configuração.¹

A convergência com MCP está sendo feita em aberto, com números que você pode verificar:

A parte interessante é o fechamento, não as propostas. A SEP-2076 pedia uma quarta primitiva ao lado de tools, resources e prompts. O working group que se formou a partir dela decidiu que a resposta era não: skills pegam carona na primitiva de recursos que já existe, como uma extensão opt-in.⁵ O Capítulo 26 mediu o mesmo instinto no changelog do próprio protocolo, onde sampling, roots e logging foram depreciados em vez de mantidos. Um órgão de padrões que remove uma proposta que ele mesmo criou está se comportando bem, e o motivo para contar esta história com os números à frente é que os resumos que você vai ler em outros lugares ainda descrevem skills como uma primitiva MCP.

Agora você consegue escrever um SKILL.md, dividi-lo em três níveis que se pagam, ler o frontmatter da skill de outra pessoa e saber quais campos não vão sobreviver ao upload em outro lugar, e responder à pergunta em torno da qual o capítulo inteiro foi construído — system prompt, skill, ferramenta ou servidor — com uma razão em vez de um hábito.

O que você não consegue fazer é dizer se a sua funciona.

Toda afirmação importante neste capítulo foi uma medição, e a que mais importou foi uma acurácia: 18 de 24 contra 10 de 24, com um intervalo em cada uma e um teste pareado entre elas, porque dois agregados que se sobrepõem não decidem nada. Esse instrumento foi emprestado. A descrição de uma skill é uma chave de roteamento, seu corpo é um procedimento que o modelo pode ou não seguir, e ambas são propriedades que você só consegue descobrir rodando a coisa muitas vezes e pontuando o que voltou — ou seja, um conjunto golden, um avaliador que você escreveu antes da execução, e a métrica que pergunta se funcionou todas as vezes, não pelo menos uma vez.

O Capítulo 29 é isso, e começa com o número de que o método deste capítulo depende: um agent que acerta sete em dez parece 70%, e seu pass^10 — a chance de acertar todos os dez — é zero. Ele também mede três avaliadores nos mesmos duzentos transcripts e obtém 0%, 13% e 26% sem regenerar um único token. Antes de confiar na frase que você acabou de escrever em um description, você precisa do instrumento que consegue dizer que ela é pior do que a que você substituiu.

Toda contagem de tokens neste capítulo foi produzida localmente com tiktoken 0.14.0 e a encoding o200k_base, em 7 de setembro de 2026: sobre as cinco skills de terceiros listadas no início deste capítulo, e sobre a skill release-notes escrita para este capítulo, cujo texto completo é reproduzido acima em parte. O nível 1 é medido como a linha única - name: description que um host renderiza no system prompt; o nível 2 é o corpo de SKILL.md após o frontmatter; o nível 3 é todo outro arquivo na pasta. Os custos usam as tarifas medidas do Capítulo 16 para gpt-5.6-terra, $2,00 por milhão de input tokens e $0,20 por milhão de input tokens em cache, aplicadas a essas contagens — são aritmética sobre tokens medidos, não observações de uma fatura real. Nenhuma API paga foi chamada para escrever este capítulo.

O experimento de ativação rodou Qwen/Qwen2.5-0.5B-Instruct em half precision em uma GPU de consumidor, greedy decoding, 24 solicitações sobre seis skills, duas vezes — uma com descrições que declaram o que a skill faz e quando se aplica, outra com as descrições reduzidas a um assunto cru no estilo do “poor example” da própria especificação. Os intervalos são Wilson a 95%; a comparação pareada é um teste exato de sinais bicaudal sobre os dez casos discordantes; o intervalo de Wilson é do Capítulo 4 e o teste exato pareado de sinais é do Capítulo 15, ambos reutilizados sem alteração. Leia as magnitudes como propriedade de um modelo muito pequeno e o método como transferível.

As cinco skills medidas aqui são pacotes de terceiros, não escritos para este capítulo: next-best-practices e next-cache-components de vercel-labs/next-skills, e vercel-composition-patterns, vercel-react-best-practices e vercel-react-native-skills de vercel-labs/agent-skills. Suas contagens internas — 70 arquivos de regras, AGENTS.md com 26.362 tokens, metadata.json datado de janeiro de 2026 e afirmando “40+ rules” — foram lidas dos arquivos no disco em 7 de setembro de 2026 e são propriedades dessa versão publicada, não críticas a seus autores: cada uma delas é o tipo de drift que aparece em qualquer árvore de documentação editada com mais frequência do que é contada.