🪜 Os 3 níveis de carregamento
O segredo das skills é o progressive disclosure: a informação é revelada em camadas, conforme o agente precisa. Em vez de jogar tudo no contexto de uma vez, a skill expõe primeiro só a metadata, depois o corpo, e por último os recursos pesados.
A ideia central
Quanto mais alto o nível, menos custa em contexto e mais frequente é o carregamento. Quanto mais baixo, mais conteúdo cabe — mas só entra quando realmente necessário. É isso que permite skills enormes funcionarem sem desperdiçar contexto.
① Nível 1 — metadata
O Nível 1 é só o name + description — cerca de 100 palavras que ficam SEMPRE no contexto do agente, junto com a metadata de todas as outras skills instaladas. É a vitrine: a partir dela o agente decide se vale a pena carregar o resto.
O que fica sempre carregado (Nível 1):
name: skill-creator description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill...
💡 Dica
Como o Nível 1 está sempre ligado, cada palavra custa contexto multiplicado por TODAS as skills. Mantenha ~100 palavras: descritivo o bastante para disparar, enxuto o bastante para não pesar.
② Nível 2 — corpo do SKILL.md
Quando a description bate com a situação, o agente carrega o corpo do SKILL.md — as instruções completas. A recomendação canônica é manter o corpo abaixo de 500 linhas. Ele só entra no contexto no momento do disparo, não antes.
A description dispara
O agente reconhece que a situação atual casa com o Nível 1.
O corpo é carregado
As instruções em Markdown entram no contexto e passam a guiar a resposta.
O agente age
Segue o corpo e, se preciso, busca recursos do Nível 3.
Por que <500 linhas
Corpos longos diluem a atenção do agente e desperdiçam contexto cada vez que disparam. Se o conteúdo crescer demais, mova detalhes para references/ (Nível 3) e deixe o corpo apenas com o essencial e ponteiros.
③ Nível 3 — bundled resources
O Nível 3 são os recursos empacotados: arquivos em scripts/, references/ e assets/. Tamanho ilimitado, carregados sob demanda. O detalhe poderoso: scripts executam sem carregar o código no contexto — o agente só recebe o resultado.
✗ Tudo no corpo
- ✗Tabelas gigantes e docs inteiros no SKILL.md
- ✗Código colado no Markdown para o agente "ler e rodar mentalmente"
- ✗Contexto estourado a cada disparo
✓ Recursos no Nível 3
- ✓Docs longos em references/, lidos só quando precisa
- ✓Scripts em scripts/ que rodam de verdade, sem ocupar contexto
- ✓Corpo enxuto que aponta para os recursos
No corpo, aponte para o recurso (não cole o conteúdo):
Para converter o arquivo, execute: python scripts/convert.py <input> Detalhes de configuração estão em references/config.md — leia se necessário.
💡 Dica
Sempre que uma tarefa for determinística (mesma entrada → mesma saída), prefira um script no Nível 3 a instruções no corpo. Mais confiável, mais barato e o código nem precisa entrar no contexto.
🎯 Escrevendo a description que dispara
Aqui está o ponto mais sutil de toda a anatomia: Claude tende a SUBDISPARAR skills. Por padrão ele é conservador e, na dúvida, não ativa. A correção é escrever uma description um pouco "pushy" — assertiva nos gatilhos, deixando claro quando usar.
✗ Tímida (subdispara)
"Pode ajudar com testes."
"Pode" e nenhum gatilho. O agente raramente vai ativar.
✓ Pushy (dispara)
"Escreve e revisa testes. Use SEMPRE que o usuário pedir testes, mencionar TDD, cobertura ou um bug a reproduzir."
O que + quando + gatilhos explícitos.
A fórmula da description que dispara:
description: [O QUE faz] + [QUANDO usar — "Use this skill when..."] + [GATILHOS concretos — exemplos, palavras-chave]
Calibre com near-misses
Para afinar, pense em queries que deveriam disparar e em near-misses que não deveriam. Se a skill ignora casos óbvios, fique mais pushy; se dispara em situações erradas, restrinja os gatilhos. Esse ajuste fino é o coração do loop de criação da Trilha 4.
🗂️ Organização por domínio
Quando uma skill cobre vários domínios, divida as referências por arquivo — references/aws.md, gcp.md, azure.md — para que o agente leia só o relevante. E em qualquer arquivo com mais de 300 linhas, adicione uma tabela de conteúdo no topo.
References divididas por domínio:
references/ ├── aws.md # só lido em tarefas AWS ├── gcp.md # só lido em tarefas GCP └── azure.md # só lido em tarefas Azure
Tabela de conteúdo no topo de um arquivo >300 linhas:
# Guia AWS ## Índice - [IAM & permissões](#iam) - [S3 & storage](#s3) - [Lambda & serverless](#lambda) - [Networking (VPC)](#vpc)
Por que isso economiza contexto
- •Um arquivo único de 900 linhas força o agente a carregar tudo. Três de 300 deixam ele pegar só um.
- •A tabela de conteúdo deixa o agente navegar até a seção certa sem reler o arquivo inteiro.
- •Domínios separados também facilitam manutenção: você edita azure.md sem tocar no resto.
💡 Dica final
Os três níveis + organização por domínio formam um sistema: description pushy no Nível 1 para disparar, corpo enxuto no Nível 2, recursos fatiados por domínio no Nível 3. É assim que skills como a azure-ai (358k installs) escalam sem perder precisão.
✅ Resumo do Módulo
Próximo:
Módulo 3.3 — ⭐ As Melhores Anatomias para Imitar: disseque o SKILL.md de skills campeãs e veja o que copiar de cada uma.