Agent Skills e SKILL.md: divulgação progressiva, medida

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

Uma skill é um ficheiro Markdown. Não um ficheiro que configura um programa, não um ficheiro que um programa compila: um documento que o modelo lê, da mesma forma que lê a mensagem que escreveu. Dar uma linguagem de programação a este capítulo significaria não ter compreendido o formato, e esse mal-entendido é o mais comum sobre skills. Tudo abaixo é Markdown e YAML, mais um pequeno script de shell que existe precisamente para mostrar onde o código deve e não deve ficar dentro de uma skill.

Eis uma instrução real: como uma empresa escreve as suas notas de lançamento. É um procedimento, não uma preferência — tem um conjunto ordenado de passos, uma taxonomia, uma voz, um template e um script que recolhe a matéria-prima.

Coloque tudo isto no system prompt, como a maioria das equipas faz, e a aritmética do Capítulo 16 assume o controlo. Um system prompt é um prefixo, e um prefixo é pago em cada 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 omitisse seria publicidade. O prompt caching fecha quase toda a diferença de dinheiro. Um system prompt é estável e vem primeiro, o que faz dele 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 caching torna um prefixo permanente mais barato. Não o torna mais pequeno.

No turno 40, a versão com system prompt ainda tem 1.716 tokens de política de notas de lançamento sentados na janela durante uma conversa sobre uma coisa completamente diferente, a competir por aquilo a que o Capítulo 24 chamou o orçamento de attention do modelo. A versão com skill tem 46. Faça cache da coisa errada e comprou um desconto numa 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 ficheiros 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 suficiente para ser apresentada na íntegra:

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.¹ Mais quatro são opcionais e não há outros definidos:

Eis a skill de notas de lançamento, 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 é. Não é a política — é uma tabela de conteúdos com uma ordem de operações. A política vive em três ficheiros que ele nomeia e não inclui. E o primeiro passo entrega trabalho a um script, porque o código de um script nunca entra na context window: só o seu output entra.²

O modelo de carregamento tem um nome e três etapas. A especificação apresenta-as com um orçamento de tokens associado:¹

1. Metadados, cerca de 100 tokens: name e description, carregados no arranque para cada skill instalada.
2. Instruções, recomendadas abaixo de 5.000 tokens: o corpo de SKILL.md, carregado quando a skill é ativada.
3. Recursos, conforme necessário: ficheiros 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 acedido.³ A frase que resume o capítulo inteiro também está lá:

Os ficheiros não consomem context até serem acedidos, pelo que as Skills podem incluir documentação de API abrangente, grandes conjuntos de dados ou exemplos extensos. Não há penalização de context por conteúdo empacotado que não é usado.³

A tabela medida no início 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 dezanove ficheiros com 19.374 tokens. Peça-lhe para corrigir um erro de hidratação e o agent lê o corpo mais hydration-error.md: 1.409 tokens em 20.340, um fator de catorze, e os outros dezoito ficheiros nunca são abertos.

next-cache-components tem um corpo de 2.334 tokens e nenhum ficheiro empacotado. É uma skill válida e bem escrita, e não tem nível 3 para revelar. Esse é o limite honesto da técnica: a divulgação progressiva só poupa 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 que resta é não a ativar.

O nível 1 é uma decisão de routing feita a partir de uma frase. Nada mais sobre uma skill influencia se alguma vez é aberta — nem a qualidade do corpo, nem os exemplos, nem os scripts. Portanto, a descrição não é documentação. É a superfície de consulta, e pode estar errada.

A especificação di-lo sob a forma de um bom exemplo e de um mau exemplo, e o mau exemplo tem quatro palavras: description: Helps with PDFs.¹ Vale a pena medir isto em vez de o aceitar.

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

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 primeiro os intervalos, como o Capítulo 4 insistiu e o Capítulo 29 voltará a insistir: sobrepõem-se, e vinte e quatro casos não conseguem ordenar dois sistemas apenas pelos seus agregados. A comparação em pares é 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 habitual.

Agora leia a última linha, que é a descoberta real. Com descrições finas, o modelo respondeu NONE em nove de vinte e quatro pedidos. Não a skill errada: nenhuma skill. Eis quatro deles, verbatim:

"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 a corrigir: 214 tokens, a diferença entre 295 e 81, distribuída por seis skills. É a conclusão do Capítulo 18 a chegar pelo outro lado. Aí, alterar apenas a descrição de uma ferramenta levou a formatação de datas de 2 corretas em 24 para 24 em 24. Aqui, alterar apenas a descrição de uma skill leva a ativação de 10 em 24 para 18. Em ambos os casos, a correção mais barata do sistema é uma frase, e em ambos os casos a frase tem de nomear o trigger e não apenas o assunto: não o que a coisa é, mas o que o utilizador terá acabado de dizer quando ela se aplica.

Uma ressalva que este capítulo deve aos seus próprios padrões. Este é um modelo com meio milhar de milhão de parâmetros, e um modelo de fronteira faz routing muito melhor do que 75 %. Leia o mecanismo, não a magnitude: o sinal de routing tem uma frase, seja qual for o modelo que a lê, e nenhum modelo consegue selecionar com base em informação que 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 na mesma.

vercel-react-best-practices é uma skill genuinamente bem construída. O seu corpo de 1.670 tokens é uma tabela de prioridades com oito categorias e uma referência rápida que nomeia 70 ficheiros de regras, uma linha cada. As regras estão em disco ao lado: 70 ficheiros, o mais pequeno com 132 tokens, mediana 319, o maior com 1.052. Faça-lhe uma pergunta sobre barrel imports e o custo honesto é o corpo mais um ficheiro — menos de 2.400 tokens contra um pacote de 53.670.

Depois, 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 ficheiros de regras: a soma é 25.784, e a diferença são os títulos entre eles. Portanto, a skill oferece ao agent a escolha entre ler uma regra mediana com 319 tokens e ler o mesmo conteúdo, todo ele, a oitenta e três vezes o preço — e oferece essa escolha numa frase sem custo associado e sem condição sobre quando a tomar.

Isso não é um bug e o ficheiro não está errado; um documento compilado é genuinamente útil para uma pessoa, e para um agent a quem foi pedido que auditasse uma codebase inteira. É um ficheiro de nível 3 com um convite de nível 2, e a lição generaliza-se para além desta skill: todos os caminhos para fora de um SKILL.md devem dizer quanto custam e quando valem a pena, porque o modelo não tem forma de saber que um nome de ficheiro é oitenta e três vezes mais caro do que o nome de ficheiro acima dele.

A mesma pasta traz uma lição menor sobre obsolescência. O corpo diz "70 rules across 8 categories" e lista 70; o diretório rules/ contém 72 ficheiros, dos quais dois são scaffolding (_template.md e _sections.md); e o sidecar metadata.json diz "40+ rules". Três contagens do mesmo conjunto numa pasta, uma certa, uma aritmética e uma deixada de uma versão anterior. Uma skill é um documento, e os documentos apodrecem exatamente como um comentário de código que se desviou do código ao seu lado — com a diferença de que este é lido por uma máquina que não vai franzir o sobrolho.

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

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

Agora a armadilha, e está enunciada na mesma documentação: fora do Claude Code — no produto web, através da Skills API, no packaging — só os seis campos especificados são permitidos, e qualquer outro campo é um erro rígido no upload.² Portanto, uma skill que funciona perfeitamente num produto falha ao instalar noutro do mesmo fornecedor, e falha no frontmatter em vez de falhar em algo que pudesse testar lendo a prosa. Se pretende que uma skill seja portável, os seis campos são todo o orçamento. Se não pretende, diga-o em compatibility, que existe exatamente para isto.

Quatro coisas são constantemente confundidas, e a confusão não é pedantismo vocabular: escolher mal custa dinheiro em cada turno, ou custa-lhe uma garantia que pensava ter.

As duas linhas a negrito são toda a distinção. Uma skill é lida; uma ferramenta é invocada. Uma skill é prosa que chega à context window e compete por attention com tudo o resto que lá está; o modelo pode segui-la, lê-la mal ou ignorá-la, e nada no sistema repara. Uma ferramenta é uma chamada que sai inteiramente das mãos do modelo: o seu código recebe argumentos, valida-os, verifica permissões e decide. O Capítulo 18 formulou-o como o modelo a propor e o seu código a dispor, e essa divisão é exatamente o que uma skill não tem.

Portanto, seis casos reais, resolvidos:

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

Agent Skills foram publicadas em 16 de outubro de 2025 como funcionalidade de um fornecedor, definidas nesse anúncio como "pastas organizadas de instruções, scripts e recursos que os agents conseguem descobrir e carregar dinamicamente para desempenhar melhor tarefas específicas", com os três níveis descritos através de uma analogia que vale a pena guardar: "como um manual bem organizado que começa com uma tabela de conteúdos, depois capítulos específicos e, por fim, um apêndice detalhado".⁴

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

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

A parte interessante é o encerramento, não as propostas. A SEP-2076 pedia uma quarta primitive ao lado de ferramentas, recursos e prompts. O working group que dela nasceu decidiu que a resposta era não: as skills viajam na primitive 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 deprecated em vez de mantidos. Um organismo de standards que remove uma proposta da sua própria autoria está a comportar-se bem, e a razão para contar esta história com os números à frente é que os resumos que vai ler noutros sítios ainda descrevem skills como uma primitive de MCP.

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

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

Todas as afirmações importantes deste capítulo foram medições, e a mais importante foi uma accuracy: 18 em 24 contra 10 em 24, com um intervalo em cada uma e um teste emparelhado 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 routing, o seu corpo é um procedimento que o modelo pode ou não seguir, e ambas são propriedades que só consegue descobrir executando a coisa muitas vezes e pontuando o que voltou — o que é um golden set, um grader que escreveu antes da execução, e a métrica que pergunta se funcionou todas as vezes em vez de pelo menos uma.

O Capítulo 29 é isso, e abre com o número de que o método deste capítulo depende: um agent que tem sucesso sete vezes em dez parece 70 %, e o seu pass^10 — a probabilidade de ter sucesso nas dez — é zero. Também mede três graders nas mesmas duzentas transcrições e obtém 0 %, 13 % e 26 % sem regenerar um único token. Antes de confiar na frase que acabou de escrever num description, precisa do instrumento que lhe consegue dizer que ela é pior do que a que substituiu.

Todas as contagens de tokens neste capítulo foram produzidas localmente com tiktoken 0.14.0 e a codificação 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 é parcialmente reproduzido acima. 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 depois do frontmatter; o nível 3 é qualquer outro ficheiro na pasta. Os custos usam as tarifas medidas no 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.

A experiência de ativação executou Qwen/Qwen2.5-0.5B-Instruct em meia precisão numa GPU de consumo, greedy decoding, 24 pedidos sobre seis skills, duas vezes — uma com descrições que indicam o que a skill faz e quando se aplica, outra com as descrições reduzidas a um tema nu no estilo do "mau exemplo" da própria especificação. Os intervalos são Wilson a 95 %; a comparação em pares é um teste exato dos sinais bilateral sobre os dez casos discordantes; o intervalo de Wilson é o do Capítulo 4 e o teste exato dos sinais emparelhado é o do Capítulo 15, ambos reutilizados sem alterações. 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. As suas contagens internas — 70 ficheiros de regras, AGENTS.md com 26.362 tokens, metadata.json datado de janeiro de 2026 e a afirmar "40+ rules" — foram lidas dos ficheiros em disco em 7 de setembro de 2026 e são propriedades dessa versão publicada, não críticas aos seus autores: cada uma delas é o tipo de drift que aparece em qualquer árvore de documentação que é editada mais vezes do que é contada.