📂 Progressive disclosure & structure

Progressive disclosure (progressive disclosure) is a principle borrowed from interface design: show only the essentials first, and reveal details only when needed. In a skill, this means that the SKILL.md loads the main flow, and the deep knowledge stays stored in files that are read only on demand.

The folder references/ holds the deep knowledge of the skill: HTML templates, design systems, color tables, checklists, long examples. These are things that would make the SKILL.md huge if they were inline—and not every run needs them.

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

When a task has deterministic logic — filtering data, transforming a file, calling an API with fixed rules — it's better to write a script and make the skill run it, instead of asking Claude to reinvent the logic on every call. Code runs the same way every time; regenerated prose doesn't.

## 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/ holds the static resources that the skill uses or references: sources, images, icons, a ready-made example output, a configuration file. The idea is to keep the skill self-contained — everything it needs travels with it, so it works the same on any machine.

This is the golden rule of the structure: the SKILL.md is a a router, not an encyclopedia. It should contain the workflow, decisions, and rules —and point to for the details, don't dump them all. A bloated SKILL.md costs you context with every invocation.

Having support folders only works if the SKILL.md know when to open each one. The pattern is simple and powerful: a conditional instruction like "read references/X.md when you’re going to do Y". This turns a pile of files into a skill you can navigate on its own.

## 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.

🧰 Copyable prompts

Use these prompts to refactor your skills using 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.

📤 Sample Output

One SKILL.md lean and delegates to supporting files—the progressive disclosure pattern in action.

---
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.

✏️ Practical exercises