📂 Progressive Disclosure

Progressive disclosure é um princípio de design de informação que diz: revele apenas o que o usuário (ou o modelo) precisa agora, e entregue o restante quando for necessário. No contexto de design de interface, isso significa esconder funcionalidades avançadas até que o usuário demonstre necessidade. No contexto de skills para LLMs, isso significa estruturar o arquivo para que o Claude processe apenas as seções relevantes à tarefa atual.

A analogia com menus de restaurante é precisa: você não recebe o manual inteiro de operações da cozinha ao pedir um prato. Você recebe o cardápio, faz um pedido, e a informação relevante flui sob demanda. Uma skill sem disclosure é o equivalente a entregar o manual da cozinha junto com o cardápio — sobrecarregar o modelo com informação que não se aplica ao pedido atual. O resultado é confusão, imprecisão e tokens desperdiçados.

Seções nomeadas com headers descritivos não são apenas organização visual — elas são a infraestrutura técnica que torna o progressive disclosure possível. Quando uma skill tem seções com títulos como "## Criando um Workflow do Zero", "## Depurando Expressões" e "## Referências de Nodes", o Claude pode identificar qual seção é relevante sem precisar ler o conteúdo de todas elas. É a diferença entre uma biblioteca com catálogo e uma com pilhas aleatórias de livros.

A qualidade dos títulos importa tanto quanto a qualidade do conteúdo. Um header genérico como "## Informações" ou "## Detalhes" não comunica nada sobre o conteúdo da seção. Um header específico como "## Como estruturar o frontmatter YAML" ou "## Resolvendo colisões de trigger" é um índice preciso que o Claude usa para navegar a skill de forma eficiente e focada.

Uma skill bem estruturada segue uma hierarquia de seções onde a informação mais universal fica no topo e a mais específica fica embaixo. O frontmatter (YAML) sempre vem primeiro e contém os metadados de seleção. A seção de visão geral vem logo depois e estabelece o contexto essencial. As seções de casos de uso específicos seguem em ordem de frequência — os casos mais comuns primeiro, os mais raros por último.

A profundidade de hierarquia ideal é dois níveis: headers H2 para seções principais e H3 para subseções dentro de cada caso de uso. Hierarquias mais profundas criam complexidade sem benefício proporcional. Menos de dois níveis resulta em seções monolíticas que não se beneficiam do disclosure. Dois níveis é o ponto ideal de equilíbrio para a grande maioria das skills.

A diferença entre uma skill monolítica e uma skill com disclosure não é óbvia na leitura do arquivo — ela aparece no uso. Uma skill monolítica força o Claude a processar 800 palavras de instruções para responder uma pergunta simples que precisaria de apenas 50 palavras de contexto. Uma skill com disclosure direciona o Claude para a seção certa imediatamente, reduzindo o processamento desnecessário e aumentando a precisão. O mesmo conteúdo, estruturado diferente, produz resultados muito melhores.

O exemplo mais revelador é quando você pede algo simples e a skill entrega uma resposta que mistura instruções de múltiplos casos de uso — sinal claro de que o modelo está processando seções irrelevantes. Com disclosure bem implementado, o Claude identifica exatamente qual sub-caso se aplica e trabalha apenas com aquele contexto, produzindo respostas mais limpas, mais focadas e mais acionáveis.

A leitura seletiva de seções pelo Claude não é aleatória — ela segue heurísticas baseadas no contexto da conversa e nas pistas fornecidas pelo texto do prompt. Seções com títulos que correspondem semanticamente às palavras-chave no prompt do usuário têm maior probabilidade de ser lidas com atenção. Títulos de seção são, na prática, palavras-chave de relevância que o Claude usa para priorizar onde concentrar processamento.

Você pode tornar a priorização mais explícita adicionando flags no início das seções: "Leia esta seção quando o usuário pedir para criar um workflow do zero." ou "Esta seção se aplica somente a casos de debug de expressões." Essas instruções explícitas de quando ler eliminam a ambiguidade e garantem comportamento mais previsível, especialmente em skills com muitas seções ou sub-casos similares.

A relação entre contexto irrelevante e hallucination é direta: quando o Claude processa instruções que não se aplicam ao caso em questão, ele frequentemente tenta "usar" esse contexto de alguma forma — criando conexões forçadas, misturando frameworks de casos diferentes ou elaborando detalhes que não existem para preencher gaps criados pela confusão de contexto. Contexto focado elimina a oportunidade para hallucinations porque não há material irrelevante para o modelo inventar conexões.

O efeito é especialmente visível em skills de domínio técnico com muitas regras e exceções. Uma skill de código sem disclosure que descreve múltiplas linguagens e frameworks resulta em respostas que misturam convenções de Python com JavaScript, ou que aplicam regras de uma biblioteca a outra. Com disclosure bem implementado, o Claude trabalha dentro de um espaço de contexto preciso e delimitado, com muito menos margem para erros por confusão de frameworks.