# O que é uma Agent Skill? Como criar instruções reutilizáveis para IA Veja como funciona uma Agent Skill, o papel do arquivo SKILL.md, a divulgação progressiva e a diferença entre instruções e ferramentas de execução. Por Bruno Rana Publicado em: 2026-10-27 Atualizado em: 2026-11-04 Artigo original: https://buildrun.com.br/blog/o-que-e-agent-skill/ ![Uma bancada separa descobrir a skill, ler SKILL.md e abrir arquivos opcionais quando necessários.](https://buildrun.com.br/diagrams/skill-progressive-disclosure.webp) Carregue instruções e arquivos adicionais no momento em que ajudam a tarefa. Repetir as mesmas orientações para um agente em toda conversa dá trabalho. Você ajusta o procedimento, acrescenta cuidados e, na tarefa seguinte, precisa lembrar de explicar tudo outra vez. Uma Agent Skill serve para guardar esse conhecimento de forma organizada e reutilizável. No formato aberto Agent Skills, ela é um diretório com instruções e materiais para um tipo de tarefa. O arquivo obrigatório é o **SKILL.md**; scripts, referências e modelos podem complementar o procedimento quando forem necessários. Isso ajuda a dar continuidade ao seu jeito de trabalhar, mas não dispensa a conferência do resultado. A skill orienta o agente; ele ainda precisa interpretar o projeto, usar as ferramentas disponíveis e reunir evidências do que fez. ## O que vai dentro de uma Agent Skill A estrutura mínima é uma pasta com `SKILL.md`. No formato publicado em [agentskills.io](https://agentskills.io/specification), o arquivo começa com metadados YAML que incluem `name` e `description`. O nome segue limites de caracteres e deve corresponder ao diretório; a descrição diz o que a skill faz e em quais tarefas é relevante. O corpo em Markdown traz o procedimento. Para ver como essas partes se conectam, considere um procedimento de revisão de API. Você quer que o agente localize a operação, confira o contrato e os controles de acesso e procure os testes relacionados. A pasta que organiza esse trabalho poderia começar assim: ```text revisar-api/ ├── SKILL.md ├── references/ │ └── checklist-api.md └── assets/ └── modelo-revisao.md ``` O documento de referência e o modelo são opcionais. A especificação também admite diretórios opcionais como `scripts/` para código executável. Eles fazem sentido quando ajudam a tarefa, mas podem trazer dependências e efeitos que precisam ser entendidos e revisados. Um `SKILL.md` curto para orientar o cenário pode conter: ```markdown --- name: revisar-api description: Avalia uma rota de API quanto a contrato, validação, autorização e testes. Use ao revisar endpoints HTTP em um repositório. --- 1. Localize a definição da rota e o contrato de entrada e saída. 2. Identifique validações e requisitos de autenticação e autorização. 3. Compare os resultados de erro documentados com os testes existentes. 4. Liste evidências e dúvidas. Não altere o código sem solicitação. ``` Esse exemplo orienta o agente a produzir uma revisão, mas não é um verificador automático nem uma garantia de que cada etapa será seguida corretamente. ## Como a divulgação progressiva reduz instruções desnecessárias O formato recomenda carregar informação em etapas. Primeiro, um cliente compatível pode conhecer apenas os nomes e as descrições das skills disponíveis. Quando a tarefa combina com a descrição, ele pode carregar o conteúdo de `SKILL.md`. Só quando o procedimento pedir, o agente consulta arquivos de referência ou executa scripts. Na revisão da rota, a descrição ajuda a reconhecer que a tarefa é uma avaliação de endpoint. Ao ativar a skill, o modelo recebe o checklist. Se a política de autorização estiver detalhada em `references/checklist-api.md`, esse material pode ser aberto durante a etapa correspondente, sem acrescentar todo o conteúdo às instruções iniciais. Essa sequência é conhecida como divulgação progressiva: descoberta, ativação e consulta de recursos conforme a necessidade. A especificação descreve o formato e a organização; cada produto decide como descobre, ativa e executa skills. Ter uma pasta válida não significa que qualquer agente vá encontrá-la ou carregá-la automaticamente. ## Skill, ferramenta MCP e contexto da conversa Uma skill orienta **como abordar o trabalho**. Uma ferramenta MCP oferece **uma operação que um host pode encaminhar a um servidor**. Por exemplo, a skill `revisar-api` pode orientar uma análise dos testes e do contrato. Uma ferramenta MCP conectada ao repositório poderia, se existisse e fosse autorizada pela aplicação, ler arquivos ou executar uma consulta específica.
Um caderno de instruções, uma ferramenta e uma pasta de contexto mostram três papéis diferentes no trabalho do agente.
Instruções orientam o trabalho; a ferramenta oferece uma capacidade; o contexto contém o que está disponível ao modelo.
Os dois recursos podem se complementar: a skill fornece o fluxo de revisão e uma ferramenta fornece acesso a uma capacidade. Mas uma instrução de "ler o contrato" não cria acesso ao repositório. Da mesma forma, conectar uma ferramenta não entrega ao agente o critério de revisão do time. O artigo sobre [como funciona o MCP](https://buildrun.com.br/blog/o-que-e-mcp/) acompanha essa separação em uma consulta de envio. Também vale separar contexto e modelo. Contexto é a informação e as instruções disponíveis ao modelo em uma etapa: pergunta, arquivos selecionados, saída de ferramenta e trechos da skill. O modelo é o sistema que processa esse contexto para gerar respostas ou propor ações. Uma skill muda as instruções disponíveis em determinada tarefa; não treina um novo modelo nem injeta conhecimento de forma permanente. Veja essa composição no artigo sobre [modelo, harness e agente](https://buildrun.com.br/blog/harness-modelo-agente/). ## Como criar e revisar uma skill útil Para o caso da rota de API, comece por uma tarefa recorrente com um resultado claro. Depois, transforme o procedimento em instruções que possam ser observadas:
Um procedimento é revisto a partir de um caso concreto e do resultado observado num medidor.
Uma skill útil começa com uma tarefa recorrente e melhora com revisões baseadas no uso.
1. **Defina o escopo.** Determine se a skill revisa contratos, segurança, testes ou tudo isso. Evite descrições amplas como “ajude com backend”. 2. **Escreva a descrição para descoberta.** Inclua termos que uma pessoa usaria ao pedir uma revisão de endpoint e explique quando ativar a skill. 3. **Oriente uma etapa por vez.** Peça ao agente para localizar o contrato, verificar regras, comparar testes e citar evidências. Diga qual formato de saída facilita a revisão. 4. **Mantenha referências sob demanda.** Coloque uma política longa ou exemplos detalhados em arquivos pequenos relacionados, em vez de carregar tudo em `SKILL.md`. 5. **Teste com tarefas reais e casos de fronteira.** Compare o resultado com o que uma revisão cuidadosa deveria encontrar: por exemplo, uma rota sem teste de acesso, um erro não documentado ou uma evidência insuficiente. Ajuste instruções vagas e repita os casos. Uma skill não restringe por si só o que o agente pode fazer. Se a instrução diz “não altere o código”, mas o host fornece uma ferramenta capaz de escrever arquivos, a aplicação e suas permissões precisam aplicar os controles apropriados. Revise scripts e referências como conteúdo executável ou de entrada; instruções de um arquivo não substituem autenticação, autorização ou validação de resultados. ## Fontes oficiais * [Visão geral de Agent Skills](https://agentskills.io/home) * [Especificação do formato Agent Skills](https://agentskills.io/specification) * [Como usar Agent Skills com MCP](https://modelcontextprotocol.io/docs/2026-07-28/develop/build-with-agent-skills) O formato é aberto, mas a compatibilidade e os detalhes de ativação variam entre implementações. Consulte a documentação do agente escolhido antes de distribuir uma skill. As referências foram consultadas em 27/10/2026.