Antes dos tópicos, uma visão de cima. Um SKILL.md de produção não é uma parede de texto: é um documento com seções nomeadas, cada uma respondendo a uma pergunta do Claude na hora de executar. O diagrama abaixo mostra a espinha dorsal do arquivo que vamos dissecar.
A espinha dorsal do SKILL.md — ilustrativo. Cada seção alimenta a página final.
Conteúdo detalhado
🗺️ A promessa: "What This Skill Does"
A primeira seção de conteúdo do arquivo é um único parágrafo, mas é o parágrafo mais importante. Ele define a saída de forma concreta: "uma página HTML interativa, autossuficiente, com tema claro/escuro, rotas de voo animadas, agenda dia a dia, cartões de voo expansíveis, checklists com persistência em localStorage e navegação multi-viagem". E fecha com a frase que carrega toda a filosofia: "parece um app de viagem premium — não um documento".
🎯 O contrato em uma frase
Toda skill madura começa dizendo, sem rodeios, o que vai entregar. Esse parágrafo é um contrato em três níveis:
- •Forma da saída: um arquivo HTML — não um PDF, não uma resposta em texto.
- •Funcionalidades: a lista de recursos vira um checklist implícito que o Claude tenta cumprir.
- •Sensação: "app premium, não documento" é a régua de qualidade.
Trecho real do SKILL.md
## What This Skill Does
Generates a stunning, interactive HTML travel
itinerary — a single self-contained file with
dark/light theme toggle, animated flight paths,
interactive day-by-day schedule, expandable
flight cards ... and multi-trip navigation.
The output looks like a premium travel app —
not a document.
💡 Dica prática
Quando escrever a sua skill, force-se a descrever a saída em uma frase verificável. Se você não consegue, o Claude também não vai conseguir. "Gera algo útil sobre viagens" é ruim; "gera um HTML interativo com agenda, voos e orçamento" é um alvo.
💬 O Setup Flow conversacional
Aqui está o coração da skill, e ela faz questão de marcar: "Setup Flow — CRITICAL". Antes de gerar QUALQUER coisa, o Claude precisa percorrer um processo de descoberta conversacional em quatro passos. Essa é a razão de a saída parecer mágica: ela é construída sobre dados reais da vida do usuário, não sobre suposições.
Detalhes básicos da viagem
As perguntas-âncora
Para onde vai, em que datas, de onde parte, se é por um evento específico, e quem viaja. Cinco perguntas que delimitam o resto da conversa.
Checagem de integrações
"ask every time"
Oferecer puxar dados reais de e-mail, agenda, Drive, mensagens e URLs. Detalhamos no Tópico 3 — é o que distingue assistente de gerador de texto.
Detalhes profundos (gaps)
Preencher o que faltou
Com base no que já reuniu, perguntar sobre voos, hospedagem, eventos, transporte, pets, orçamento, atividades e requisitos especiais — só o que está em branco.
Confirmar & gerar
O portão antes da saída
Mostrar um resumo de tudo que foi reunido e confirmar antes de construir. Só então a página HTML é gerada.
📊 Por que "coletar antes de gerar" funciona
- Especificidade: dados reais produzem uma página que parece feita para aquela viagem, não um molde.
- Confiança: ao confirmar o resumo, o usuário corrige erros antes de gastar tokens gerando o HTML inteiro.
- Ordem: os passos vão do mais barato (perguntas) ao mais caro (gerar), reduzindo retrabalho.
🔌 Integrações via MCP: dados reais
O Passo 2 do setup é onde a skill ganha superpoderes. Ela instrui o Claude a oferecer — toda vez — checar fontes de dados do usuário: e-mail, agenda, Drive/Docs, Slack/mensagens, URLs e Notion. Se o usuário autorizar, o Claude usa as ferramentas MCP correspondentes (Gmail, Google Calendar, Google Drive) para puxar confirmações de voo, reservas e tickets de evento direto para o documento.
✓ O que FAZER
- ✓Oferecer a integração e esperar a autorização do usuário.
- ✓Usar a ferramenta MCP certa para cada fonte (Gmail para e-mail, Calendar para agenda).
- ✓Preencher o documento com os dados reais que voltarem.
- ✓Cair de volta nas perguntas (Passo 3) para o que a integração não cobriu.
✗ O que NÃO fazer
- ✗Acessar e-mail ou agenda sem perguntar.
- ✗Inventar números de voo ou reservas quando não há dados.
- ✗Pular a oferta porque "deve dar trabalho" — a skill diz "ask every time".
- ✗Misturar dados de placeholder com dados reais sem rotular.
As fontes que a skill oferece checar
💡 Dica prática
A frase da skill, "I can pull in real data to make this way more useful", é um modelo de copy. Ela explica o benefício antes de pedir permissão — o usuário entende o porquê e tende a dizer sim. Copie esse padrão nas suas skills com integração.
📦 Output Format: um arquivo, zero dependências
Curtíssima, mas decisiva. A seção "Output Format" amarra a saída com regras explícitas: um único HTML autossuficiente, com todo o CSS num <style> e todo o JS num <script>; imagens como data URIs base64 ou emoji; nenhuma dependência externa além do Google Fonts (Inter); e um nome de arquivo padronizado.
Trecho real do SKILL.md
## Output Format
Generate a single self-contained HTML file.
All CSS inline in <style>. All JS inline in
<script>. Images as base64 data URIs or emoji
fallbacks. No external dependencies except
Google Fonts (Inter).
Save as travelwings-{destination}.html
📊 O que cada restrição evita
- "Single file": evita arquivos espalhados que o usuário precisa juntar.
- "Inline CSS/JS": evita links para folhas/scripts que quebram ao mover o arquivo.
- "base64 / emoji": evita imagens que não carregam offline.
- "No external deps": evita dependências de CDN que somem com o tempo.
⚠️ Atenção
Sem uma seção de Output Format, o Claude tende a "ajudar demais" — propondo um projeto com várias pastas, um framework, um build. Para uma skill que gera um artefato para o usuário final, isso é o oposto do que se quer. Restringir é projetar.
🧩 Example Sections: a planta da página
Esta seção lista 13 blocos sugeridos para a página — hero, banner de evento, stats, mapa de rota, voos de ida, hotel, pets, agenda dia a dia, voos de volta, orçamento, checklists, rodapé e tema. Mas o detalhe que importa está entre parênteses: "adapt per trip". É uma planta, não uma camisa de força.
✓ Como a lista ajuda
- ✓Dá ao Claude uma ordem de referência dos blocos.
- ✓Lembra de seções fáceis de esquecer (rodapé, checklists).
- ✓Marca quais são condicionais ("if attending an event", "if applicable").
✗ O que evitar
- ✗Despejar todos os 13 blocos mesmo sem dados para eles.
- ✗Criar uma seção de pets numa viagem sem pet.
- ✗Tratar a ordem sugerida como obrigatória e rígida.
Os 13 blocos sugeridos (adapt per trip)
💡 Dica prática
"Adapt per trip" é uma das duas palavras mais poderosas numa skill de geração. Sempre que listar blocos, marque o que é condicional. Assim você dá estrutura sem produzir páginas infladas com seções vazias.
⭐ Key Principles: a bússola
A seção final são seis princípios curtos que resumem o espírito da skill. Enquanto os passos dizem o quê fazer, os princípios dizem como decidir quando a situação não estava no roteiro. São a regra de bolso do Claude.
🧭 Os seis princípios
- 1.Real data > placeholder data. Sempre tentar puxar dos dados reais primeiro.
- 2.Ask before assuming. A conversa de setup é o que dá valor.
- 3.One file, zero dependencies. Tudo autossuficiente.
- 4.Feel like a premium app, not a document. A régua de qualidade.
- 5.Interactive > static. Checklists salvam estado, dias clicam, voos expandem.
- 6.Colour-code everything. Azul ida, verde confirmado, laranja volta, lavanda conexão, dourado evento.
📊 Passos vs Princípios
- Passos cobrem o caminho feliz: faça A, depois B, depois C.
- Princípios cobrem os imprevistos: e se faltar um dado? E se houver conflito? Decida pela régua.
- Juntos, eles tornam a skill robusta — funciona mesmo fora do roteiro previsto.
💡 Dica prática
Bons princípios são curtos e oponíveis: cada um descarta uma alternativa concreta ("real > placeholder" descarta inventar dados). Se um princípio seu não exclui nada, ele é só decoração — reescreva.
Exercícios práticos
1. Mapeie as seções
Abra qualquer skill que gere um artefato e identifique: onde está a promessa? Existe um setup flow? Há uma seção de Output Format? Há princípios? Anote o que falta.
2. Escreva a promessa
Em uma frase verificável, descreva a saída de uma skill que você gostaria de ter. Submeta a frase ao teste: dá para checar se a saída cumpriu?
3. Crie um SKILL.md rodável
Salve o arquivo abaixo como ~/.claude/skills/menu-planner/SKILL.md, reinicie o Claude Code e digite /menu. Veja a skill conduzir o próprio setup flow.
---
name: menu-planner
description: Generates a self-contained HTML weekly
meal plan. Trigger on "/menu", "plan my meals",
"weekly menu", "meal prep". Asks about diet,
people, budget and pantry BEFORE generating.
---
# Menu Planner
## What This Skill Does
Generates a single self-contained HTML weekly meal
plan: 7 day cards, a shopping list grouped by aisle,
a budget total, and a print button. Looks like an
app, not a document.
## Setup Flow — CRITICAL
Before generating, ask:
1. How many people, and any diets/allergies?
2. Budget for the week?
3. What's already in the pantry? (offer to read a
note/doc if they have one)
4. Confirm a summary, THEN generate.
## Output Format
One HTML file. CSS in <style>, JS in <script>.
No external deps except Google Fonts (Inter).
Save as menu-{week}.html.
## Key Principles
1. Ask before assuming.
2. One file, zero dependencies.
3. Interactive > static (check off items, save state).
4. Colour-code by meal type.
🎯 Resumo do Módulo
Próximo Módulo:
2.2 — Setup flow, design system e saída: do prompt à página HTML