O que é uma Agent Skill? Como criar instruções reutilizáveis para IA

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, 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:

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:

---
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.

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 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.

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:

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
• Especificação do formato Agent Skills
• Como usar Agent Skills com MCP

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.