Pré-visualização: Página HTML com Seleção para Comentários
Transforme qualquer plano, proposta, rascunho ou texto final em uma página HTML onde é possível "selecionar texto → adicionar comentário", abrindo-a no computador do usuário para que ele (ou seu cliente) revise. Após a revisão, clique em "Copiar tudo" e os comentários e marcações de checkbox serão convertidos em markdown, que pode ser colado de volta no chat para aplicar as alterações.
Onde está o arquivo desta skill
A pasta onde este arquivo está localizado é a pasta da skill (escrita como $SKILL_DIR abaixo). Defina-a antes de executar qualquer comando:
SKILL_DIR="${CLAUDE_SKILL_DIR:-$HOME/.claude/skills/preview}"
[ -f "$SKILL_DIR/scripts/md-to-preview.py" ] || SKILL_DIR="$(cd "$(dirname "$(find "$HOME/.claude/skills" .claude/skills -path '*/preview/scripts/md-to-preview.py' 2>/dev/null | head -1)")/.." && pwd)"
echo "$SKILL_DIR"
- Requer apenas Python 3.9 ou superior, usando apenas a biblioteca padrão — não é necessário pip.
- No macOS, use
python3; no Windows, se não houver o comandopython3, usepythonoupy. - Se a pasta da skill não for encontrada, pare e informe ao usuário para confirmar se a pasta
previewestá em~/.claude/skills/. Não crie uma funcionalidade de comentários separada.
| Arquivo | Finalidade |
|---|---|
scripts/md-to-preview.py | Gerador principal: converte md em página de pré-visualização |
scripts/convert/inject.py | HTML já diagramado: adiciona apenas a funcionalidade de comentários |
scripts/convert/visuals.py, flow.py, tables.py | Componentes visuais, fluxogramas, conversão de tabelas (chamados automaticamente pelo gerador) |
assets/preview-comment-overlay.html | Interface de comentários por seleção de texto |
assets/preview-tokens.css | Cores, fontes, espaçamento; personalize a aparência aqui |
assets/fonts/ | Fontes incluídas: Noto Sans TC, Geist, Geist Mono (licença SIL OFL) |
assets/example.md | Exemplo completo: uma proposta fictícia de projeto, utilizando todos os componentes |
Regra 1: Comentários sempre são por "seleção de texto"
Quando o usuário disser "adicione comentários" ou "versão com comentários", refere-se a um sistema como o Google Docs, onde você seleciona qualquer texto e adiciona um comentário — não a uma caixa de entrada ao lado de cada parágrafo. A interface de comentários desta skill é exatamente essa: use-a diretamente, sem criar outra.
Regra 2: Primeiro reescreva, depois gere a página
Primeiro, identifique o tipo de página
| Tipo | Exemplo | Como tratar |
|---|---|---|
| Explicativo | Planos, propostas, relatórios, comparações, páginas para aprovação | Reescreva conforme o guia abaixo para uma versão legível e, só depois, gere a página. Não jogue o rascunho diretamente no gerador |
| Revisão de texto original | Contratos, textos finais, transcrições, material do cliente | Não altere uma única palavra; gere a página com --no-lint. No máximo, adicione um > [!Conclusão] no início explicando o que deve ser revisado na página |
Estilo para conteúdo explicativo
- Primeira tela já diz tudo: comece com
> [!Conclusão]resumindo a conclusão em uma frase, seguido por> [!Decisão sua]listando o que o leitor precisa fazer. O contexto vem depois; o leitor não precisa rolar para tomar uma decisão. - Cada coisa dita uma vez: se a conclusão já foi dita no quadro, não repita no texto; se um gráfico ou tabela já explica, não repita em parágrafo abaixo. Evite seções de "resumo".
- Linguagem clara: use as palavras que o leitor usa no dia a dia. Na primeira aparição de um termo técnico, use uma analogia ou um
> [!Simples]para complementar com uma explicação. - Se puder desenhar, não escreva: pergunte-se "que tipo de relação este trecho descreve?" e escolha o componente conforme a tabela abaixo. Texto puro: no máximo três linhas por parágrafo. Cada seção
##deve conter pelo menos um componente visual ou tabela. - Curto: uma frase, um ponto principal. Elimine bordões como "ou seja", "em outras palavras", "vale notar que".
- Elimine repetições, não informações: números, datas, nomes e consequências nunca podem ser omitidos ou alterados.
Guia rápido de componentes visuais
Escreva algumas linhas com sintaxe curta; o gerador desenha o gráfico. Use ｜ (barra vertical larga) como separador e → para setas. Veja o exemplo completo em assets/example.md.
| O que este trecho descreve | Componente | Sintaxe |
|---|---|---|
| Antigo vs novo, agora vs depois da mudança | Comparação | ```comparação: primeira linha agora → depois da mudança, depois cada linha item｜antigo → novo |
| Como o sistema é composto, fluxo de dados | Arquitetura | ```arquitetura: cada linha um nível nível｜caixa, caixa; dentro do nível, use a → b para ordem; entre níveis, pode inserir ↓ descrição |
| O que acontece quando | Linha do tempo | ```linha-do-tempo: cada linha tempo｜título｜descrição; início da linha: ✅ concluído, 👉 agora |
| Sequência, etapas, causa e efeito | Passos | ```passos: cada linha título｜descrição, numeração automática; até 4 passos em linha horizontal, 5+ em vertical |
| Números-chave | Números | ```números: cada linha número unidade｜rótulo｜nota; espaço entre número e unidade para tornar a unidade pequena |
| Opções, quem faz o quê, itens paralelos | Cartões | ```cartões (ou opções, divisão): cada linha título｜uma linha｜outra linha; início com ★ marca como opção recomendada |
| Comparação em várias colunas | Tabela | Tabela markdown comum. Quando o cabeçalho contém "agora/antigo" e "depois/novo/sugerido", a coluna antiga fica cinza e a nova, verde claro |
| Fluxo com ramificações | Cartões de fluxo | Diagramas ASCII ou mermaid (graph/flowchart com TD, LR); se não converter bem, mantém o original |
| Conclusão, decisão, atenção, risco | Quadro de destaque | > [!Conclusão] título, a partir da próxima linha > conteúdo. Use: Conclusão, Decisão sua, Atenção, Risco, Feito, Simples, Explicação |
| Status | Marcador colorido | Inline: {verde:Concluído} {amarelo:Aguardando você} {vermelho:Empacado} {azul:Em andamento} {cinza:Não será feito} |
| Palavra-chave em uma frase | Destaque | ==palavra-chave==, no máximo um por parágrafo |
- As cores têm significado fixo: azul é conclusão e informação; verde é concluído e depois da mudança; amarelo é atenção e espera; vermelho é risco e empacado. "Decisão sua" aparece apenas uma vez na página.
- Se a sintaxe estiver errada, a página não quebra — o bloco vira um bloco de código com fundo cinza. Após gerar, veja se algum bloco que deveria ser gráfico ainda está cinza.
- Para relações de causa e efeito ou sequência, use Passos ou Linha do tempo; para itens independentes, use Cartões.
- O texto dentro dos gráficos é texto real e pode ser selecionado para comentários.
Verificação de layout
Ao gerar a página, o sistema imprime automaticamente uma "Verificação de layout": se não houver quadro de conclusão no início, se um parágrafo for muito longo, se houver poucos componentes visuais, se houver palavras repetitivas, travessões, a mesma coisa dita duas vezes, etc. Se houver alertas, edite o markdown e gere novamente até aparecer "Verificação de layout: aprovado". Para revisão de texto original, use --no-lint.
Economia de recursos
- Use sempre a sintaxe curta para gráficos; nunca desenhe HTML ou SVG manualmente, nem gere imagens externas.
- Para alterar o conteúdo, edite o markdown e gere novamente; nunca edite o HTML de saída diretamente.
- Listas muito longas podem ser recolhidas com
--fold "3".
Regra 3: Sempre execute o gerador
- A página de pré-visualização deve ser gerada exclusivamente com
scripts/md-to-preview.py(fonte em md) ouscripts/convert/inject.py(HTML já diagramado). Não escreva CSS manualmente nem monte a funcionalidade de comentários por conta própria. - Para alterar a aparência, edite
assets/preview-tokens.csse execute o gerador novamente.
Fluxo de execução
Etapa 1: Confirmar fonte e identidades
Identifique a partir do diálogo; se não conseguir, pergunte:
- O que será pré-visualizado? (conteúdo recém-escrito no chat, ou arquivo fornecido pelo usuário)
- Quem comentará? Identidades padrão:
eu,visitante. Se for para o cliente, use algo comocliente,eu(o primeiro é a identidade padrão).
Se a fonte for o conteúdo do diálogo, salve-o primeiro em um arquivo md no diretório de trabalho atual do usuário (se não existir, crie uma pasta Pré-visualização na área de trabalho). O nome do arquivo deve descrever o conteúdo em português, por exemplo proposta-cliente-exemplo.md.
Etapa 2: Gerar a página
Fonte é md (caso mais comum):
python3 "$SKILL_DIR/scripts/md-to-preview.py" "<fonte>.md" "<saída>.html" \
--identities "eu,visitante" --badges "rascunho,2026-10-19"
| Parâmetro | Função |
|---|---|
--identities | Lista de identidades separadas por vírgula; a primeira é a padrão |
--badges | Marcadores cinza pequenos abaixo do título, separados por vírgula; se omitido, não exibe |
--key | Nome usado no navegador para armazenar comentários; deve ser único por página; se omitido, usa o nome do arquivo de saída |
--title | Título do documento; se omitido, usa o primeiro título # do markdown |
--fold "3,4" | Recolhe seções de determinado nível em parágrafos expansíveis; útil para páginas longas |
--no-lint | Ignora a verificação de layout (use para contratos, textos finais) |
--no-overlay | Versão limpa, sem funcionalidade de comentários |
--icon | Caractere ou emoji no ícone da aba; se omitido, usa o primeiro caractere do título |
--fonts copy／link／none | Tratamento de fontes; padrão copy |
Fontes: por padrão, uma pasta preview-fonts/ é criada ao lado do HTML de saída. 🚨 Ao enviar para outra pessoa, é necessário compactar o HTML e a pasta preview-fonts/ juntos; enviar apenas o HTML fará com que o sistema use fontes padrão (ainda funciona, mas fica menos bonito).
Imagens: blocos isolados de  no markdown serão convertidos em imagens com legenda, com caminhos relativos ao HTML de saída.
Fonte já é HTML diagramado (ex.: uma proposta que você mesmo criou): Não altera o layout, apenas adiciona a funcionalidade de comentários.
python3 "$SKILL_DIR/scripts/convert/inject.py" "<página>.html" -o "<página>-com-comentarios.html" --identities "eu,cliente"
-odeve ser um arquivo novo; a ferramenta nunca sobrescreve a fonte.- Se a página já tiver funcionalidade de comentários e for necessário atualizá-la, adicione
--replace.
Etapa 3: Abrir para o usuário
Abra no navegador padrão do sistema:
# macOS
open "<saída>.html"
# Windows (o terminal do Claude é Git Bash, use start; no PowerShell, use Start-Process "<saída>.html")
start "" "<saída>.html"
# Linux
xdg-open "<saída>.html"
Informe ao usuário três coisas:
- Selecione qualquer texto que aparecerá "Adicionar comentário".
- As caixas de seleção podem ser clicadas diretamente.
- Após a revisão, clique no botão "Copiar tudo" no canto superior direito e cole o conteúdo de volta no chat.
Etapa 4 (opcional): Enviar para cliente comentar
- Compacte o HTML e a pasta
preview-fonts/ao lado em um arquivo zip e envie ao cliente. Peça para ele descompactar e clicar duas vezes no HTML para abrir. - Defina as identidades conforme o papel do cliente, ex.:
--identities "cliente,eu". - Os comentários ficam armazenados no navegador do cliente e não são sincronizados automaticamente. Peça ao cliente para clicar em "Copiar tudo" e enviar o texto por email ou mensagem.
Marcação de checkbox
Quando o usuário precisar decidir item por item de uma lista e as opções são fixas, crie checkboxes, não peça para ele digitar a resposta. Exemplos: decidir quais funcionalidades implementar ou não, selecionar alguns recursos de um conjunto, checklist de pré-lançamento. Se houver apenas uma ou duas opções, ou se for necessário justificar, pergunte diretamente ou use comentários por seleção de texto.
Como escrever
No markdown, use listas de tarefas; o gerador as converterá em caixas clicáveis:
### Obrigatório
- [x] Formulário de pedidos (preenchido pelo cliente, entra automaticamente no banco de dados)
- [ ] Calendário de turnos (cada funcionário vê apenas seu próprio turno)
- [ ]não marcado,- [x]marcado por padrão.- Cada grupo deve estar sob seu próprio título (
##ou###): na exportação, agrupa pelo título mais próximo acima. - Cada item deve ter um nome e uma breve descrição que o torne compreensível isoladamente; não escreva apenas "sim" ou "não".
- Não pode haver dois itens com o mesmo texto sob o mesmo título.
O que acontece no navegador do usuário
- O estado das checkboxes é armazenado no navegador e persiste mesmo após atualizar a página; o botão "Limpar" limpa apenas os comentários, não as checkboxes.
- Ao clicar em "Copiar tudo", um bloco adicional é incluído no início:
## Resultado das checkboxes (marcadas 2/5)
### Definição de escopo › Obrigatório
- [x] Formulário de pedidos (preenchido pelo cliente, entra automaticamente no banco de dados)
- [ ] Calendário de turnos (cada funcionário vê apenas seu próprio turno)
Ao receber o resultado das checkboxes
- Salve o resultado exatamente como está em um arquivo e siga-o fielmente; não recorra à memória.
- Itens não marcados significam "não fazer" ou "manter como está"; não tome decisões por conta própria.
- Se houver itens conflitantes marcados no mesmo grupo, pergunte ao usuário.
- Se a ação impactar terceiros (enviar email, excluir arquivos, colocar em produção), primeiro liste o resultado final e só execute após o usuário confirmar "Pode fazer".
Como aplicar o "Resumo de comentários" recebido
Quando o usuário cola de volta o conteúdo do "Copiar tudo", ele contém: cada comentário com o texto original selecionado (citação), a posição (título do parágrafo), contexto anterior/posterior e o conteúdo do comentário.
Interpretação item por item
| Aparência do comentário | Interpretação |
|---|---|
| Apenas um novo texto, sem verbo | Substituir: troque a citação pelo texto do comentário |
| "Remover", "Tirar" | Remova o trecho da citação (apenas o intervalo citado) |
| "Adicionar", "Incluir", "Mais um abaixo" | Inserir: adicione conteúdo próximo à citação |
| Descritivo ("Pode...?", "Gostaria que...") | Modifique conforme a solicitação |
| Ambíguo, com duas interpretações possíveis | Escolha a alteração mais conservadora e informe claramente qual foi a escolha |
- Use a "posição" e o "contexto anterior/posterior" para localizar o ponto correto antes de modificar. Se o mesmo texto aparecer várias vezes na página, confirme pelo contexto que está alterando apenas um local.
- Comentários de uma rodada podem se repetir em relação à rodada anterior; compare primeiro o que já foi alterado.
Aplicar, gerar novamente, reabrir
- Altere o markdown original e execute o gerador com o mesmo comando e o mesmo
--key— nunca edite o HTML de saída diretamente (será sobrescrito na próxima execução). Com a mesma chave, os comentários antigos são preservados. - Reabra a página para o usuário.
- Relate: liste item por item "qual comentário → o que foi alterado", marcando suas escolhas quando houver ambiguidade.
Notas técnicas (para o Claude, não precisa informar o usuário)
- A ancoragem dos comentários usa "texto selecionado + contexto anterior/posterior"; pequenas alterações no conteúdo são reposicionadas automaticamente. Se não encontrar, marca como "Texto original alterado".
- O destaque usa a CSS Custom Highlight API do navegador, sem modificar a estrutura da página. Navegadores Chrome, Edge e Safari (versões recentes) são compatíveis; em navegadores incompatíveis, apenas o destaque amarelo não aparece, mas os comentários na barra lateral funcionam normalmente.
- Comentários e checkboxes são armazenados no
localStoragedo navegador, com uma chave diferente para cada página (--key). Caso contrário, comentários de páginas diferentes se misturariam. - Após carregar a interface de comentários, o objeto
window.PreviewCommentsfica disponível:.refresh()reposiciona os destaques,.data()retorna todos os comentários,.exportMd()retorna o markdown exportado. - O z-index de popups da própria página deve ser inferior a 10400 para que os botões de comentários não fiquem ocultos.