🧠 O problema: a memória de trabalho é limitada
Novo aqui? Contexto (ou janela de contexto) é a memória de trabalho do agente — tudo o que ele consegue "enxergar" de uma vez enquanto pensa e decide: sua conversa, os arquivos abertos, e qualquer texto carregado na sessão. É finita. Não infinita, não elástica — um espaço limitado que precisa ser usado com cuidado, do mesmo jeito que uma mesa de trabalho só cabe tantos papéis abertos ao mesmo tempo.
Se toda skill instalada fosse lida inteira, do primeiro ao último caractere, toda vez que o agente pensasse em qualquer coisa, o problema é óbvio: com 20 skills instaladas, boa parte do contexto já teria ido embora antes de você sequer terminar de digitar o seu pedido. O agente ficaria mais lento, mais caro, e mais confuso — cheio de instruções de skills que nem eram relevantes pra tarefa atual.
⚠️ Atenção
Esse cenário — carregar tudo sempre — é exatamente o que o formato de skill evita. A solução não é "ter poucas skills". É carregar cada uma na medida certa, no momento certo. É esse o assunto do módulo inteiro.
🔍 Por dentro
Pense numa biblioteca gigante. Se cada vez que você precisasse de um livro específico, a biblioteca inteira fosse colocada em cima da sua mesa, você nunca acharia nada. O jeito que funciona de verdade: um catálogo enxuto (o fichário na entrada) te ajuda a achar o livro certo, e só esse livro sai da estante.
1️⃣ Nível 1 — o índice, sempre carregado
O Nível 1 é só o name e
a description do front matter
(que você viu no módulo 3.1) — algo em torno de 100 tokens por skill. Isso é muito barato, e é justamente
o que o agente varre pra decidir, a cada pedido novo, se alguma skill instalada serve pra tarefa atual.
É como o índice de um livro: uma linha por capítulo, suficiente pra saber se aquele capítulo é o que
você procura, sem ler o capítulo inteiro pra descobrir.
Legenda: o custo cresce de dentro pra fora — o centro (Nível 1) é minúsculo e sempre presente; cada anel externo só entra em cena se o anterior decidiu que era necessário.
💡 Dica Prática
É por isso que o custo de ter uma skill instalada é quase zero — mesmo com 20 instaladas, o agente só varre 20 fichas curtas. O custo real só aparece quando uma delas de fato é usada.
2️⃣ Nível 2 — o capítulo, só quando dispara
O Nível 2 entra em cena só quando a skill é de fato disparada
— ou seja, quando a description do Nível 1 bateu com o seu pedido. Aí sim o agente carrega o
skill.md inteiro: o corpo
com o passo a passo completo, na faixa de 1.000 a 2.000 tokens. É o capítulo do livro que você de fato
escolheu ler — depois de olhar o índice e decidir que era esse.
Início da sessão
Todas as descriptions de Nível 1 já estão disponíveis pro agente comparar com qualquer pedido.
Você faz um pedido que bate com uma delas
Nesse exato instante — nem antes, nem "por garantia" — o Nível 2 daquela skill específica entra no contexto.
As outras 19 skills continuam só no Nível 1
Elas não custaram nada extra — permanecem só como ficha, prontas caso apareça um pedido que combine com elas.
🔍 Por dentro
É o mesmo princípio de leitura sob demanda que já apareceu no módulo 2.4 com o padrão cheat sheet: instrução curta que só puxa mais detalhe quando precisa. Skills aplicam esse princípio de forma padronizada e embutida no próprio formato.
3️⃣ Nível 3 — o apêndice, sob demanda
O Nível 3 é o que fica nas pastas references/ e
scripts/ do módulo 3.1 — e só é lido se o
passo a passo do Nível 2 mandar explicitamente ("se precisar do detalhe X, leia o arquivo Y"). É o apêndice
técnico do livro: a maioria dos leitores nunca chega lá, mas quando alguém precisa, está exatamente onde
deveria estar.
O tamanho do Nível 3 é variável — pode ser um arquivo de 200 tokens ou uma referência de 5.000. Mas isso não importa pro custo do dia a dia, porque na esmagadora maioria das execuções ele nunca é aberto.
✓ skill.md enxuto
- ✓Corpo com os passos essenciais, cabe numa tela
- ✓Empurra a tabela de códigos, exemplos extensos e casos raros pra
references/ - ✓Custo do Nível 2 fica sempre próximo de 1-2 mil tokens
✗ skill.md gigante
- ✗Cola tudo no corpo — tabela, exemplos, casos raros, tudo junto
- ✗Toda execução carrega o material inteiro, mesmo quando 90% não é usado
- ✗O Nível 2 vira, na prática, um Nível 3 disfarçado — perde a vantagem do carregamento em camadas
🚀 Por que 20 skills instaladas não deixam o agente lento
Junte os três níveis e a resposta pra pergunta que abriu este módulo fica direta: o custo de ter uma skill instalada é quase zero (só o Nível 1, ~100 tokens cada). O custo de usar uma skill é proporcional só ao que realmente foi acionado — Nível 2 sempre, Nível 3 raramente. Ter 20 skills instaladas e usar uma só custa, no fim das contas, quase o mesmo que ter só essa uma instalada, mais um punhado de fichas de índice das outras 19.
🎯 Conceito Principal
- •Ter uma skill instalada ≠ pagar o custo dela sempre. Isso já é resolvido pelo Nível 1.
- •Usar uma skill custa proporcional ao que ela realmente puxou — Nível 2 quase sempre, Nível 3 raramente.
- •É seguro instalar muitas skills específicas em vez de poucas skills genéricas gigantes.
💡 Dica Prática
Não hesite em ter uma skill separada pra cada processo pequeno da sua rotina, em vez de uma skill "faz-tudo". Skills específicas com descriptions precisas disparam melhor e mantêm o Nível 2 curto — o custo de ter mais uma instalada é irrelevante.
✍️ Escrevendo uma description que aciona o Nível 1 direito
Como o Nível 1 é o único filtro que decide se o Nível 2 vai ou não ser carregado, a description precisa carregar dois trabalhos ao mesmo tempo: dizer o que a skill faz e quando usá-la, com palavras próximas do jeito real que você pede a tarefa. O módulo 3.4 aprofunda esse assunto — aqui fica o exemplo mínimo funcional.
---
name: <nome-da-sua-skill>
description: <o que ela faz>, use quando o usuário pedir
"<frase 1 que você diria>", "<frase 2>" ou "<frase 3>".
---⚠️ Atenção
Description vaga demais ("ajuda com relatórios") compete mal contra outras skills parecidas e engorda a decisão do Nível 1 sem necessidade. Description específica demais ("gera relatório de vendas de outubro de 2026") só dispara naquele mês exato. O equilíbrio certo é o assunto do módulo 3.4.
Exercício mental: se você tem 20 skills instaladas e nenhuma delas é usada nesta sessão, quantos tokens isso custa aproximadamente?