Anatomia de uma Skill

Contexto

O que é uma Skill?

No contexto dos agentes de Inteligência Artificial, uma Skill é um conjunto reutilizável de instruções, regras, conhecimento e recursos que ensina um agente a executar uma tarefa ou um tipo de tarefa de forma mais consistente.

Uma Skill pode definir:

quando deve ser utilizada;
quais os dados de entrada necessários;
que etapas devem ser executadas;
que ferramentas podem ou devem ser utilizadas;
restrições e regras de segurança;
critérios de decisão;
formato esperado dos resultados;
verificações a realizar antes de concluir a tarefa;
scripts, referências, exemplos, templates ou outros recursos de apoio.

Uma Skill não deve ser entendida como um simples prompt longo. Funciona antes como um manual operacional reutilizável para um agente de IA.

Como funcionam?

No formato aberto de Agent Skills, uma Skill é normalmente representada por uma pasta que contém, no mínimo, um ficheiro SKILL.md.

Esse ficheiro combina:

metadados em YAML, usados para identificar e descrever a Skill;
instruções em Markdown, que definem o modo de execução.

A Skill pode ainda incluir scripts, documentação de referência, templates, exemplos, imagens, schemas ou outros recursos necessários ao workflow.

Um agente compatível pode analisar os metadados das Skills disponíveis, identificar aquela que corresponde à tarefa atual e carregar as instruções completas apenas quando necessário. Este mecanismo reduz o contexto utilizado e permite manter muitas Skills disponíveis sem carregar todas as instruções simultaneamente.

Diferença entre Prompt e Skill

Prompts e Skills são mecanismos relacionados, mas têm funções diferentes.

Um prompt transmite instruções ao modelo num determinado contexto. Uma Skill encapsula conhecimento procedural e um workflow reutilizável que pode ser aplicado repetidamente por um agente.

Aspeto	Prompt	Skill
Finalidade	Dá instruções ou contexto para uma tarefa, pergunta ou objetivo.	Define uma capacidade ou procedimento reutilizável para executar um tipo de tarefa.
Configuração	Pode existir em diferentes níveis de instrução, como sistema, aplicação/desenvolvedor e utilizador.	É normalmente armazenada como um artefacto dedicado e versionável, geralmente numa pasta com `SKILL.md`.
Reutilização	Pode ser reutilizado, mas muitas vezes é escrito para uma interação ou contexto concreto.	É concebida especificamente para ser reutilizada em tarefas semelhantes.
Execução	O modelo interpreta as instruções presentes no contexto e gera uma resposta ou ação.	O agente identifica a Skill adequada, carrega as instruções e segue o workflow definido, utilizando ferramentas e recursos quando necessário.
Estrutura	Pode variar desde uma frase simples até instruções complexas.	Normalmente possui estrutura, metadados, workflow, restrições, recursos e critérios de validação.
Consistência	Depende fortemente da qualidade do prompt e do contexto fornecido.	Tende a produzir maior consistência porque o procedimento é explicitamente documentado e reutilizado.
Manutenção	Alterações podem exigir modificar prompts dispersos por várias aplicações ou conversas.	Pode ser versionada e atualizada como um componente independente.
Ideal para	Perguntas, brainstorming, tarefas pontuais e instruções específicas.	Processos recorrentes, especializados, multi-etapa ou que exigem regras consistentes.

Uma forma simples de visualizar a diferença é:

Prompt = instrução para esta interação.
Skill = procedimento reutilizável para este tipo de trabalho.

Importância das Skills

As Skills tornam os agentes mais previsíveis, especializados e reutilizáveis.

Poupar tempo em tarefas repetitivas

Uma Skill evita explicar repetidamente ao agente como executar o mesmo tipo de tarefa.

Pode ser utilizada, por exemplo, para:

analisar documentos;
gerar relatórios;
rever código;
preparar apresentações;
tratar dados;
organizar ficheiros;
executar procedimentos técnicos;
aplicar normas internas de uma organização.

Produzir resultados mais consistentes

Quando as mesmas instruções, etapas, formatos e verificações são reutilizados, reduz-se a variabilidade entre execuções.

A consistência não depende apenas da Skill: continua a depender do modelo, dos dados de entrada, das ferramentas disponíveis e da qualidade das instruções. Contudo, uma Skill bem construída reduz significativamente a improvisação desnecessária.

Suportar casos de uso especializados

Uma Skill pode incorporar conhecimento específico de um domínio.

Exemplos:

análise jurídica;
administração de sistemas;
desenvolvimento de software;
análise de dados;
suporte técnico;
marketing;
investigação;
documentação técnica;
processos internos de uma empresa.

Assim, o agente deixa de depender apenas do seu conhecimento geral e passa a receber procedimentos e referências específicos para aquele contexto.

Escalar processos

Uma Skill permite transformar conhecimento individual num procedimento reutilizável por várias pessoas ou agentes.

Isto facilita:

normalização de processos;
partilha de boas práticas;
formação de equipas;
automação de tarefas;
redução de erros;
auditoria de procedimentos;
melhoria contínua.

O padrão Agent Skills

Estrutura básica

No padrão aberto Agent Skills, uma Skill corresponde a um diretório que contém pelo menos:

minha-skill/
├── SKILL.md
├── scripts/        # opcional
├── references/     # opcional
├── assets/         # opcional
└── ...

O único ficheiro obrigatório é normalmente o SKILL.md.

As restantes pastas dependem das necessidades da Skill.

`SKILL.md`

O ficheiro contém duas partes principais:

---
name: minha-skill
description: Descrição do que a Skill faz e de quando deve ser utilizada.
---

# Instruções

...

O bloco YAML inicial constitui o frontmatter.

Os campos obrigatórios e opcionais podem variar consoante a especificação e o cliente, mas name e description são os elementos fundamentais do formato aberto.

Divulgação progressiva

Uma das ideias centrais das Agent Skills é a divulgação progressiva (progressive disclosure).

Em vez de carregar todas as Skills completas para o contexto do modelo, um cliente compatível pode trabalhar em várias fases:

1. Descoberta

O agente conhece apenas informação mínima sobre as Skills disponíveis, especialmente:

nome;
descrição.

2. Ativação

Quando uma tarefa corresponde à descrição de uma Skill, o agente pode carregar o respetivo SKILL.md.

3. Execução

O agente segue as instruções e, se necessário, consulta recursos adicionais ou executa ferramentas e scripts.

Esta abordagem reduz o consumo de contexto e permite manter bibliotecas de Skills relativamente grandes.

Anatomia de uma Skill

Uma Skill de boa qualidade deve responder claramente a várias perguntas.

1. Identificação

Que Skill é esta?

Normalmente definida através de:

name;
description;
versão;
autor ou organização;
licença;
metadados adicionais.

A descrição é especialmente importante porque pode ser utilizada pelo agente para decidir quando a Skill é relevante.

2. Condições de utilização

Quando deve ser utilizada?

Uma Skill deve deixar claro:

quais os pedidos que a devem ativar;
que tipos de ficheiros ou dados suporta;
que tarefas estão dentro do seu âmbito;
que tarefas estão fora do seu âmbito.

Uma descrição demasiado vaga pode provocar ativações incorretas.

3. Entradas

De que informação necessita?

Por exemplo:

ficheiros;
texto;
parâmetros;
credenciais;
localização;
dados estruturados;
contexto do projeto.

Quando falta uma entrada obrigatória, a Skill deve indicar como proceder.

4. Workflow

Que sequência de trabalho deve o agente seguir?

Exemplo:

1. Validar entradas
2. Identificar o tipo de tarefa
3. Consultar referências necessárias
4. Executar a operação
5. Validar o resultado
6. Corrigir problemas encontrados
7. Produzir o resultado final

O workflow deve ser suficientemente explícito para reduzir ambiguidades, mas não tão rígido que impeça o agente de se adaptar quando isso for necessário.

5. Ferramentas

Que ferramentas podem ou devem ser utilizadas?

Uma Skill pode depender de:

acesso ao sistema de ficheiros;
browser;
APIs;
bases de dados;
terminal;
Python;
Git;
aplicações externas;
ferramentas MCP;
scripts locais.

É importante distinguir entre:

ferramenta obrigatória;
ferramenta preferencial;
ferramenta opcional;
ferramenta proibida.

6. Recursos

Uma Skill pode incluir recursos de apoio.

`references/`

Documentação que o agente pode consultar quando necessária.

Exemplos:

references/
├── api.md
├── regras-negocio.md
├── arquitetura.md
└── exemplos.md

`scripts/`

Código reutilizável para operações determinísticas ou repetitivas.

Exemplos:

scripts/
├── validate.py
├── convert.py
└── build_report.py

`assets/`

Recursos utilizados na produção do resultado.

Exemplos:

templates;
imagens;
schemas;
ficheiros de configuração;
exemplos;
modelos de documentos.

7. Restrições e guardrails

O que o agente não deve fazer?

Uma boa Skill deve definir explicitamente limites.

Exemplos:

não eliminar ficheiros sem confirmação;
não alterar ficheiros de produção;
não expor credenciais;
não inventar dados em falta;
não utilizar ferramentas externas sem autorização;
não executar operações destrutivas sem validação.

Os guardrails reduzem erros e tornam a execução mais segura.

8. Formato de saída

A Skill deve especificar, quando relevante, como o resultado deve ser apresentado.

Exemplos:

Markdown;
JSON;
CSV;
relatório;
tabela;
código;
ficheiro;
estrutura de diretórios.

Quando o formato é importante para sistemas automáticos, deve ser descrito de forma rigorosa.

9. Validação

Uma Skill robusta não termina simplesmente depois de executar a tarefa.

Deve definir verificações finais.

Por exemplo:

Antes de concluir:

- confirmar que todos os ficheiros foram processados;
- validar a sintaxe;
- verificar campos obrigatórios;
- confirmar que não existem erros;
- comparar o resultado com os requisitos;
- indicar limitações ou dados em falta.

Esta etapa funciona como um mecanismo de controlo de qualidade.

10. Tratamento de erros

Uma Skill deve explicar como reagir quando algo corre mal.

Pode definir:

quando repetir uma operação;
quando usar uma estratégia alternativa;
quando interromper;
quando pedir informação adicional;
quando informar o utilizador de uma limitação.

Uma Skill que descreve apenas o cenário ideal tende a ser menos robusta.

Ciclo de execução

De forma simplificada, o ciclo pode ser representado assim:

Pedido do utilizador
        │
        ▼
Descoberta das Skills disponíveis
        │
        ▼
Existe uma Skill relevante?
        │
   ┌────┴────┐
   │         │
  não       sim
   │         │
   ▼         ▼
Resposta    Carregar SKILL.md
normal          │
                ▼
          Validar entradas
                │
                ▼
          Executar workflow
                │
                ▼
          Usar ferramentas
                │
                ▼
          Validar resultado
                │
                ▼
          Entregar resposta

Portabilidade

O formato Agent Skills foi concebido para facilitar a reutilização entre diferentes agentes e plataformas compatíveis.

No entanto, portabilidade de formato não significa compatibilidade total de execução.

Uma Skill pode necessitar de adaptações quando muda de cliente devido a diferenças em:

ferramentas disponíveis;
sistema de permissões;
localização dos diretórios;
APIs;
convenções próprias do cliente;
suporte a campos adicionais no YAML;
mecanismos de ativação;
ambientes de execução.

Assim, é mais correto dizer:

Uma Skill baseada no padrão aberto pode ser estruturalmente portátil entre clientes compatíveis, mas a execução pode exigir adaptações específicas da plataforma.

Boas práticas

Uma Skill deve ser:

Específica

Deve resolver um problema ou conjunto de problemas claramente relacionado.

Reutilizável

Não deve depender desnecessariamente de uma única conversa.

Determinística quando possível

Operações que podem ser executadas de forma fiável através de scripts devem considerar essa abordagem em vez de depender exclusivamente de geração de texto.

Modular

Skills demasiado grandes tornam-se difíceis de manter.

É geralmente preferível dividir responsabilidades distintas em Skills independentes.

Explícita

Regras importantes não devem depender de interpretação implícita.

Versionável

Como são ficheiros de texto e recursos associados, as Skills podem ser mantidas num sistema de controlo de versões como o Git.

Testável

Uma Skill deve ser testada com diferentes tipos de entrada, incluindo:

casos normais;
casos limite;
entradas incompletas;
erros de ferramentas;
dados inesperados.

Segurança

Skills podem incluir instruções capazes de:

executar scripts;
ler ficheiros;
aceder a serviços externos;
utilizar APIs;
alterar dados;
executar comandos.

Por isso, uma Skill obtida de terceiros deve ser tratada de forma semelhante a código ou automação externa.

Antes de instalar ou executar uma Skill desconhecida, convém verificar:

origem;
conteúdo do SKILL.md;
scripts incluídos;
comandos executados;
acessos de rede;
permissões solicitadas;
utilização de credenciais;
operações destrutivas.

Uma Skill não deve ser considerada segura apenas por estar escrita em Markdown.

Quando criar uma Skill?

Uma Skill é especialmente útil quando:

a mesma tarefa é executada frequentemente;
existe um procedimento bem definido;
é importante manter consistência;
são necessárias várias etapas;
existem regras que não podem ser esquecidas;
o agente necessita de documentação especializada;
existem ferramentas ou scripts específicos;
o resultado precisa de seguir um formato preciso.

Uma Skill pode ser desnecessária quando:

a tarefa é única;
um prompt simples resolve o problema;
não existe um processo suficientemente estável;
o workflow ainda está em fase de exploração.

Prompt, Skill, Tool e Agent

Estes conceitos são frequentemente confundidos.

Conceito	Função
Prompt	Diz ao modelo o que deve fazer ou considerar.
Skill	Ensina um procedimento reutilizável para um determinado tipo de trabalho.
Tool	Permite ao agente executar uma ação externa ou obter informação.
Agent	Sistema que interpreta objetivos, seleciona Skills e ferramentas e coordena a execução.

Uma Skill pode instruir um agente a utilizar uma Tool, mas a Skill não é a própria ferramenta.

Exemplo conceptual

Imagine uma Skill chamada:

analisar-configuracao-nginx

A Skill poderia definir:

---
name: analisar-configuracao-nginx
description: Analisa configurações Nginx, identifica erros, problemas de segurança e oportunidades de otimização.
---

E depois incluir um workflow:

1. Localizar os ficheiros de configuração.
2. Identificar includes.
3. Validar a sintaxe.
4. Analisar configuração TLS.
5. Procurar regras inseguras.
6. Identificar conflitos de server_name e portas.
7. Verificar headers de segurança.
8. Produzir relatório.
9. Classificar problemas por severidade.
10. Sugerir correções sem alterar ficheiros automaticamente.

Poderia ainda utilizar:

scripts/
└── nginx_check.sh

references/
├── security.md
└── conventions.md

Este conjunto forma uma capacidade reutilizável muito mais estruturada do que um único prompt.

Conclusão

Uma Skill pode ser entendida como uma unidade reutilizável de conhecimento procedural para agentes de IA.

A sua utilidade não está apenas em guardar instruções, mas em reunir num único componente:

Skill
├── Metadados
├── Condições de utilização
├── Entradas
├── Workflow
├── Ferramentas
├── Recursos
├── Restrições
├── Tratamento de erros
├── Formato de saída
└── Validação

Esta estrutura permite transformar procedimentos humanos ou prompts repetidos em workflows mais consistentes, documentados, versionáveis e reutilizáveis.

Referências

OpenAI — Skills in ChatGPT https://help.openai.com/en/articles/20001066
OpenAI Academy — Using skills https://openai.com/academy/skills/
Agent Skills — Overview / Specification https://agentskills.io/