Uma Skill é muito menos mágica do que parece

Quando começamos a trabalhar com agentes de IA, rapidamente aparece uma palavra nova: Skill.

Há repositórios, catálogos e pacotes com dezenas delas. A linguagem ao redor do conceito pode fazer parecer que estamos diante de algum componente muito sofisticado.

Vale tirar um pouco da fumaça.

Como modelo mental, uma Skill é algo simples:

uma instrução organizada para poder ser reutilizada.

Na implementação descrita pela documentação oficial da OpenAI, uma Skill é um diretório ancorado por um arquivo SKILL.md. Esse diretório pode conter apenas instruções, mas também pode incluir referências, scripts e templates. Portanto, ela pode ser maior do que um prompt, embora continue sendo menos misteriosa do que o nome sugere.

Um exemplo simples

Imagine que vários agentes de uma empresa precisam consultar o mesmo CRM.

Todos precisam saber:

onde procurar;
quais campos importam;
como interpretar determinadas informações;
quais regras devem respeitar;
o que podem ou não alterar.

Uma opção seria repetir essas instruções dentro de cada AGENTS.md:

agente-comercial
    └── instruções para consultar CRM

agente-documentos
    └── instruções para consultar CRM

agente-pos-venda
    └── instruções para consultar CRM

Funciona. Mas agora temos três cópias da mesma coisa. Quando a regra mudar, precisamos lembrar de alterar as três.

É aí que uma Skill começa a fazer sentido:

skills/
└── consultar-crm/
    ├── SKILL.md
    ├── references/
    │   └── campos-do-crm.md
    └── scripts/
        └── consultar-cliente.sh

Nem toda Skill precisa dessas pastas adicionais. Se a instrução for suficiente, o diretório pode conter apenas SKILL.md:

---
name: consultar-crm
description: Consulte dados comerciais no CRM quando a tarefa depender do histórico de um cliente.
---

Use o identificador do cliente informado na tarefa.

Consulte apenas os campos necessários para responder à solicitação.

Não altere registros sem autorização explícita.

Informe quando um dado não estiver disponível ou estiver desatualizado.

Nome e descrição ajudam o agente a reconhecer o que a capacidade faz e quando deve considerá-la. O corpo contém as instruções completas.

Os agentes que precisam dessa capacidade passam a reutilizar a mesma fonte. Isso é composição.

Skill não é a ferramenta

No exemplo do CRM, a Skill não cria acesso ao sistema. O agente ainda precisa de uma ferramenta, API ou conexão que consiga consultar os dados, além das credenciais e permissões adequadas.

A separação fica assim:

Skill
→ quando e como executar o trabalho

ferramenta ou API
→ consultar ou alterar o sistema

permissões
→ limitar aquilo que pode ser feito

Essa distinção importa especialmente para operações de escrita. Uma frase como “não altere registros sem autorização” ajuda a orientar o agente, mas uma operação crítica também deveria ser protegida pela própria ferramenta ou por um fluxo de aprovação. Instrução não substitui controle de acesso.

Uma Skill também não é um agente independente. Ela oferece uma capacidade que o agente pode usar dentro de um trabalho maior. Essa diferença é discutida com mais detalhes em AI Skills são fluxos reutilizáveis, não agentes.

Skill é uma forma de reaproveitar conhecimento

Podemos ter Skills como:

consultar-crm
gerar-documento
validar-documento
versionar-projeto
fazer-handoff
comparar-propostas

Uma capacidade pode ser usada por vários agentes sem que cada um mantenha uma cópia independente das instruções.

Isso se parece com algo que fazemos há décadas em software: encontramos uma responsabilidade coerente, damos um nome, definimos sua interface e passamos a compor coisas maiores a partir dela.

A analogia tem limite. Skills não são necessariamente funções determinísticas. O modelo ainda interpreta as instruções, e o resultado pode variar. Reutilizar uma Skill reduz duplicação; não garante, por si só, que todas as execuções serão iguais.

Carregar quando necessário

Skills também ajudam a controlar contexto.

Imagine um AGENTS.md contendo absolutamente tudo que um agente talvez precise saber:

gerar documentos;
consultar CRM;
analisar planilhas;
escrever atas;
produzir PDFs;
versionar arquivos;
verificar contratos;
fazer pesquisas.

Numa tarefa específica, talvez ele precise apenas consultar o CRM. Colocar todas as instruções detalhadas no contexto principal aumenta o volume que precisa ser considerado mesmo quando a maior parte não se aplica.

Na implementação documentada pela OpenAI, o agente vê primeiro o nome, a descrição e o caminho das Skills disponíveis. Quando escolhe uma delas, lê o SKILL.md e os arquivos de apoio necessários. É uma forma de revelar detalhes progressivamente:

consultar-crm
→ use quando a tarefa exigir o histórico comercial de um cliente
→ carregue as instruções completas quando a capacidade for necessária

Esse mecanismo pode melhorar duas coisas ao mesmo tempo: reuso e foco.

Isso não significa que menos contexto seja sempre melhor. Pouco contexto pode omitir uma regra decisiva. O objetivo é manter no contexto permanente aquilo que vale para todo o trabalho e carregar detalhes especializados quando eles passarem a ser relevantes.

Quando transformar algo em Skill?

Uma boa pergunta é:

Estou ensinando isso novamente?

Se a resposta for sim, talvez exista uma Skill esperando para ser criada.

Eu procuraria também outros sinais:

existe uma situação reconhecível que deve ativar a capacidade;
as instruções produzem um resultado identificável;
há regras, exemplos ou templates que precisam permanecer juntos;
mais de um agente ou projeto pode reutilizar o procedimento;
a capacidade muda num ritmo diferente das regras gerais do agente.

Outra situação aparece quando o AGENTS.md começa a crescer demais. Há trechos fundamentais para qualquer tarefa daquele projeto. Esses provavelmente devem continuar ali. Outros só importam ocasionalmente e podem ser extraídos.

Uma separação possível:

AGENTS.md
→ responsabilidade, limites e regras permanentes do projeto

skills/
→ capacidades específicas usadas quando necessário

Essa fronteira não é universal. Se uma regra precisa ser obedecida em toda tarefa, escondê-la numa Skill opcional aumenta o risco de ela não ser carregada. Nesse caso, o AGENTS.md continua sendo um lugar mais adequado.

Skills também podem evoluir

Depois que uma capacidade foi separada, ela deixa de pertencer exclusivamente a um agente. Pode ser melhorada uma vez e reutilizada em vários lugares.

              consultar-crm
              /     |     \
             /      |      \
       comercial documentos pós-venda

O aprendizado deixa de ficar preso ao lugar onde aconteceu e vira uma peça reutilizável. Essa vantagem também cria uma responsabilidade: uma mudança na Skill pode afetar vários consumidores.

Por isso, eu versionaria essas mudanças e testaria os fluxos que dependem dela. Uma alteração centralizada é mais fácil de distribuir, mas também centraliza o risco de regressão.

Uma Skill precisa ser revisada

O formato simples não torna uma Skill inofensiva. Suas instruções podem influenciar planejamento, uso de ferramentas e execução de comandos. Se houver scripts, eles podem executar código no ambiente quando forem acionados.

A documentação da OpenAI recomenda tratar Skills como instruções privilegiadas e revisar pacotes de terceiros antes de disponibilizá-los ao agente. Eu aplicaria o mesmo cuidado usado para uma dependência:

entender de onde veio;
ler o SKILL.md;
inspecionar scripts e referências;
verificar quais ferramentas e dados ela pode alcançar;
limitar ações destrutivas ou de escrita;
testar com entradas representativas.

Um catálogo grande não é automaticamente uma vantagem. A procedência e a qualidade das capacidades importam mais do que a quantidade instalada.

Não transforme tudo em Skill

Também existe o exagero contrário.

Se criarmos uma Skill para cada pequena instrução, apenas substituímos um arquivo grande por centenas de diretórios difíceis de entender, descobrir e manter.

O objetivo não é maximizar o número de Skills. É encontrar capacidades com coerência, um gatilho reconhecível e potencial de reutilização.

Depois dessa separação, ainda resta decidir quanto detalhe colocar nas instruções. Em AI Skills para GPT-5.6 Sol: menos instrução, mais contrato, mostro como tenho revisado Skills antigas para preservar restrições e critérios de conclusão sem microgerenciar cada passo.

Menos mágica, mais engenharia

A parte interessante das Skills não está em alguma inteligência escondida dentro delas. Está na organização.

Pegamos uma instrução que funcionou. Damos um nome. Explicamos quando deve ser usada. Juntamos os recursos necessários. Separamos do restante do contexto. E passamos a reutilizá-la.

Em vez de imaginar Skills como poderes especiais instalados no agente, prefiro uma descrição menos emocionante:

Skills são conhecimento operacional empacotado para reutilização.

É justamente quando o conceito parece menos mágico que ele começa a ficar mais útil.