🪜 Progressive disclosure de verdade
Você já viu os 3 níveis no 3.2. Aqui colocamos em prática: o objetivo é que o agente carregue só o que precisa, quando precisa. Uma skill avançada é como um menu — o SKILL.md mostra as opções, e cada arquivo só entra no contexto quando aquela rota é escolhida.
A meta
Numa tarefa AWS, o agente lê aws.md e ignora gcp.md e azure.md. O contexto carrega um terço do conteúdo. É assim que skills como azure-ai (358k) cobrem dezenas de serviços sem estourar o contexto.
🗂️ references/ por domínio
O padrão canônico do skill-creator: quando uma skill cobre vários domínios, organize por variante e deixe o SKILL.md fazer a seleção. O agente lê apenas o arquivo de referência relevante.
estrutura de domain organization (do skill-creator):
cloud-deploy/
├── SKILL.md # workflow + seleção
└── references/
├── aws.md # lido só em tarefas AWS
├── gcp.md # lido só em tarefas GCP
└── azure.md # lido só em tarefas Azure
No corpo, o roteamento é explícito — uma tabela "se o domínio é X, leia Y":
roteamento no corpo do SKILL.md:
## Selecione o provedor | Provedor | Leia | |----------|---------------------| | AWS | references/aws.md | | GCP | references/gcp.md | | Azure | references/azure.md | Read ONLY the file for the user's provider.
💡 Pro tip
Um arquivo único de 900 linhas força o agente a carregar tudo. Três de 300 deixam ele pegar só um — economia de 66% de contexto. E manutenção fica trivial: você edita azure.md sem tocar no resto.
⚙️ scripts/ que executam sem contexto
A jogada mais poderosa do Nível 3: um script executa e o agente só recebe o resultado — o código nunca entra no contexto. Para tarefas determinísticas (mesma entrada → mesma saída), isso é mais confiável e mais barato do que instruir o agente a "raciocinar" o passo a passo.
✗ Instrução no corpo
- ✗"Faça parse do CSV, some a coluna 3, formate..."
- ✗O agente pode errar a aritmética
- ✗Gasta tokens raciocinando o óbvio
✓ Script no Nível 3
- ✓"Run
python scripts/sum.py" - ✓Resultado exato, sempre
- ✓Código não ocupa contexto
no corpo: aponte e execute, não cole o código:
## Steps 1. Run `python scripts/package_skill.py <path>` to bundle the skill into a .skill file. 2. The script prints the output path — return it. # o conteúdo de package_skill.py NUNCA entra # no contexto; só a saída do comando.
Sinal de extração
Se você nota o agente reescrevendo o mesmo helper em toda execução, esse é o sinal: escreva uma vez, ponha em scripts/, e mande a skill usá-lo. É exatamente o que o skill-creator recomenda no loop de iteração.
📑 Table-of-contents em arquivos >300 linhas
Regra do skill-creator: qualquer arquivo de referência com mais de 300 linhas ganha uma tabela de conteúdo no topo. Assim o agente navega direto à seção certa sem reler o arquivo inteiro.
índice no topo de um reference longo:
# Guia AWS ## Índice - [IAM & permissões](#iam) - [S3 & storage](#s3) - [Lambda & serverless](#lambda) - [Networking (VPC)](#vpc) ## IAM ...
💡 Pro tip
Se um reference passa de ~300 linhas com a TOC e ainda assim parece grande demais, é sinal de quebrá-lo em dois arquivos por subtema. TOC é o primeiro remédio; partição é o segundo.
📏 SKILL.md <500 linhas + hierarquia com pointers
A regra de ouro: mantenha o corpo abaixo de 500 linhas. Ao se aproximar do limite, não corte conteúdo — adicione uma camada de hierarquia com ponteiros claros sobre para onde o agente deve ir em seguida.
Identifique o que é detalhe
Edge cases, tabelas grandes e exemplos longos raramente precisam estar no corpo.
Mova para references/
Tire do corpo e ponha num arquivo de referência dedicado por subtema.
Deixe um pointer no corpo
"See references/schemas.md for the full schema" — diga quando ler.
pointers reais (estilo skill-creator):
See `references/schemas.md` for the full schema (including the `assertions` field). The references/ directory has more docs: - `references/schemas.md` — JSON structures - `references/eval-format.md` — eval layout
Por que o limite importa
O corpo entra inteiro no contexto a cada disparo. Corpos longos diluem a atenção do agente e custam tokens toda vez. Hierarquia com pointers paga o custo só quando o detalhe é realmente necessário.
🎨 assets/ e o checklist final
A pasta assets/ guarda arquivos usados no output: templates HTML, fontes, ícones, boilerplate. Diferente de references/ (que o agente lê para aprender), assets são preenchidos ou copiados para o resultado final — como o assets/eval_review.html que o skill-creator preenche com dados.
os três diretórios, papéis distintos:
scripts/ → executado (resultado no contexto) references/ → lido (aprende sob demanda) assets/ → preenchido (vai pro output final)
Checklist da skill multi-arquivo afiada
- ✓SKILL.md abaixo de 500 linhas, com pointers claros
- ✓references/ fatiado por domínio; agente lê só o relevante
- ✓TOC em todo reference acima de 300 linhas
- ✓Tarefas determinísticas viraram scripts/ que rodam sem contexto
- ✓assets/ só com arquivos que vão para a saída
- ✓Cada arquivo tem um ponteiro correspondente no corpo
💡 Dica final
Multi-arquivo bem feito é o que separa uma skill brinquedo de uma como azure-ai ou supabase. Com a anatomia dominada, a próxima fronteira é o loop de criação — testar, avaliar e otimizar a description — que é exatamente o tema da Trilha 4.
✅ Resumo do Módulo
Próximo:
Trilha 4 — ⚙️ Como Criar (o loop): capturar intent, draft, testar com prompts realistas, avaliar e otimizar a description até a skill ficar afiada.