Habilidades de Agente: Um Guia Completo

Quando Usar

• Use ao criar, editar, revisar ou depurar um arquivo SKILL.md de agente.
• Use quando precisar de orientação de qualidade para gatilhos, exemplos, limitações e notas de segurança.

Uma referência consolidada sobre o que são habilidades de agente, por que existem, como funcionam e como escrever habilidades eficazes.

1. O que são habilidades de agente

Uma Habilidade de Agente é uma pasta contendo um arquivo SKILL.md (frontmatter YAML + instruções em markdown), mais subpastas opcionais para scripts, referências e assets que o agente carrega sob demanda.

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code (CLIs, validators, helpers)
├── references/       # Optional: detailed docs loaded only when needed
└── assets/           # Optional: templates, fonts, static files

As habilidades são um padrão aberto (agentskills.io), originalmente criadas pela Anthropic e adotadas por OpenAI Codex, Cursor, Gemini CLI, Microsoft Agent Framework, Google ADK e mais de 40 outros produtos de agente. Uma habilidade escrita uma vez funciona em todos os agentes compatíveis.

2. Por que essa abstração existe

LLMs base são generalistas. O trabalho real requer conhecimento procedural, contexto organizacional e fluxos de trabalho repetíveis. Cada alternativa anterior tinha um modo de falha:

As habilidades resolvem quatro problemas de uma vez:

• Eficiência de contexto — instruções carregam apenas quando relevantes
• Repetibilidade — procedimentos de várias etapas se tornam fluxos de trabalho auditáveis
• Composabilidade — múltiplas habilidades se combinam em tempo de execução por tarefa
• Portabilidade — os mesmos arquivos funcionam entre fornecedores e superfícies

Modelo mental: as habilidades são para LLMs o que as páginas de manual, runbooks e manuais de equipe são para engenheiros — material de referência carregado na memória de trabalho apenas quando a tarefa exige.

3. Como funcionam — divulgação progressiva

O núcleo arquitetônico. Carregamento em três estágios:

Nível 1 — Descoberta (~100 tokens por habilidade, sempre em contexto): Apenas name + description do frontmatter são injetados no prompt do sistema na inicialização. O agente sabe que a habilidade existe e quando ela se aplica. Você pode instalar dezenas de habilidades com sobrecarga negligenciável.

Nível 2 — Ativação (<5.000 tokens, carregado ao corresponder): Quando a solicitação do usuário corresponde à descrição de uma habilidade, o agente lê o corpo completo de SKILL.md para o contexto.

Nível 3 — Execução (ilimitado, sob demanda): O agente lê arquivos referenciados (references/foo.md) ou executa scripts (scripts/validate.py) apenas conforme necessário. Scripts podem ser executados sem que seu código-fonte seja carregado no contexto.

É por isso que o conteúdo empacotado não tem limite prático. Os arquivos não consomem tokens até serem acessados.

4. Anatomia do SKILL.md

---
name: skill-name
description: What this skill does AND when to use it. Include trigger phrases the user will say.
---

# Skill Name

## Quick start
[Minimal working example]

## Workflow
[Step-by-step procedure with checklists]

## Output format
[What the user/agent should expect back]

## Advanced
[Link to references/ for rarely-needed detail]

Restrições do Frontmatter:

• name é minúsculo, apenas hifens, 1–64 caracteres, corresponde exatamente ao nome da pasta pai
• Evite < e > no frontmatter (eles podem ser injetados no prompt do sistema)
• YAML inválido impede o carregamento silenciosamente

Campos padrão opcionais:

• disable-model-invocation: true — impede que o agente carregue automaticamente a habilidade com base na conversa; ela só pode ser acionada manualmente (por exemplo, /skill-name). Agora é um campo de especificação padrão de Habilidades de Agente, portanto, funciona em clientes compatíveis com a especificação (Claude Code, Copilot, etc.), não apenas Claude. Observação: impede a invocação automática, mas alguns clientes (Claude Code, bug aberto) ainda injetam description no contexto, então nem sempre economiza os tokens de nível de descoberta. Use para utilitários apenas manuais que você não quer que disparem automaticamente.

5. Duas filosofias de design

As habilidades tendem a cair em um de dois padrões. Ambos são válidos; eles resolvem problemas diferentes.

Padrão A — Primitivas de Capacidade (wrappers de ferramentas)

A habilidade é um wrapper fino sobre um CLI ou script determinístico. A lógica vive no código. SKILL.md ensina o agente como invocá-lo.

…