🧮 O problema do contexto
Toda conversa com o Claude tem uma janela de contexto finita — tokens que somem quando acabam. Carregar todas as skills de uma vez seria um desastre para a eficiência e a qualidade das respostas.
A janela de contexto de um LLM é como a RAM de um computador: finita, valiosa e cara para usar. Se o Claude carregasse o conteúdo completo de cada skill instalada a cada conversa, esgotaria o contexto antes mesmo de você digitar a primeira palavra.
A solução é a divulgação progressiva: carregar só o mínimo necessário e ir buscando mais conforme a complexidade da tarefa exige.
name+description na memória- ✓ Dezenas de skills instaladas sem custo de contexto
- ✓ Respostas mais rápidas e focadas
- ✓ Conteúdo profundo só quando realmente necessário
- ✓ Contexto livre para o código e conversa do usuário
- ✗ Cada skill carrega centenas de tokens sempre
- ✗ 20 skills = 16.000 tokens queimados antes de começar
- ✗ Degradação de qualidade em conversas longas
- ✗ Conflitos entre instruções de skills não relevantes
1️⃣ Camada 1: name + description sempre na memória
O nível mais leve da divulgação progressiva. Apenas o name e a description de cada skill ficam disponíveis o tempo todo — custo mínimo, visibilidade máxima.
O Claude precisa saber que uma skill existe e para que serve — mas não precisa dos detalhes de como executá-la antes de decidir se ela é relevante. O name é o identificador; a description é o gatilho de ativação.
É como o índice de um livro: você lê o índice para decidir qual capítulo abrir — não lê tudo de uma vez.
Como o Claude leu no narration-template.sh (cena s3): "A descrição é a parte mais importante de todas. É o que o Claude lê para decidir quando usar aquela skill. Quanto mais clara e específica, melhor o gatilho."
Ao abrir o Claude Code, o sistema lê automaticamente todos os SKILL.md encontrados nas pastas .claude/skills/ (projeto e global) e indexa apenas name + description de cada um.
Com 20 skills, o custo total é de ~1.000 tokens — um porcentagem ínfima da janela. O Claude sabe que essas ferramentas existem sem ter consumido nada relevante do contexto.
A qualquer momento da conversa, o Claude compara o pedido com as descriptions disponíveis. Se houver match, avança para a Camada 2.
2️⃣ Camada 2: SKILL.md completo carrega on match
Quando a tarefa do usuário combina com a description de uma skill, o Claude carrega o conteúdo completo do SKILL.md — instruções, fluxo, regras e identidade visual.
Ao detectar que o pedido do usuário se enquadra no escopo descrito pela description, o Claude executa o equivalente a "abrir o livro no capítulo certo". Todo o SKILL.md é carregado no contexto neste momento — e apenas neste momento.
- ✓ Inclua fatos reais: valores como
LEAD=0.5,TAIL=0.9 - ✓ Organize em seções claras com headers Markdown
- ✓ Separe "regras de ouro" de instruções opcionais
- ✓ Inclua links para os arquivos de referência (Camada 3)
- ✗ Não coloque conteúdo de referências longas direto no SKILL.md
- ✗ Não repita o que está na description no corpo do arquivo
- ✗ Não omita os valores exatos (o Claude precisa de números reais)
- ✗ Não torne o SKILL.md maior que ~1.000 tokens sem necessidade
Pense no SKILL.md como o briefing que você daria a um novo membro da equipe: completo o suficiente para executar a tarefa, conciso o suficiente para caber numa reunião de 5 minutos. Detalhes técnicos profundos ficam nas referências (Camada 3).
3️⃣ Camada 3: referências e scripts só sob demanda
O nível mais profundo: arquivos grandes como templates de composição, paletas detalhadas e scripts de shell ficam em references/ e são lidos apenas quando a tarefa exige.
O narration-template.sh tem ~100 linhas. O composition-template.mjs tem ~300 linhas. Embutir esses arquivos no SKILL.md consumiria 5.000+ tokens toda vez que a skill fosse ativada — mesmo em tarefas que não precisam deles.
Carregado quando o usuário pede para gerar narração TTS — contém os comandos npx hyperframes tts, a voz pf_dora --speed 0.98 e o loop ffprobe para medir durações.
Carregado quando o usuário pede para criar ou adaptar o build-index.mjs — contém a estrutura de cenas, constantes LEAD=0.5, TAIL=0.9, FADE=0.45 e a cena final de CTA do INEMA.CLUB.
Carregado quando o Claude encontra erros de layout durante npx hyperframes lint ou inspect — lista os problemas conhecidos e suas correções.
Carregado especificamente no passo 3 do fluxo, quando é hora de baixar os arquivos .woff2 (subset latin) para assets/fonts/fonts.css.
O SKILL.md menciona cada arquivo da Camada 3 com o caminho exato (ex.: [narration-template.sh](scripts/narration-template.sh)). Isso permite ao Claude localizar e carregar o arquivo correto quando necessário, sem precisar adivinhar o nome.
📈 Por que isso escala com dezenas de skills
Com divulgação progressiva, você pode instalar 30, 50, 100 skills sem degradar a qualidade das respostas. O custo de contexto cresce de forma linear e controlada — não exponencial.
| Skills instaladas | Sem progressiva | Com progressiva | Economia |
|---|---|---|---|
| 5 skills | ~4.000 tokens | ~250 tokens | 94% menos |
| 20 skills | ~16.000 tokens | ~1.000 tokens | 94% menos |
| 50 skills | ~40.000 tokens | ~2.500 tokens | 94% menos |
Uma biblioteca de 10.000 livros não ocupa mais espaço na sua cabeça do que uma de 10 — porque você não memoriza todos os livros, apenas sabe onde encontrá-los. Skills funcionam da mesma forma com divulgação progressiva.
Cada skill adicional acrescenta apenas ~50 tokens à Camada 1 (name + description). O custo marginal de uma nova skill é quase zero.
- ✓ Escreva descriptions únicas e precisas (sem sobreposição)
- ✓ Use TRIGGER/SKIP explícitos na description
- ✓ Mantenha SKILL.md ≤ 1.000 tokens, mova o resto para Camada 3
- ✓ Agrupe skills relacionadas em subpastas organizadas
- ✗ Descriptions vagas que ativam a skill errada (falso positivo)
- ✗ SKILL.md com 5.000+ tokens (pesa como 100 skills)
- ✗ Duas skills com descriptions sobrepostas
- ✗ Usar a pasta global para skills de projetos específicos
Skills globais (~/.claude/skills/) ficam disponíveis em todo projeto — use para ferramentas universais como video-explicativo. Skills de projeto (.claude/skills/) ficam disponíveis só naquele projeto — use para workflows específicos do cliente ou codebase.
🤔 Como o Claude decide qual skill ativar
O mecanismo de seleção de skills não é mágica: o Claude compara semanticamente o pedido do usuário com cada description disponível na Camada 1 e escolhe a que melhor se encaixa.
O Claude não faz uma busca literal por palavras-chave. Ele usa compreensão semântica para avaliar se a intenção do pedido corresponde ao escopo descrito na description. Por isso "cria um vídeo explicativo sobre Docker" aciona a skill video-explicativo mesmo sem usar essas palavras exatas.
Ex.: "quero fazer um vídeo curto mostrando como o SKILL.md funciona"
Verifica: video-explicativo → "cria vídeos explicativos HTML→MP4 com HyperFrames". ✓ Match de alta confiança. Verifica: formato-curso → "cria páginas HTML de curso". ✗ Não é o escopo aqui.
Carrega o SKILL.md completo de video-explicativo — instruções, fluxo, valores como pf_dora --speed 0.98, paleta #0D1321, regras de ouro.
Segue o fluxo da skill: Roteiro → Projeto → Fontes → Narração → Composição → Validar → Render. Só busca Camada 3 quando o passo específico exige.
Se duas skills têm descriptions sobrepostas, o Claude pode ativar a errada ou ficar em conflito. Solução: use as cláusulas TRIGGER when e SKIP na description para delimitar o escopo com precisão.
Antes de finalizar uma skill, peça ao Claude: "Se eu pedisse X, qual skill você ativaria?". Se a resposta for a skill errada, reescreva a description com mais especificidade — adicione exemplos de gatilhos no campo TRIGGER e exclusões no campo SKIP.
✅ Resumo do Módulo 1.3
- ✓A janela de contexto é finita — carregar tudo seria ineficiente e contraproducente.
- ✓Camada 1:
name + descriptionficam sempre na memória — custo de ~50 tokens por skill. - ✓Camada 2: o SKILL.md completo é carregado on match — instruções, fluxo e regras de ouro.
- ✓Camada 3: referências e scripts (
references/,scripts/) só sob demanda — quando o passo específico exige. - ✓Com divulgação progressiva, 50 skills custam ~94% menos contexto do que sem ela.
- ✓O Claude usa matching semântico + TRIGGER/SKIP para decidir qual skill ativar.