Agent Skills: ensine o procedimento, não repita o prompt

Existe um padrão que quase toda empresa que usa IA repete, e que ninguém nomeia: alguém tem um prompt de quarenta linhas salvo num documento, e cola esse prompt toda semana.

Às vezes é o formato do relatório de fechamento. Às vezes é o tom das respostas de suporte. Às vezes é a estrutura da proposta comercial. Funciona — e então o texto começa a existir em cinco versões ligeiramente diferentes, na área de transferência de cinco pessoas, e ninguém sabe qual é a atual.

Agent Skills é o nome da solução para esse problema específico. E o que a torna interessante não é a ideia de guardar instruções — é como elas são carregadas.

A tese em uma frase: uma skill transforma um prompt repetido num procedimento versionado que a ferramenta carrega sozinha quando o assunto aparece — e, porque o formato é aberto, o procedimento não fica preso à ferramenta onde você o escreveu.

O que é uma skill, na prática

Uma Agent Skill é uma pasta. Dentro dela, obrigatoriamente, um arquivo de texto chamado SKILL.md, escrito em Markdown comum — nada de linguagem de programação.

Esse arquivo tem duas partes:

• Um cabeçalho curto com o nome e uma descrição. A descrição não é decorativa: é ela que diz quando aquele procedimento se aplica. "Use ao gerar a proposta comercial padrão."
• O procedimento completo, abaixo. Passos, formato de saída, o que nunca fazer, exemplos.

Opcionalmente a pasta leva mais coisas: um modelo de documento, uma planilha de referência, um script que executa alguma etapa de forma determinística. Isso importa mais do que parece — significa que a skill pode carregar o seu template real, não uma descrição dele.

Se você já escreveu um procedimento operacional interno, você já sabe fazer isso. A diferença é que o leitor agora é um modelo, e o gatilho de uso precisa estar explícito no cabeçalho.

Por que Agent Skills não é só um prompt salvo

Aqui está o mecanismo que separa uma skill de um documento cheio de prompts, e é a parte que vale entender.

Só a descrição fica no contexto do modelo. Uma linha, sempre visível. O corpo do arquivo — que pode ter dez páginas — não é carregado até que a tarefa pareça pedir por ele. Quando pede, o arquivo inteiro entra.

Esse comportamento tem um nome na documentação, progressive disclosure, e três consequências práticas:

• Você pode escrever um procedimento longo sem culpa. Ele não pesa nas outras conversas, porque não está lá.
• Você pode ter muitas skills ao mesmo tempo. Só as descrições ficam residentes.
• Você para de depender de alguém lembrar. Quem decide carregar o procedimento é a ferramenta, ao reconhecer o gatilho — não a pessoa, ao lembrar de abrir o documento certo.

O terceiro é o que muda a operação. Prompt salvo num documento é conhecimento disponível; skill é conhecimento aplicado por padrão. Entre os dois há a distância inteira entre ter um POP escrito e ter um POP seguido.

E há o item mais chato e mais valioso: skills têm versão. O procedimento existe num lugar, com histórico. Quando ele muda, muda para todo mundo — em vez de continuar circulando em cinco variantes que ninguém consegue reconciliar.

Prompt, skill ou automação?

Três coisas diferentes que se confundem. A régua:

A coluna do meio é a que estava faltando no vocabulário da maioria das empresas. Tinha "escrever um prompt melhor" e tinha "automatizar" — e uma quantidade enorme de trabalho repetitivo com julgamento no meio não cabe em nenhuma das duas.

Para decidir o que sequer merece ser padronizado, o caminho é anterior à ferramenta: mapear o processo e saber o que não automatizar. Skill de um processo que ninguém entende é o caos com versionamento.

O formato é aberto — e essa história já se repetiu

Aqui está o fato que muda a análise de risco, e que quase nenhum conteúdo em português menciona: em dezembro de 2025 o formato foi publicado como padrão aberto, com a especificação em agentskills.io.

O efeito é concreto: mais de 20 ferramentas de agente leem o mesmo arquivo — entre elas Cursor, Codex CLI e OpenCode. A mesma pasta de procedimento funciona nelas sem reescrita.

Se isso soa familiar, é porque este blog já contou essa história duas vezes. O MCP nasceu dentro de um fornecedor e foi doado a uma fundação neutra, como está em o que é MCP. E as APIs antifraude das operadoras seguiram exatamente o mesmo caminho, em o que é Open Gateway.

As Agent Skills fecham o trio. Três vezes o mesmo arco: especificação primeiro, adoção cruzada depois, abertura no fim. Vale aprender a reconhecê-lo, porque ele muda a conta de uma decisão: escrever procedimento em formato aberto é investimento que sobrevive à troca de ferramenta. Escrever no formato proprietário de uma plataforma é aluguel.

Sendo justo com o ceticismo: padrão aberto publicado por um fornecedor único ainda é um fornecedor definindo o padrão. A diferença entre isso e uma fundação neutra é real. Mas 20 implementações independentes é evidência melhor que qualquer promessa de governança.

Onde isso já funciona hoje

Duas categorias, e a primeira serve para testar sem escrever nada:

Skills prontas. Existem skills mantidas pela própria Anthropic para gerar arquivos de escritório — .pptx, .xlsx, .docx, .pdf. Não são exemplos didáticos: é o caminho pelo qual uma IA entrega uma apresentação ou uma planilha formatada de verdade em vez de descrever uma. Se você quer entender o conceito em vinte minutos de uso, comece por elas.

Agent Skills suas. As que você escreve para os seus procedimentos. É aqui que o valor está, e é aqui que quase ninguém chegou ainda.

O suporte a Agent Skills está espalhado pelas superfícies onde a IA já é usada: os aplicativos de conversa, as ferramentas de linha de comando para quem programa, e a API para quem constrói produto. Se você quiser a versão formal e curta, o catálogo gratuito tem uma trilha de 30 minutos só sobre isso — está mapeada em cursos gratuitos de IA da Anthropic.

Como eu escreveria a primeira

Sem projeto, numa tarde:

1. Escolha o procedimento que você já repetiu três vezes. Não o mais importante — o mais repetido. Provavelmente é um formato de relatório, uma estrutura de proposta ou um padrão de resposta.
2. Junte as versões que existem. Se há cinco variantes circulando, a primeira tarefa não é escrever: é decidir qual está certa. Esse trabalho é o valor real, e ele acontece antes da ferramenta.
3. Escreva o gatilho antes do conteúdo. "Use quando…" é a linha mais importante do arquivo. Gatilho vago é skill que nunca carrega — ou que carrega no momento errado.
4. Inclua o que não fazer. Procedimento real tem limite: "não invente número que não esteja na planilha anexa". Isso conversa direto com alucinação de IA — a skill é um bom lugar para fixar a regra de conferência.
5. Anexe o template de verdade. Se existe um arquivo modelo, ele vai junto. É a diferença entre "siga o nosso padrão" e ter o padrão em mãos.
6. Use por duas semanas antes de escrever a segunda. A primeira skill sempre está errada em algum detalhe que só o uso revela.

Uma ressalva de governança: skill é um documento que orienta o que a IA faz com dados da empresa, então ela pertence ao mesmo perímetro da política de uso de IA — inclusive na parte de não colar dado sensível dentro do arquivo.

O que não vira skill

Curto, porque errar aqui gera trabalho inútil. Não vale virar Agent Skills:

• O que você fez uma vez. Prompt resolve.
• O que ainda muda toda semana. Padronizar antes de estabilizar congela a versão errada. Espere.
• O que não tem julgamento nenhum. Se a regra é totalmente determinística e o volume é alto, isso é automação — e provavelmente pede uma ligação com os seus sistemas, o assunto de como conectar IA aos dados da empresa.
• O que só existe na cabeça de uma pessoa. Aí o problema não é de ferramenta. Escrever a skill vai forçar a explicitar a regra, o que é ótimo — mas essa é uma conversa entre pessoas, não uma tarefa técnica.

O ponto que fica

Agent Skills não é tecnologia difícil. É um arquivo de texto numa pasta, com uma linha dizendo quando usá-lo.

O que ela muda é mais mundano e mais valioso que isso: o procedimento deixa de morar na área de transferência de alguém. Ele passa a ter um lugar, uma versão e um gatilho — e a próxima pessoa da equipe herda o padrão em vez de reinventá-lo.

Se você já treinou a equipe em como usar IA no trabalho e ainda vê cada um fazendo do seu jeito, o que falta provavelmente não é mais treinamento. É o procedimento estar escrito num lugar que a ferramenta consegue ler.

E como o formato é aberto, esse trabalho não é aposta em plataforma. É escrever, uma vez, o jeito como a sua empresa faz as coisas.