Claude Skills explicado: os três níveis de divulgação progressiva

Um Claude Skill é, fisicamente, uma pasta. Não um serviço hospedado, não um binário, não um bloco de texto que você cola no início de uma conversa — um diretório contendo um arquivo SKILL.md e tudo o mais que a tarefa exigir. Quase tudo o que há de interessante nos Skills decorre dessa única decisão, porque uma pasta é algo que um agente pode abrir seletivamente. Um prompt não pode ser aberto seletivamente. Ele ou está na conversa, ou não está.

A documentação da Anthropic descreve o arranjo como organizado à maneira de um guia de onboarding que você criaria para um novo membro da equipe, e a analogia vai mais longe do que parece à primeira vista. Ninguém lê um guia de onboarding de capa a capa antes de começar a trabalhar. A pessoa lê a página que corresponde à pergunta que tem diante de si e confia que o restante continua lá quando precisar. Uma skill é construída sobre a mesma aposta: a de que a maior parte de um procedimento pode permanecer em disco na maior parte do tempo.

Sistema de arquivos primeiro, capacidade depois.

Claude opera em uma máquina virtual com acesso ao sistema de arquivos. Essa é a precondição para que uma skill seja um diretório em vez de uma entrada de configuração, porque permite ao agente listar uma pasta, ler um arquivo e seguir uma referência para outro arquivo usando as mesmas operações que uma pessoa usaria. Dentro disso, uma skill empacota instruções, metadados e recursos opcionais, como scripts e modelos.

O resultado é uma capacidade maior do que qualquer arquivo individual na pasta. As instruções dizem como realizar a tarefa. Um script incluído pode executar parte dela sem ser descrito em prosa. Um documento de referência pode conter material que é consultado em vez de memorizado. O que transforma essas três coisas em um sistema, e não em uma pilha, é a ordem em que elas se tornam visíveis, que é a parte que a Anthropic chama de divulgação progressiva — carregar informações em etapas conforme a necessidade, em vez de consumir contexto de antemão.

Nível 1: os dois campos que são sempre carregados

Toda skill começa com um frontmatter YAML contendo um nome e uma descrição. O Claude carrega esses metadados na inicialização e os inclui no prompt do sistema. É a única parte da skill presente antes de alguém pedir qualquer coisa e, até que uma skill seja acionada, apenas o nome e a descrição dela ocupam contexto.

A descrição desempenha três funções ao mesmo tempo, e separá-las explica por que tantas skills são silenciosamente ignoradas. Ela é um rótulo, que diz qual é o nome da coisa. É uma entrada de índice, o texto com o qual uma solicitação é comparada quando o Claude decide se a skill é relevante. E é uma declaração de escopo, e é por isso que a orientação da Anthropic é que ela deve dizer tanto o que a skill faz quanto quando usá-la. Uma descrição que só dá conta da primeira não oferece nada ao mecanismo de correspondência para comparar.

Considere duas versões da mesma habilidade. Uma é descrita como preenchimento e validação de formulários PDF, para ser usada quando uma solicitação envolve preencher ou verificar um formulário PDF. A outra é descrita como ajuda com documentos. A primeira nomeia uma ação e uma situação; a segunda não nomeia nenhuma das duas. Uma habilidade cuja descrição não nomeia nenhuma das duas ficará no disco sem ser lida enquanto o agente faz a tarefa pelo caminho mais longo — não porque a habilidade falhou, mas porque nunca foi encontrada.

Nível 2: o corpo, leia quando a descrição corresponder

Quando uma solicitação corresponde à descrição, o segundo nível se abre: o corpo do SKILL.md. Esse é o procedimento — fluxos de trabalho, boas práticas, orientações — e é escrito para um agente que já decidiu que esta habilidade é a ferramenta certa para a tarefa. É onde uma equipe registra as etapas que, de outra forma, repetiria em cada conversa, e é onde ficam as referências para material mais aprofundado.

A ordem importa aqui tanto quanto no nível 1. O corpo não é carregado na inicialização, nem é carregado por precaução. Ele chega depois que uma decisão foi tomada, o que significa que a decisão precisa ser possível de tomar apenas a partir do nível 1. Uma habilidade com uma descrição vaga não tem como se recuperar no nível 2, porque o nível 2 nunca é lido.

Nível 3: arquivos que abrem porque algo apontou para eles

O terceiro nível é o resto da pasta: ficheiros adicionais referenciados a partir do SKILL.md. O exemplo da Anthropic é um FORMS.md que contém orientações avançadas sobre o preenchimento de formulários, mantido fora das instruções principais para que estas se mantenham curtas e os detalhes só estejam disponíveis quando uma tarefa o exigir. Os scripts e os modelos também pertencem a este nível.

O efeito estrutural é que uma skill pode carregar uma grande quantidade de material sem carregá-lo todo de uma vez. Uma pasta pode conter um arquivo principal de instruções, uma referência detalhada, um conjunto de templates e um script, e uma determinada tarefa pode tocar em apenas um deles. Tudo aquilo para o que nada aponta permanece no disco, e o disco não é o recurso escasso em um agente. O contexto é.

É também aí que o formato eleva o teto com que os prompts se deparam. Um prompt precisa ser curto o suficiente para valer a pena colar. O material incluído de uma skill é limitado pelo que um diretório pode armazenar, porque a única parte que chega ao modelo é a parte que a tarefa realmente tocou.

Por que a ordem é o design, não um detalhe

Três consequências decorrem disso e, em conjunto, são a razão pela qual vale a pena compreender isto em vez de apenas saber.

• O contexto é um orçamento, e conteúdo sempre carregado é um custo fixo. Tudo o que está num prompt de sistema é pago em cada pedido, incluindo pedidos que nada têm a ver com essa competência. A divulgação progressiva transforma um custo fixo num custo condicional: uma descrição sempre, instruções quando forem relevantes, referências quando forem referenciadas.

• A descrição é uma interface. É a única parte de uma habilidade que tem garantia de ser vista, portanto é onde o autor precisa pensar no acionamento, e não apenas no conteúdo.

• Uma skill tem três velocidades de manutenção.Os metadados mudam quando a skill deve ser acionada de forma diferente, o corpo muda quando o fluxo de trabalho muda, e as referências mudam quando o material subjacente muda. Mantê-los separados evita que uma atualização de referência se transforme em uma reescrita das instruções.

O custo é a imagem espelhada do benefício. Toda fronteira de nível é um ponto em que o modelo precisa tomar uma decisão corretamente. Uma descrição demasiado estreita faz com que a habilidade nunca seja acionada e a pasta seja um peso morto. Uma demasiado ampla faz com que ela seja acionada em trabalhos para os quais não foi criada, e suas instruções se tornam um ônus para tarefas não relacionadas. A divulgação progressiva faz com que a descrição seja estrutural de uma forma que um prompt longo, sempre presente, nunca é.

O que a Anthropic já oferece e de onde vêm suas próprias habilidades

A Anthropic oferece Skills pré-construídas para PowerPoint, Excel, Word e PDF — apresentações, planilhas, documentos e saída em PDF formatado. Elas estão disponíveis no claude.ai, na Claude API, na Claude Platform on AWS e no Microsoft Foundry, com a ressalva de que, no Foundry, exigem uma implantação Hosted on Anthropic.

Esses são a maneira mais rápida de ver o mecanismo em vez de ler sobre ele. A ordem de carregamento é idêntica à de qualquer coisa que você mesmo escreva; a diferença entre uma skill pré-construída e uma personalizada é quem criou a pasta, não como ela chega ao modelo.

Custom Skills podem ser criadas no Claude Code, enviadas por upload pela Claude API ou adicionadas nas configurações do claude.ai. Os benefícios declarados pela Anthropic para elas são os que você esperaria de qualquer coisa reutilizável: especializar o Claude para tarefas de domínio, criar orientações uma vez em vez de repeti-las e compor várias skills para trabalho de várias etapas. O último desses benefícios decorre mais diretamente da arquitetura, porque, se cada skill é uma pasta que se abre sob demanda, uma pilha de skills custa muito pouco até que o trabalho realmente precise delas.

Uma habilidade não é um prompt, nem um conector.

Três coisas são confundidas na conversa, e a ordem de carregamento torna as distinções fáceis de manter.

Um prompt é de nível de conversa. Ele está presente desde o primeiro turno, colore tudo naquela conversa e desaparece junto com a conversa. Uma skill é sob demanda: ela existe antes de a conversa começar, a maior parte dela nunca entra na conversa, e a parte que chega o faz porque uma descrição teve correspondência. Essa é a diferença entre dizer a um agente como se comportar e dar a ele algo que ele possa pegar.

Um conector tem a ver com alcance. Conectores são acesso a aplicativos, o que significa que determinam o que um agente pode acessar; uma habilidade determina como o agente deve fazer algo depois que consegue acessá-lo. Uma equipe pode ter excelentes conectores e ainda produzir documentos inconsistentes, porque acesso não é procedimento. Também pode ter excelentes habilidades e ainda não ver os dados, porque procedimento não é acesso.

A documentação da Anthropic trata Skills e o Model Context Protocol como camadas diferentes, e o mecanismo de três níveis mostra por que a separação é clara. A ordem de carregamento diz respeito a quando a informação chega, não de onde ela veio.

Onde a doação se encaixa, em um parágrafo

Em 22 de outubro de 2026, a Anthropic doou o padrão Agent Skills à Agentic AI Foundation, sob a Linux Foundation — o nome, o logotipo, a organização no GitHub e o domínio agentskills.io —, com engenheiros da Anthropic, do Google, da OpenAI e de outras empresas mantendo-o como indivíduos. Nada disso altera o mecanismo acima. O formato de pasta, o frontmatter YAML, a ordem de carregamento e as habilidades de documento pré-construídas são exatamente como eram no dia anterior. O que mudou é quem é dono do nome, o que importa muito para a estabilidade de longo prazo de um padrão e não importa em nada para como você escreve uma habilidade hoje à tarde.

Ler uma skill antes de instalá-la

Se os três níveis são a arquitetura, eles também formam uma pequena lista de verificação para revisão. Leia a descrição primeiro, porque é ela que decide se qualquer outra coisa chega a acontecer: ela deve indicar o que a habilidade faz e quando deve ser usada, em palavras que uma solicitação provavelmente usaria. Leia o SKILL.md em segundo lugar, porque ele é o procedimento que o agente seguirá, e deve soar como instruções para um colega competente, e não como um resumo do que você espera que aconteça. Leia o que ele referencia em terceiro lugar. Depois, leia os scripts.

Esse último item não é paranoia. O formato permite que uma skill carregue instruções junto com recursos opcionais, e os recursos podem incluir código executável. Uma skill que você instala, portanto, não é apenas texto que molda uma conversa; é uma pasta de onde um agente capaz abrirá arquivos e agirá com base neles. O modelo nível a nível diz exatamente onde olhar, o que é mais do que a maioria das coisas instaladas oferece.

Vale explicitar um limite para leitores que chegam pelas nossas próprias páginas. O OrcaRouter roteia chamadas de modelo, e não hospedamos nenhum dos aplicativos da Anthropic nem suas superfícies de skill — uma skill é executada onde estiver o sistema de arquivos do agente, e essa não é a nossa camada. O que fazemos fica abaixo da escolha do modelo: mais de 200 modelos por trás de uma única chave compatível com OpenAI, preço de tabela do provedor repassado sem acréscimo e failover automático entre provedores quando um deles não está disponível. Uma skill decide como uma tarefa deve ser feita. Um roteador decide qual modelo a faz, e nenhuma das camadas deveria precisar saber muito sobre a outra.

A divulgação progressiva é honesta quanto à restrição que resolve. O contexto é finito, os procedimentos são longos e a maior parte de qualquer procedimento é irrelevante para a tarefa em questão. Um nome, um corpo e um conjunto de arquivos não é um design complicado; é o menor design que permite a um agente carregar uma grande quantidade de conhecimento mantendo apenas a parte de que precisa.

É por isso que a linha mais consequente em uma habilidade bem construída também é a mais curta. Todo o resto na pasta é uma biblioteca. A descrição é o catálogo de fichas e, quando o catálogo está errado, é como se a biblioteca nem existisse.