Técnica · Multiagentes · Contexto · Codificação
Agent Skills
Pastas com instruções que transformam um agente genérico em especialista — sem inchar o contexto.
- Fabricante
- Padrão aberto
- Preço
- Grátis
- Nível
- Intermediário
- min de leitura
- 11 min
- Atualizado
- 18 de ago. de 2026
- É
- Uma pasta com um arquivo SKILL.md que ensina a um agente como executar uma tarefa específica — carregada só quando a tarefa aparece.
- Use quando
- Quando existe um procedimento real e repetível, com regras próprias, que você hoje explica à mão toda vez que precisa dele.
- Evite quando
- Quando a instrução cabe em duas frases, quando o conhecimento muda todo dia, ou quando o que você precisa é acesso a um sistema — isso é MCP, não skill.
VereditoEscreva uma skill quando você já se pegou explicando o mesmo procedimento pela terceira vez — antes disso, um prompt resolve.
Todo mundo que usa um agente por algumas semanas passa pelo mesmo desconforto: você explica o mesmo procedimento de novo. Como a empresa formata um relatório de incidente. Quais campos são obrigatórios num contrato. Qual a convenção de commits do time. Você explica, o agente executa bem, a sessão acaba, e na semana seguinte você explica tudo outra vez.
A saída óbvia é colocar essas instruções no prompt de sistema. Funciona — até você ter trinta procedimentos. Aí todo pedido, inclusive "que horas são", carrega trinta procedimentos irrelevantes e você paga o preço disso em qualidade, por causa do context rot.
Agent Skills resolvem exatamente esse dilema.
Resposta direta: uma Agent Skill é uma pasta com um arquivo
SKILL.mdque ensina a um agente como executar uma tarefa específica. O agente enxerga apenas o nome e a descrição de cada skill; o conteúdo completo só entra no contexto quando a tarefa corresponde à descrição.
Divulgação progressiva: o mecanismo central
O conceito que faz tudo funcionar tem nome: progressive disclosure, divulgação progressiva. O agente carrega o conhecimento em três estágios, e cada estágio custa mais que o anterior.
- 01
Descoberta
ao iniciar, o agente lê só nome e descrição de cada skill. Custo: algumas dezenas de tokens por skill.
- 02
Ativação
quando a tarefa corresponde a uma descrição, ele lê o SKILL.md inteiro. Custo: centenas ou milhares de tokens, uma vez.
- 03
Execução
ele segue as instruções e, se precisar, abre arquivos de referência ou roda scripts da pasta. Custo: só o que foi aberto.
O efeito prático é que uma biblioteca de cinquenta skills custa quase nada quando nenhuma é usada. Você deixa de escolher entre "o agente sabe muita coisa" e "o contexto está limpo".
Tokens de contexto ocupados com 50 procedimentos disponíveis
- Tudo no prompt de sistema55 milcarregado em todo pedido, mesmo os irrelevantes
- Skills, nenhuma ativada3 milsó os nomes e descrições
- Skills, uma ativada5 mildescrições mais o conteúdo da skill usada
A anatomia de um SKILL.md
O formato é deliberadamente simples: um arquivo Markdown com um cabeçalho de metadados. O mínimo obrigatório é nome e descrição.
$ minha-skill/$ minha-skill/SKILL.md$ minha-skill/referencia/modelo-relatorio.md$ minha-skill/scripts/gerar.pyO corpo do arquivo é instrução em português claro: quando usar, o passo a passo, o que verificar antes de dizer que terminou. Não é código, é procedimento escrito para ser lido por alguém competente que nunca fez essa tarefa aqui.
A descrição é a parte mais importante
Esta é a lição que custa caro aprender. O conteúdo da skill define a qualidade da execução; a descrição define se ela vai ser executada.
Uma descrição vaga significa que a skill nunca ativa, ou ativa na hora errada. E uma skill que não ativa é o mesmo que uma skill que não existe.
Descrições que ativam
- Use quando o usuário pedir um relatório de incidente, post-mortem ou RCA
- Use ao criar ou revisar um contrato de prestação de serviço
- Use para qualificar um lead novo antes de passar para vendas
- Cite os termos que a pessoa realmente digita, incluindo sinônimos e gírias do time
Descrições que falham
- Ajuda com documentos
- Melhores práticas da empresa
- Ferramentas úteis para o time
- Descrições que descrevem a skill em vez de descrever o gatilho
A regra prática: escreva a descrição pensando na frase que a pessoa vai digitar, não no nome que você deu ao processo internamente.
Skill, prompt, subagente ou MCP?
Quatro mecanismos que se confundem porque todos "ensinam algo ao agente". Eles resolvem problemas diferentes.
| Mecanismo | O que é | Use quando |
|---|---|---|
| Prompt | Instrução na hora | A instrução é pontual e cabe em duas frases |
| Skill | Procedimento reutilizável carregado sob demanda | Existe um jeito certo de fazer, repetível, com regras próprias |
| Subagente | Sessão paralela com contexto isolado | A subtarefa exige ler muito para concluir pouco |
| MCP | Conexão com um sistema externo | O agente precisa ler ou escrever em uma ferramenta de verdade |
A confusão mais comum é entre skill e MCP, e a distinção é limpa: skill é saber, MCP é poder. Um agente com MCP do CRM consegue consultar o CRM; ele continua sem saber como a sua empresa decide se um lead está qualificado. Esse conhecimento é skill.
O que falta ao agente é conhecimento ou acesso?
Escreva uma skill
O procedimento existe na cabeça de alguém e precisa virar arquivo.
Conecte um MCP
Nenhuma instrução resolve a falta de permissão para ler o sistema.
Como escrever a primeira
O melhor candidato não é o processo mais importante da empresa. É o que você mais explicou nas últimas duas semanas.
- 01
Escolha o procedimento que você mais repete
se você explicou três vezes, ele merece existir como arquivo
- 02
Escreva como você explicaria para alguém competente e novo
sem jargão interno não explicado, sem etapas subentendidas
- 03
Inclua o critério de pronto
o que precisa estar verdadeiro para a tarefa estar concluída
- 04
Escreva a descrição por último
agora você sabe exatamente qual gatilho descrever
- 05
Teste pedindo com as palavras de outra pessoa
se não ativar, o problema é a descrição, não o conteúdo
Onde skills não ajudam
Conhecimento que muda todo dia. Skill é arquivo versionado; se o conteúdo muda diariamente, ele vai estar desatualizado quando for lido. Esse caso é RAG, com a fonte viva.
Instruções curtas. Se cabe em duas frases, um prompt resolve. Skill tem custo de manutenção, e custo de manutenção só se paga com reuso.
Substituir julgamento. Uma skill descreve como executar bem um procedimento que já existe. Ela não decide se o procedimento faz sentido — isso continua sendo trabalho de gente.
O resumo: skills convertem conhecimento tácito em ativo reutilizável, sem cobrar contexto por isso. É a diferença entre uma empresa em que o procedimento certo mora na memória de três pessoas e uma em que ele mora em um arquivo que todo agente sabe encontrar.