Communitygithub.com

html-to-editable-pptx

Converte decks de slides HTML em arquivos PPT/pptx verdadeiramente editáveis, onde textos permanecem caixas de texto nativas do PowerPoint, e não capturas de tela.

O que é html-to-editable-pptx?

Esta skill permite que agentes de IA como Claude Code, Cursor, Codex e opencode convertam decks de slides HTML em arquivos PowerPoint (.pptx) totalmente editáveis, preservando textos como caixas de texto nativas, formas vetoriais e imagens. Ela é útil para engenheiros que criam apresentações em HTML e precisam compartilhá-las em PowerPoint sem perder editabilidade. A skill oferece uma pipeline robusta com pré-análise de riscos, medição, montagem, incorporação de fontes (incluindo fontes CJK), verificação estrutural e auditoria visual via compare side-by-side. Suporta execução incremental para correções iterativas e um workflow completo que guia o agente desde a conversão até a entrega final, incluindo limpeza de artefatos temporários.

Funciona com✓Claude Code✓Codex CLI✓Cursor✓OpenCode
npx skills add Hasasasa/html-to-editable-pptx

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

html-to-pptx

Quando acionar

Quando o usuário disser qualquer uma das seguintes intenções:

  • "Converta este deck HTML / página da web para PPT / pptx"
  • "Fiz slides HTML e quero dar um ppt para os colegas"
  • "Não dá pra abrir o navegador na reunião, quero um arquivo ppt"
  • Já tem o caminho do arquivo HTML e menciona ppt / pptx / apresentação / slide

Chamada

<skill_dir> é o diretório de instalação desta skill (geralmente ~/.claude/skills/html-to-pptx/, no Windows é %USERPROFILE%\.claude\skills\html-to-pptx\). Substitua <skill_dir> pelo caminho real nos comandos abaixo, ou primeiro cd <skill_dir> e depois execute python convert.py ….

python <skill_dir>/convert.py <input>.html
  • A saída padrão é no mesmo diretório da entrada com o nome <input>.pptx
  • Fontes são baixadas sob demanda: quando uma fonte HTML é usada, ela é baixada do Google Fonts durante a conversão, subsetada e incorporada, com cache em %LOCALAPPDATA%\html-to-pptx\fonts\ ou ~/.cache/html-to-pptx/fonts/, reutilizando na próxima vez instantaneamente
  • Se o HTML contiver caracteres CJK, as fontes Noto Sans SC + Noto Serif SC são automaticamente baixadas (primeira vez ~40 MB / ~30s para download e instanciação estática Regular/Bold, depois cache é usado)
  • Fontes que não estão no Google Fonts são revertidas para as fontes do sistema no visualizador, com um warning impresso
OpçãoSignificado
--out <path>Caminho personalizado para o .pptx de saída
--keep-screenshotsMantém também uma captura de tela de referência de cada página + preflight.json
--no-embed-fontsPula a incorporação de fontes. Arquivo menor, mas em outro computador as fontes serão revertidas para as do sistema
--no-preflightDesliga a pré-análise de riscos do Stage 1
--no-verifyDesliga a auto-verificação estruturada do Stage 5a
--no-visual-auditDesliga a produção de materiais de auditoria visual do Stage 5b. Não desligar no dia a dia
--install-user-fontsInstala as fontes não CJK detectadas automaticamente no diretório de fontes do usuário (para que o WPS as renderize corretamente). Suportado em Windows/macOS/Linux. Pergunte ao usuário antes, veja a seção "Confirmação de configuração" abaixo
--only-slides N,N,NRe-execução incremental. Números de página separados por vírgula (base 1). O measure executa apenas nas páginas especificadas e combina com a medição em cache da rodada anterior; assemble/embed-fonts ainda são completos; Stage 5a renderiza apenas as páginas especificadas; Stage 5b recria apenas as imagens compare das páginas especificadas — todas as outras páginas reutilizam o cache da rodada anterior. Usado exclusivamente em rodadas iterativas de auditoria, veja a seção "Re-execução incremental" abaixo
--cleanupNão faz conversão. Remove os artefatos de trabalho audit / measurement / preflight ao lado do input.pptx, mantendo apenas o .pptx e o audited.html. Use antes da entrega final, veja a última etapa do "Workflow" abaixo

Cópia de trabalho (HTML original não é alterado)

Após a primeira execução de python convert.py <input>.html, o convert.py copia automaticamente uma versão <input>.audited.html para o mesmo diretório do HTML de origem. Mecanismo:

  • Todas as correções de auditoria são feitas no audited.html, nunca no HTML de origem
  • Em rodadas subsequentes de convert (incluindo --only-slides), a entrada é <input>.audited.html, e a saída continua sendo <input>.pptx (o sufixo .audited é removido automaticamente)
  • Se audited.html já existir → reutilizado, não sobrescreve (mantém correções da rodada anterior)
  • Se o agente passar o HTML de origem como entrada por engano → convert.py detecta internamente e usa o audited.html como fallback
  • O cleanup não deleta o audited.html (considerado subproduto entregável, junto com o .pptx)
  • Para recomeçar do zero → delete o audited.html manualmente e execute novamente

Configuração (.config.local.toml)

Arquivo de preferências locais opcional na raiz da skill, gitignorado, um por usuário. Atualmente existem três tipos de preferências:

[fonts]
auto_install = "ask"   # "yes" instala automaticamente, "no" nunca instala, "ask" o agente pergunta

[cleanup]
default = "clean"      # "clean" faz cleanup automático no final do workflow, "keep" mantém artefatos de auditoria

[audit]
mode = "ask"           # "triage" / "page" / "manual" / "ask" o agente pergunta
  • Arquivo / chave ausente → usa o padrão (acima)
  • Template: <skill_dir>/.config.local.toml.example
  • fonts.auto_install é lido e aplicado pelo convert.py (=yes adiciona automaticamente --install-user-fonts, =no ignora)
  • cleanup.default é lido pelo agente no final do workflow para decidir o comportamento
  • audit.mode é confirmado pelo agente antes da primeira conversão; após o Stage 5b, a revisão segue esse valor:
    • "triage" → o agente principal vê a imagem de contato geral audit_contact_*.png para triagem, depois envia sub-agentes para analisar as páginas selecionadas individualmente, economizando tokens
    • "page" → envia um sub-agente para cada página alvo ver a imagem individual slide_NN_compare.png, cobertura máxima
    • "manual" → gera apenas os materiais de revisão e entrega ao usuário para verificação manual; o usuário reporta problemas e depois corrige
    • "ask" ou ausente → o agente coleta a preferência via AskUserQuestion e então reescreve este campo (padrão)
  • Primeiro uso: o agente coleta fonts.auto_install e audit.mode via AskUserQuestion e então escreve este arquivo ele mesmo — o usuário não precisa criar manualmente

Confirmação de configuração (antes da primeira conversão)

Duas preferências precisam ser confirmadas antes da primeira conversão: fonts.auto_install e audit.mode. O fluxo é o mesmo, diferindo apenas na condição de acionamento e na forma de perguntar.

Fluxo geral

Cada preferência é determinada independentemente na seguinte ordem:

  1. Leia <skill_dir>/.config.local.toml, veja o campo correspondente:
    • Valor válido diferente de ask → siga esse valor, não pergunte mais na sessão
    • ask ou arquivo/campo ausente → vá para "condição de acionamento + ask"
  2. Se o CLAUDE.md / instrução global especificar um valor equivalente, siga esse valor e atualize o config (mantendo uma única fonte de verdade)

Após acionamento, pergunte via AskUserQuestion uma vez, ambas as preferências devem ser feitas:

  • Escreva em <skill_dir>/.config.local.toml o campo correspondente com a resposta do usuário (não escreva ask, senão perguntará novamente na próxima sessão)
  • Na sessão atual, siga a resposta

Ao escrever o config: se o arquivo não existir → Write o arquivo inteiro (template das três seções [fonts] [cleanup] [audit]); se o arquivo já existir → use Edit para fazer um replace de linha única (apenas este campo), não Write o arquivo inteiro novamente, senão sobrescreverá outras chaves personalizadas do usuário.

Se ambas as preferências forem acionadas na mesma sessão → combine em uma única AskUserQuestion e pergunte de uma vez.

fonts.auto_install — Instalação de fontes

PowerPoint COM slide.Export() e WPS Office não leem arquivos TTF nus incorporados no pptx — tanto a renderização de auditoria quanto o WPS revertem para fontes do sistema. Instalar no diretório de fontes do usuário faz ambos usarem as fontes do sistema. Diretórios (todos em nível de usuário, podem ser deletados manualmente):

  • Windows: %LOCALAPPDATA%\Microsoft\Windows\Fonts\ + registro HKCU
  • macOS: ~/Library/Fonts/
  • Linux: ~/.local/share/fonts/ + fc-cache -f

Condição de acionamento: Veja o <head> do HTML em busca de <link href="...fonts.googleapis.com/..."> / @import url(https://fonts.googleapis.com/...) / dentro de <style> com font-family::

  • Aciona: Qualquer fonte GF / auto-hospedada (Bricolage Grotesque, DM Sans, Inter, Space Grotesk, Caveat, etc.)
  • Não aciona: Apenas fontes na lista de sistema (Arial, Times New Roman, Helvetica, Helvetica Neue, Courier, system-ui, -apple-system, BlinkMacSystemFont, SF Pro, Microsoft YaHei, SimSun, PingFang, Hiragino)

Conforme resposta: concordar → adicione --install-user-fonts; recusar → não adicione.

audit.mode — Modo de revisão visual

Três modos: triage / page / manual (significados na seção "Configuração" acima). Determinado antes da primeira conversão de cada sessão (não depende do conteúdo HTML para acionar). AskUserQuestion com pergunta de escolha única, as opções são os três modos.

Workflow (obrigatório)

Rodar convert.py não é o fim da entrega. O fluxo completo:

convert.py (na primeira rodada, copia automaticamente o <input>.audited.html, todas as correções vão para esta cópia)
  → Stage 5a Auto-verificação estruturada (varredura OOXML, dá dicas)
  → Stage 5b Materiais de auditoria visual — requer PowerPoint COM ou renderizador LibreOffice
  → Leia `audit.mode` para decidir método de revisão: triage / page / manual
  → 【auditoria do agente】
        modo triage: agente principal lê a folha de contato para triagem → sub-agente vê imagens individuais das páginas selecionadas → escreve audit_findings.md
        modo page: sub-agente vê todas as páginas individuais → escreve audit_findings.md
        modo manual: entrega os materiais de auditoria ao usuário, aguarda feedback manual
  → Para cada finding, faça a menor modificação local possível, sempre no audited.html (veja "Disciplina de correção" abaixo)
  → Após corrigir um lote de findings: `convert.py <input>.audited.html --only-slides <páginas modificadas>` + re-audite apenas as páginas frescas (veja "Re-execução incremental" abaixo)
  → Todas as páginas OK ou apenas LOW restantes
  → 【Se encontrar anti-padrão HTML / novo limite OOXML】 registre em lessons-learned, veja "Registro de problemas HTML e limites OOXML" abaixo
  → Leia `cleanup.default` em `<skill_dir>/.config.local.toml`:
        "clean" (padrão) → execute diretamente `python convert.py <out>.pptx --cleanup`, sem perguntar ao usuário
                           Após limpeza, o diretório contém: <input>.html (origem, inalterado) + <input>.audited.html (versão corrigida) + <out>.pptx
        "keep"        → pule cleanup, mantenha todos os artefatos de auditoria
  → Entregue o caminho do .pptx ao usuário (o audited.html também é entregue como subproduto da versão corrigida em HTML)

Princípio de prioridade vetorial (obrigatório)

Conteúdo que pode ser expresso com texto nativo / forma / linha do PPT deve ser mantido editável: fundo de cor sólida normal, borda retangular normal, linha em um lado, retângulo/elipse simples, ::before / ::after com moldura simples devem todos usar forma PPT.

deco_snapshot é apenas para decorações difíceis de expressar em OOXML (condições de acionamento + definição completa de níveis + mecanismo de captura de tela / camada vetorial colaborativo em references/supported-css.md). Não transforme linhas comuns, eixos de gráfico, bordas simples em captura de tela por preguiça — isso sacrifica a editabilidade do PPT e também dificulta correções locais futuras.

Requisito de renderizador (pré-condição do Stage 5b)

O Stage 5b de auditoria visual requer renderizar o .pptx em PNG, dependendo de:

  • PowerPoint COM (Windows + Office + pywin32), ou
  • LibreOffice (multiplataforma, com pip install pdf2image)

Se qualquer um estiver disponível, a auditoria pode rodar. Se ao final da saída do convert aparecer [self-check] Pulando: nenhum renderizador de pptx disponível significa que nenhum dos dois está instalado — neste caso a auditoria não produz imagens compare, e o Stage 5b é pulado.

Neste caso, o agente DEVE perguntar ao usuário (não entregar um pptx não auditado silenciosamente):

"Seu computador não tem PowerPoint nem LibreOffice instalados, a auditoria visual não pode rodar e o PPT pode ter bugs visíveis. Três opções:

  1. Instale o LibreOffice (recomendado, multiplataforma, 2-3 minutos): winget install LibreOffice.LibreOffice (Windows) / brew install --cask libreoffice (mac) / apt install libreoffice (Linux) e depois pip install pdf2image, execute o convert novamente
  2. Pule a auditoria e entregue diretamente (assumindo o risco de possíveis bugs visuais no PPT)
  3. Execute novamente em outra máquina que já tenha o Office instalado"

Se o usuário escolher 1 → aguarde a instalação e execute convert novamente; escolher 2 → execute com --no-visual-audit, entregue após informar o risco; escolher 3 → envie o diretório atual + HTML para ele.

Modo de auditoria visual (config, pré-condição: 5b rodou)

Antes de executar a revisão visual, leia [audit].mode em <skill_dir>/.config.local.toml. Normalmente isso já deve ter sido perguntado antes da primeira conversão através da seção "Confirmação de configuração" acima; se aqui o mode ainda for "ask" (significa que o agente esqueceu de perguntar), pergunte ao usuário imediatamente seguindo a seção "Confirmação de configuração" antes de continuar.

Cada mode tem seu significado específico na seção "Configuração" acima; aqui listamos apenas cenários de uso:

modeUso
triagePadrão, economiza tokens
pageAntes da entrega final, cliente crítico, usuário exige máxima cobertura
manualUsuário quer ver por si mesmo

A divisão de trabalho no triage é muito clara: Rodada 1 pass de contato = o agente principal vê as miniaturas para triagem (barato, já tem o contexto do HTML de origem / Stage 5a / preflight); Rodada 2 pass de detalhes = envia sub-agentes para ver as imagens compare individuais das páginas selecionadas. Não pode reportar um finding HIGH/MID apenas com base na miniatura; para reportar um finding, deve passar pela confirmação da página individual pelo sub-agente na Rodada 2.

Regras de distribuição de auditoria e leitura de imagens compare

No modo page, todas as páginas passam por dispatch paralelo com sub-agentes Agent(...). No modo triage, apenas as páginas selecionadas na Rodada 2 passam por sub-agentes; a Rodada 1 da folha de contato é lida pelo próprio agente principal, sem sub-agente.

O agente principal lê imagens compare ativamente apenas nos seguintes cinco cenários:

  • Rodada 1 do triage: lê audit_contact_*.png para triagem geral
  • Rodada de verificação de correção focada: se as páginas frescas nesta rodada forem ≤ 2 e a mudança não envolver CSS global → o agente principal lê diretamente as imagens individuais das páginas frescas para revisar findings conhecidos + verificar regressões naquela página, sem sub-agente (um sub-agente leva 2-3 minutos por rodada, ler diretamente leva alguns segundos). Se houver mais páginas frescas ou mudança global, ainda use sub-agente
  • Quando a descrição de um finding for vaga / entrar em conflito com o código fonte e não for possível localizar, leia a imagem individual slide_NN_compare.png correspondente
  • Antes de confirmar um sticky hit, leia a imagem individual
  • Quando o usuário mencionar uma página específica, leia a imagem individual

Fora isso, não leia imagens compare página por página.

Os batches são otimizados por wall-clock dividindo em pequenos lotes paralelos (sub-agentes lendo imagens grandes serialmente é a principal causa de latência; vários batches pequenos paralelos são mais de 2x mais rápidos que um grande batch):

Nº de slidesEstratégia
≤ 21 batch
3-202 páginas por batch, todos paralelos
> 203 páginas por batch (controlar número total de agentes)

O template completo de chamada de sub-agente + checklist + formato de findings está em <out>_audit/audit_prompt.md. Para paralelismo, múltiplas chamadas Agent(..., run_in_background: true, subagent_type: "general-purpose") devem ser colocadas na mesma mensagem do agente principal.

Sub-agentes retornam apenas o texto dos findings (no modo page, contém blocos ## page NN para cada página alvo; no triage, os batches de análise detalhada contêm blocos para cada página ampliada revisada), e o agente principal os mescla e escreve audit_findings.md — escrita concorrente causaria sobrescrita.

Cada finding deve nomear o nome curto do elemento estável e descrever "estado real na metade HTML; diferença na metade PPT". Apenas reporte problemas visuais que são novos ou ampliados no PPT em relação ao HTML; problemas já existentes na metade HTML não contam como finding de conversão.

Preparação do agente principal em paralelo com sub-agentes (obrigatório)

Ao iniciar sub-agentes no modo page ou na Rodada 2 de detalhes do triage, use run_in_background: true na chamada Agent e, na mesma mensagem, envie:

Agent(run_in_background: true, subagent_type: "general-purpose", description: "Auditar slides 1-4", prompt: ...)
Agent(run_in_background: true, subagent_type: "general-purpose", description: "Auditar slides 5-9", prompt: ...)
Read(file_path: "<deck>/template.html")
Read(file_path: "<skill_dir>/references/lessons-learned.md")
Grep(pattern: "class=\"slide |data-slide=", path: "<deck>/template.html",
     output_mode: "content", -n: true)

Cada prompt de sub-agente deve incluir diretamente o caminho absoluto dos arquivos slide_NN_compare.png do lote, o caminho do deck HTML, o caminho de lessons-learned.md (escopo de uso conforme seção "Modo de auditoria visual" acima); não assuma que a saída de Read / Grep do agente principal será automaticamente passada para o sub-agente.

Envie apenas preparações que "sejam úteis independentemente de quais findings surgirem" — não preveja findings e modifique o HTML antecipadamente.

Disciplina de correção (para findings, não buscar causa raiz)

Após receber audit_findings.md, corrija todos os findings desta rodada em um lote, depois execute novamente o convert + audit de uma vez — não um de cada vez. Uma rodada = um lote de edições HTML + um convert + um audit.

Após obter os findings:

  • Não leia imagens compare rotineiramente (os findings já descrevem os sintomas); três exceções para leitura individual estão na seção "Regras de distribuição de auditoria e leitura de imagens compare" acima
  • Não leia measure.py / assemble.py / nenhum código interno da skill para encontrar a causa raiz
  • Abra diretamente audited.html e corrija cada finding por vez

Para cada finding, faça a menor modificação local possível no HTML:

  • Cada finding: modifique apenas o ponto que "o faz desaparecer", depois vá para o próximo finding (continue editando o HTML, não execute convert novamente)

  • Não investigue a causa raiz profunda de "por que a fonte caiu / por que o layout deslocou"

  • Não faça otimizações fora da lista de findings (como "já que estou aqui, vou mudar o .footer para posicionamento absoluto também")

  • Não faça refatorações estruturais entre findings ("declarar font-family explicitamente em todos os slides" ≠ correção mínima de um único finding)

  • Se o mesmo finding aparecer em duas rodadas consecutivas (rodada anterior + rodada atual) → sticky hit, pare e informe ao usuário, não continue expandindo as alterações. A chave de julgamento = (número da página, nome curto do elemento visual):

    • Mudanças na redação / gravidade / HIGH↔MID não resetam o julgamento. Exemplo: (página 5, tamanho do take) descrito como "pequeno" na rodada 6 e "gravemente insuficiente" na rodada 7 → mesma chave sticky, rodada 7 é hit
    • Apenas quando "número da página + elemento" não coincidirem considera-se nova chave sticky
    • Recuperação entre rodadas: se aparecer na rodada 6, desaparecer na rodada 7 e aparecer novamente na rodada 8 → não é sticky (ausência na rodada 7 considera o problema corrigido, rodada 8 é nova regressão)
    • Hit = não corrija este finding nesta rodada, liste como candidato a limite da skill e informe ao usuário; os outros findings desta rodada ainda devem ser corrigidos

    Implementação: após mesclar audit_findings.md de cada rodada, antes de fazer Edit, deve primeiro Read o audit_findings.md da rodada anterior (na primeira rodada não há) para comparar par a par — se uma chave aparecer tanto na rodada atual quanto na anterior, é hit. Findings hit são listados separadamente para o usuário julgar, não entram na fila de edição desta rodada.

Após corrigir este lote de findings, execute python convert.py <input>.audited.html --only-slides <páginas modificadas> de uma vez.

Critério de julgamento: o número de linhas no seu diff deve ser ≤ número de findings × 3 linhas. Acima disso significa que você está "exagerando".

Re-execução incremental (--only-slides)

Usada a partir da 2ª rodada de auditoria; a primeira rodada é completa.

python convert.py <input>.audited.html --only-slides 2,7,12

A cobertura incremental afeta measure / renderização Stage 5a / imagens compare Stage 5b, executando apenas nas páginas listadas + páginas com cache ausente; assemble / embed_fonts ainda são completos. audit_index.json marca incremental_mode: true, fresh_indices, cached_indices, e para cada página fresh: true/false.

As páginas alvo de auditoria na rodada incremental são apenas as fresh_indices. No modo page, distribua diretamente essas páginas; no modo triage, faça triagem dentro deste escopo e depois envie as páginas selecionadas para sub-agentes.

Pré-condição: o diretório <out>_audit/ da rodada anterior ainda existe. Se cache ausente, cai para execução completa; se o número de páginas HTML mudar, detecta automaticamente e cai para measure completo.

Casos onde --only-slides NÃO pode ser usado (quando o efeito visual transborda as páginas listadas, resultando em falso negativo do cache):

  • Mudança em CSS global (<style>, seletores raiz, estilos gerais de .slide)
  • Adição / remoção de fontes (@import, declaração de font-family alterada)
  • Mudança em tokens de nível de deck (fundo, cor de tema, espaçamento)
  • Qualquer mudança em variável global que afete o layout de outras páginas

Nestes casos, execute conversão completa sem flag. Se não tiver certeza → execução completa é sempre segura.

Registro de problemas HTML e limites OOXML (obrigatório)

Seu papel é registrar chamada + uso, não corrigir a skill. Se encontrar um bug interno na skill, não corrija measure.py / assemble.py no local.

Apenas registre duas categorias:

1. Problemas de escrita HTML (o HTML do usuário causa distorção na conversão)

CategoriaJulgamentoO que fazer
Caso único (aparece apenas neste deck, corrigir uma ou duas linhas de HTML resolve)Exceção de página únicaCorrija diretamente o HTML de origem; não registre, não notifique
Anti-padrão HTML geral (qualquer pessoa escrevendo HTML semelhante vai esbarrar)Cross-deckCorrija o HTML + registre na seção "Evasão de escrita HTML" em references/lessons-learned.md

2. Limites de expressão OOXML (PowerPoint / OOXML não suporta naturalmente)

A grande maioria das classes de decoração CSS (backdrop-filter / filter / mix-blend-mode / skew / box-shadow / gradient / uso decorativo de ::before ::after — content vazio + bg-image / box-shadow, etc.) já é automaticamente capturada pelo hasComplexDecoration na "Estratégia de cobertura" e vai para deco_snapshot — o HTML não precisa ser alterado. ::before ::after com string content (content: "↑" etc.) vai pelo canal de texto, veja references/supported-css.md nível 1.

Verdadeiros limites que ainda precisam de workaround no HTML (coisas que a camada de texto OOXML nativamente não consegue expressar):

LimiteCaminho alternativo
Emoji colorido (fontes COLR/CPAL)Twemoji SVG <img>, via canal img
background-clip: text gradiente de textoinline <svg><text fill="url(#grad)">, via canal SVG

Se esbarrar nestes dois tipos → corrija o HTML para usar o caminho alternativo + registre na seção "Limites OOXML" em references/lessons-learned.md.

Se esbarrar em novo CSS não suportado que não está na tabela acima → primeiro verifique se hasComplexDecoration não está deixando de acionar (adicione uma linha de condição de acionamento), em vez de corrigir o HTML. Veja "Método padrão para adicionar novo suporte" em references/supported-css.md.

Como tratar suspeitos de bug na skill (não corrija nem registre)

Se você encontrar um sintoma que, com o mesmo padrão CSS, em outro deck também aconteceria e não está dentro dos limites OOXML conhecidos → isso é uma abstração insuficiente da skill. Não corrija o código da skill no local. Faça estas duas coisas:

  1. No deck atual, faça um workaround no lado HTML para corrigir o finding, para que o usuário receba um PPT entregável
  2. Informe claramente ao usuário: "Encontrei um bug que parece ser geral da skill: [sintoma + padrão CSS que o aciona + workaround atual]. Sugiro que o autor registre como issue para que a skill lide com este padrão de forma mais geral em measure/assemble"

Onde registrar: cópia local + template upstream

references/lessons-learned.md é uma cópia de trabalho local independente por usuário (gitignorada). Na primeira execução do convert.py, local_config.seed_lessons_learned() copia automaticamente do template lessons-learned.md.example (committed). O mecanismo é o mesmo que .config.local.toml.

  • O agente investiga / registra sempre no lessons-learned.md local — livre para adicionar / modificar / organizar, sem ruído de git
  • A cópia local nunca é sobrescrita pelo upstream — git pull puxa apenas o template .example, não mexe na sua cópia de trabalho
  • Para enviar um registro ao upstream: o autor copia manualmente a entrada de volta para lessons-learned.md.example e faz commit; curadoria seletiva, não empurra tudo
  • Escrita local / padrão específico de cliente → escreva diretamente na cópia local, não vai para upstream
  • As entradas de lessons devem conter apenas sintomas, padrões de acionamento e regras de evasão reutilizáveis; não escreva nomes de arquivo locais específicos, nomes de template, números de página, nomes de cliente ou nomes de arquivo de código. Detalhes de implementação específica, comandos e código devem ficar em commit / issue / documentação principal da skill

Acionamento: quando esbarrar em anti-padrão HTML geral / limite OOXML → adicione à tabela correspondente no lessons-learned.md local. Cada convert relê, efeito imediato.

Estratégia de cobertura (em uma frase)

Internamente, a skill traduz todo CSS em quatro níveis de saída: Texto vetorial → Forma vetorial → Decoração rasterizada (deco_snapshot) → Mídia direta. bg-color / border / border-radius simples vão nos dois primeiros níveis (editável e pesquisável), box-shadow / gradient / filter / backdrop-filter / mix-blend-mode / border-radius assimétrico / contêiner cortado + filho rotacionado, etc. acionam hasComplexDecoration e vão no terceiro nível (raster apenas os pixels de decoração, o texto sempre permanece vetorial desenhado sobre a captura).

Definição completa de níveis / condições de acionamento / guia para adicionar novo suporte (prioridade vetorial → captura como fallback) → references/supported-css.md.

Pipeline

[1 Identificação de entrada/pré-varredura] → [2 Medição] → [3 Montagem] → [4 Incorporação de fontes] → [5a Auto-verificação estruturada] → [5b Auditoria visual]
   preflight.py                measure.py       assemble.py     embed_fonts.py      self_check.py         visual_audit.py

Ações de cada estágio / regras anti-suposição / asserções de saída / checklist de novo template → references/methodology.md.

O Stage 5b produz <out>_audit/ (imagens compare + folha de contato + audit_index.json + audit_prompt.md). Não faz diff de pixels — números são insensíveis a bugs locais, dão falsa confiança; o julgamento visual segue audit.mode com triage / page / manual. Sem renderizador, o 5b é pulado, e o agente pergunta ao usuário conforme a subseção "Requisito de renderizador" acima.

Antes de chamar

…

[truncado para tradução]

Habilidades Relacionadas