📂 Progressive disclosure & estrutura

Progressive disclosure (revelação progressiva) é um princípio emprestado do design de interfaces: mostre primeiro só o essencial e revele o detalhe apenas quando ele for necessário. Numa skill, isso significa que o SKILL.md carrega o fluxo principal, e o conhecimento profundo fica guardado em arquivos que só são lidos sob demanda.

A pasta references/ guarda o conhecimento profundo da skill: templates HTML, design systems, tabelas de cores, checklists, exemplos longos. São coisas que tornariam o SKILL.md gigantesco se ficassem inline — e que nem toda execução precisa.

minha-skill/
├── SKILL.md              ← enxuto: fluxo + roteamento
└── references/
    ├── DESIGN-REFERENCE.md   ← paleta, componentes, tokens
    ├── TEMPLATE.md           ← esqueleto da saída
    └── CHECKLIST.md          ← revisão antes de entregar

Quando uma tarefa tem lógica determinística — filtrar dados, transformar um arquivo, chamar uma API com regras fixas —, é melhor escrever um script e fazer a skill executá-lo, em vez de pedir ao Claude para reinventar a lógica a cada chamada. Código roda igual sempre; prosa regenerada, não.

## Workflow
1. Ask the user for the leads CSV path.
2. Run `python scripts/qualify_leads.py <path>` to score each lead.
3. Read the script's JSON output and summarize the top 10.

# A lógica de scoring vive no script — não é regenerada
# em cada execução. O Claude orquestra, o código calcula.

assets/ guarda os recursos estáticos que a saída usa ou referencia: fontes, imagens, ícones, um exemplo de saída pronto, um arquivo de configuração. A ideia é manter a skill autocontida — tudo que ela precisa viaja junto, então ela funciona igual em qualquer máquina.

Esta é a regra de ouro da estrutura: o SKILL.md é um roteador, não uma enciclopédia. Ele deve conter o fluxo, as decisões e as regras — e apontar para os detalhes, não despejá-los. Um SKILL.md inchado paga o preço em contexto a cada disparo.

Ter pastas de apoio só funciona se o SKILL.md souber quando abrir cada uma. O padrão é simples e poderoso: uma instrução condicional do tipo "leia references/X.md quando for fazer Y". Isso transforma um amontoado de arquivos numa skill que se navega sozinha.

## Quando ler cada arquivo

| Se você vai...              | Leia primeiro              |
|-----------------------------|----------------------------|
| construir a página de saída | references/DESIGN.md       |
| revisar antes de entregar   | references/CHECKLIST.md    |
| calcular o score            | (rode scripts/score.py)    |

Não leia tudo de uma vez — abra cada arquivo só na etapa
que precisa dele.

🧰 Prompts copiáveis

Use estes prompts para refatorar suas skills aplicando progressive disclosure.

Aqui está meu SKILL.md: <cole>. Aponte quais blocos são
"conhecimento de consulta" (tabelas, templates, exemplos longos)
que deveriam sair para references/, e quais blocos são fluxo/regras
que devem ficar. Justifique cada um.

Para uma skill que faz <descreva>, proponha a árvore de pastas
(SKILL.md + references/ + scripts/ + assets/) e diga, para cada
arquivo, o que ele contém e em que etapa do workflow é lido.

Escreva uma seção "Quando ler cada arquivo" para minha skill,
em forma de tabela (condição → arquivo a abrir), deixando claro
que os arquivos só devem ser carregados sob demanda.

📤 Exemplo de saída

Um SKILL.md enxuto que delega para arquivos de apoio — o padrão de progressive disclosure em ação.

---
name: invoice-builder
description: Builds a clean PDF-ready HTML invoice. Use when the
  user wants to "create an invoice", "bill a client", or /invoice.
---

# Invoice Builder

## Workflow
1. Collect client, items, amounts, due date.
2. When building the layout, read `references/TEMPLATE.md`.
3. Before delivering, run `references/CHECKLIST.md`.

## Rules
- Never invent line items the user didn't provide.
- Totals must match the sum of the lines exactly.

## When to read each file
| If you are...        | Read first              |
|----------------------|-------------------------|
| building the layout  | references/TEMPLATE.md  |
| reviewing the output | references/CHECKLIST.md |

Load support files only at the step that needs them.

✏️ Exercícios práticos