Seu agente de IA (Claude Code, Codex Gemini) possui uma determinada janela de contexto, vamos pegar por exemplo o modelo Claude Sonnet 4.5 que possui 200 mil tokens, a instrução da sua SKILL que ele realmente precisava tinha 400 tokens, porem ele ignorou.
Esses 400 tokens estavam perdidos em uma posição da sua janela de contexto na posição 130 mil, acima estava seis definições de ferramentas, quadro documentos de referência e um guia de marca que ninguém pediu para o modelo ler. Essa é a razão mais comum para a falha de agentes em produção. Não é culpa do modelo ou da estrutura do seu projeto, o problema ficou muito grande e a coisa certa acabou sendo negligenciada.
As habilidades (SKILL.md) são a solução mais simples para esse problema. Não se trata de um modelo maior, uma janela maior ou um mecanismo de recuperação mais inteligente. Apenas um pequeno conjunto de decisões de design sobre onde o contexto reside e quando ele é carregado. Neste artigo vou explicar as cinco peças que fazem tudo funcionar e como cada uma se encaixa.
2. Uma habilidade é uma pasta
Uma Skill não é uma classe python nem uma ferramenta registrada, é simplesmente uma pasta no disco com um arquivo markdown dentro dela:
O arquivo SKILL.md é o único obrigatório, a pasta references contém documentos que o agente lê sob demanda. A pasta assets contém modelos e arquivos de marca, já a pasta scripts contém o código que o agente pode executar. Tudo, exceto o arquivo SKILL.md, é opcional. Como uma habilidade consistente apenas em arquivos, você versiona no Git, você compara as versões em PRs. Você a copia entre projetos, você publica no Github.
O mesmo arquivo SKILL.md funciona com Claude Code, Codex, Gemini CLI, Cursor etc.. Uma pasta, vários ambientes de execução.
3. As primeiras linhas são o índice de pesquisa.
Abra qualquer arquivo SKILL.md e a primeira coisa que você verá é um cabeçalho YAML com dois campos. Esses dois campos não são apenas metadados, eles são o índice de pesquisa.
Ao iniciar a sessão, o agente carrega o nome e a descrição de cada habilidade instalada. Aproximadamente 100 tokens por habilidade. O corpo, as referências, os scripts, tudo permanece no disco.
Quando uma solicitação (prompt) é recebido, o modelo lê seu próprio catálogo e decide qual habilidade abrir. A descrição é o que ele compara. Se a descrição for vaga, a habilidade nunca será ativada. Se for precisa, com palavras-chaves especificas, a habilidade será ativada exatamente quando deveria.
Essa única frase é o elemento mais importante de toda a habilidade. As pessoas geralmente gastam horas no corpo do texto da SKILL e dez segundos na descrição, e depois se perguntam por que sua SKILL nunca é usada.
Inverta essa proporção!
4. A Divulgação progressiva é o segredo do sucesso
Uma única habilidade pode conter dezenas de milhares de tokens de instruções e material de referência. Um agente com vinte habilidades poderia carregar centenas de milhares de tokens, múltiplas janelas de contexto completas, repletas de informações inúteis, antes mesmo do usuário digital algo.
A divulgação progressiva impede isso com três níveis de carregamento.
- Metadados de nível 1: O nome e descrição, sempre são carregados no inicio da sessão. Como disse anteriormente aproximadamente 100 tokens por habilidade.
- Instruções de nível 2: O corpo do arquivo SKILL.md, carregado somente quando a descrição corresponde a uma tarefa do usuário. Geralmente contém alguns mulhares de tokens.
- Referências de nível 3: Arquivos em references/, assets/ e scripts/. Carregados somente quando as instruções de nível 2 apontam explicitamente o agente para esses diretórios.
Um agente com vinte habilidades instaladas paga o mesmo custo inicial que um agente com apenas uma. Adicione uma 21° habilidade amanhã e as tarefas de ontem custarão o mesmo que custavam ontem.
O problema é que a divulgação progressiva só economiza tokens se você realmente usar os níveis. Se você incluir todos os exemplos no arquivo SKILL.md, o corpo do código infla para 10 mil tokens. Agora, cada tarefa que ativa a habilidade paga esse custo. Mantenha o arquivo SKILL.md conciso, mova casos extremos, exemplos longos e tabelas de referencias para a pasta references/. O agente os utiliza somente quando necessário.
5. O agente encaminha a consulta
Quando uma solicitação é recebida, o modelo faz o que você faria ao olhar para uma caixa de ferramentas. Lê os rótulos. Escolhe a ferramenta certa e abre.
Você diz no prompt: “limpe este CSV bagunçado e remova as linhas duplicadas”. O modelo examina o catálogo de descrições. pdf-forms , baixa correspondência. brand-voice, baixa correspondência, data-clean: limpeza de CSV, remoção de duplicatas, nulos, alta correspondência. O corpo de data-clean é carregado. O trabalho começa.
Dois detalhes são importantes aqui.
A correspondência não é uma recuperação vetorial. O modelo decide diretamente a partir de descrições dentro do seu próprio contexto. Sem etapa de incorporação. Sem pontuação de similaridade. Sem camada de roteamento separada. O LLM é o roteador. A partida também é exclusiva. Apenas uma habilidade é ativada por tarefa. As outras permanecem em L1. Seus personagens nunca entram na janela de contexto. O custo de habilidades desnecessárias é essencialmente zero.
É isso que diferencia as habilidades das ferramentas MCP ou das chamadas de função. As ferramentas estão sempre carregadas, sempre visíveis e sempre pagas. As habilidades, por sua vez, são carregadas somente quando relevantes.
5. Composição sem excesso de contexto
Amplie a escala. Um agente, oito habilidades instaladas. Três tarefas diferentes são executadas ao longo de uma sessão.
As habilidades que o agente não utilizou permanecem no nível 1 (L1). Cada uma custa aproximadamente 100 tokens, não possui corpo e não tem referências o custo do corpo é pago apenas nas tarefas que o exigem.
O padrão importa além do contexto econômico.
As equipes podem implementar funcionalidades de forma independente. A equipe de dados é responsável pela limpeza de dados e pelo executor de SQL. A equipe de design é responsável pela identidade visual da marca e pela criação da apresentação. A Equipe de plataforma configura o agente. Ninguém coordena. Ninguém mescla prompts. Ninguém reconstrói o prompt do sistema a cada nova funcionalidade implementada.
As Skills estão fazendo pelo agentes o que o npm fez pelo JavaScript: unidades pequenas, focadas e combináveis por trás de uma interface clara. O gerenciador de pacotes venceu o JavaScript. O mesmo formato vai vencer os agentes.
6. Com habilidades de agente vs sem habilidade de agente
Ao juntar as cinco partes, a diferença entre um agente desenvolvido com habilidades e um desenvolvido sem elas é tão nítida que cabe em uma unica página.
7. Conclusão
Se você desenvolve agentes e ainda não escreveu uma skill para eles, escolha um fluxo de trabalho que você realiza semanalmente. Escreva uma skill para ele. Uma pasta, um arquivo SKILL.md, versionando-o no Git. Observe o agente ativá-la.
O formato consiste simplesmente em arquivos. A vantagem é enorme.
Comece hoje, uma habilidade, um fluxo de trabalho e veja as mudanças.
