Revisar Site Estático
Objetivo
Validar a saída de um site estático antes do usuário editá-la, publicá-la ou considerá-la finalizada.
Este skill é um gate de qualidade para sites gerados em HTML/CSS/JS. Ele não escolhe um tema, recria uma referência, migra conteúdo ou faz deploy do site. Ele verifica se a pasta gerada se comporta como um site estático real.
Verificações principais:
- Os arquivos fonte são UTF-8 válido e legíveis por humanos.
- Links locais, scripts, folhas de estilo, imagens e outros assets são resolvidos.
- Links e assets locais do site usam caminhos relativos à página por padrão, não caminhos absolutos raiz como
/assets/style.css. - A saída pode ser aberta diretamente de
index.htmlpara pré-visualização manual, a menos que o usuário tenha aceitado explicitamente um comportamento somente servidor. - As páginas geradas cobrem os tipos de página esperados.
- O site renderiza em um navegador real via HTTP local.
- Os layouts desktop e mobile são utilizáveis.
- Erros de console, interações quebradas, placeholders residuais e texto copiado de fontes específicas são reportados ou corrigidos.
Contrato
Entradas:
- Raiz do site estático, como
site/,dist/,out/,public/,docs/ou raiz do repositório. - Escopo de página esperado opcional, URL de pré-visualização local,
EDITING.md, URL/captura de tela de referência e strings proibidas de fontes específicas.
Saídas:
- Descobertas ordenadas por severidade, ou correções quando a validação faz parte de uma tarefa de construção/correção.
- Resultados de auditoria estática, páginas/viewports do navegador verificadas e arquivos alterados, se houver.
- Estado claro de aprovação/reprovação para prontidão de publicação ou finalização.
Limites:
- Não escolher temas, recriar sites, migrar conteúdo, personalizar identidade ou fazer deploy.
- Não redesenhar o site durante a validação, a menos que um problema visual bloqueie a usabilidade e o usuário tenha solicitado correções.
- Não abençoar caminhos absolutos raiz locais do site, a menos que
--allow-root-absoluteseja usado intencionalmente e a limitação seja declarada.
Gate de sucesso:
- Nenhum bloqueador permanece: navegação primária quebrada, tipo de página obrigatório ausente, codificação de fonte ilegível, falha de asset local, falha de console, interface móvel inutilizável ou problema acidental de caminho absoluto raiz.
- Avisos são corrigidos, documentados ou aceitos pelo usuário.
Se o gate falhar:
- Corrigir problemas locais diretos quando a validação faz parte da construção.
- Roteirizar falhas maiores para
make-personal-site,copy-website-style,personalize-site,add-blog-postsouedit-site-part, dependendo da superfície que falhou. - Reexecutar auditoria determinística e verificações de navegador afetadas.
Usar Com
Use este skill após:
make-personal-sitecriar ou redesenhar um site pessoal estático original.copy-website-stylerecriar o estilo de um site alvo como arquivos estáticos.- Um usuário apontar para uma pasta de saída estática existente e perguntar se ela é boa o suficiente.
- Um usuário pedir para verificar, validar, fazer QA, inspecionar, auditar ou testar um site estático antes de publicar.
Se o usuário fornecer um projeto fonte de framework, valide a pasta de saída estática já construída quando possível. Não introduza um fluxo de trabalho de construção de framework aqui, a menos que o usuário peça explicitamente.
Entradas
Use quaisquer entradas disponíveis:
- Pasta raiz do site estático, como
site/,dist/,out/oupublic/. - URL de pré-visualização local, se um servidor já estiver em execução.
- Escopo de página esperado: apenas homepage, site pessoal completo, blog, portfólio, notas, links, recriação de estilo, etc.
EDITING.md, mapa de página ou quaisquer notas de finalização produzidas por outro skill.- URL ou captura de tela de referência, ao validar uma recriação de estilo.
- Strings conhecidas que não devem permanecer, como nomes de autores originais, domínios, emails, IDs de analytics ou texto placeholder antigo.
Se a raiz do site não estiver clara, inspecione pastas próximas e escolha a que contém index.html e assets estáticos.
Fluxo de Trabalho
- Identificar a raiz do site estático e o escopo de página esperado.
- Ler
EDITING.mdou inferir o mapa de página a partir de arquivos HTML e links de navegação. - Executar o script de auditoria de arquivos determinística.
- Iniciar ou reutilizar um servidor HTTP local para a raiz estática.
- Validar o site em um navegador real com larguras desktop e mobile.
- Abrir ao menos uma página representativa para cada tipo de página gerada.
- Testar interações principais, como navegação, alternância de tema, busca/filtro, botões de copiar, menu mobile e paginação.
- Verificar erros de console do navegador e recursos de rede ausentes.
- Auditar compatibilidade de caminhos relativos, placeholders, legibilidade UTF-8 e texto residual de fontes específicas.
- Corrigir defeitos diretos quando o usuário pediu validação como parte de uma construção; caso contrário, reportar descobertas primeiro.
Auditoria de Arquivos Determinística
Use o script incluído antes da validação no navegador:
python scripts/static_site_check.py <site-root>
Para recriações de estilo ou limpezas de sites copiados, passe strings proibidas de fontes específicas:
python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"
O script verifica:
- Decodificação UTF-8 para arquivos HTML, CSS, JS, JSON, Markdown, SVG, XML e texto.
- Mojibake suspeito e caracteres de substituição.
<meta charset="utf-8">ausente em arquivos HTML.- Referências locais quebradas
href,src,srcset,poster,actionedata-src. - Referências absolutas raiz locais do site, como
/assets/...,/posts/...,/data/...ou/images/..., a menos que explicitamente permitidas. - Referências de asset CSS
url(...), incluindo URLs locais ausentes ou absolutas raiz. - Strings absolutas raiz comuns do site dentro de HTML, JavaScript e JSON.
- Links que escapam da raiz do site.
- Strings placeholder comuns.
- Strings proibidas fornecidas com
--forbid. - Arquivos de raiz de deploy sensíveis à privacidade, como
.env, chaves privadas, arquivos de credenciais e artefatos de conta de serviço locais. - Atribuições semelhantes a segredos, padrões de token conhecidos, blocos de chave privada e caminhos absolutos do sistema de arquivos local no texto fonte.
- Artefatos temporários, de log, backup e do SO que não devem ser publicados.
- Contagem de páginas HTML e tipos de página inferidos.
- Se
EDITING.mdexiste.
A auditoria de arquivos ainda deve verificar a legibilidade UTF-8 para arquivos de fornecedores, mas não deve tratar palavras semelhantes a placeholder dentro de pacotes de fornecedores minificados de terceiros como conteúdo placeholder do site.
Trate erros de script como bloqueadores, a menos que o usuário quisesse apenas uma revisão exploratória rápida. Trate avisos como itens para inspecionar manualmente.
Se o site for intencionalmente projetado para exigir caminhos relativos à raiz sob uma raiz de domínio personalizado, execute o script com --allow-root-absolute e declare que a abertura direta file:// e a implantação em subcaminho de projeto do GitHub não são garantidas. Não use esta exceção para sites estáticos pessoais simples gerados, a menos que o usuário aceite explicitamente essa compensação.
Compatibilidade de Caminhos
Sites estáticos simples gerados devem funcionar em três contextos comuns:
- Abrir diretamente
index.htmldo sistema de arquivos para uma pré-visualização manual rápida. - Servir a pasta via HTTP local para automação de navegador e verificações de console/rede.
- Implantar em um host estático que pode servir o site de uma raiz de domínio ou de um subcaminho.
Regra padrão:
- Use caminhos relativos à página para links e assets locais do site.
- De páginas raiz, use
assets/style.css,posts/example.htmleabout.html. - De páginas aninhadas, use
../assets/style.css,../blog.htmle links relativos a irmãos conforme apropriado. - Não use
/assets/style.css,/posts/example.html,/data/posts.json,/images/foo.pngou/para navegação interna por padrão.
Verifique também links gerados por JavaScript, resultados de busca, filtros de tag, botões de copiar, cartões dinâmicos, referências RSS/sitemap, capas de imagem, valores CSS url(...), favicons, fontes e assets de fornecedores KaTeX/math. Não é suficiente que atributos HTML estáticos sejam relativos se JavaScript posteriormente inserir caminhos absolutos raiz.
Caminhos absolutos raiz são aceitáveis apenas quando o usuário quer explicitamente uma implantação somente servidor raiz, como uma raiz de domínio personalizado, e entende que a abertura direta de arquivo e subcaminhos do GitHub Pages podem quebrar.
Validação no Navegador
Use um navegador real antes da entrega final. Sirva arquivos locais via HTTP, não file://:
python -m http.server 8000
Depois abra:
http://127.0.0.1:8000/
Use uma ferramenta de navegador interativa realmente disponível como caminho de validação de primeira escolha para alvos HTTP locais. "Disponível" significa que a ferramenta está exposta na lista de ferramentas chamáveis do turno atual, não meramente mencionada em um skill, lista de plugins ou descrição do sistema. No Codex, isso pode ser o plugin Browser/navegador no aplicativo quando o usuário ou cliente o roteou para o turno; em outros agentes, pode ser um navegador visível equivalente, ferramenta de uso de navegador ou navegador com suporte a devtools. Ela deve abrir a URL local, inspecionar viewports desktop/mobile, exercitar interações e verificar problemas visíveis de console/rede.
Se nenhuma ferramenta de navegador interativa estiver exposta no turno atual, não finja que a validação no navegador ocorreu. Se a validação depender disso, peça ao usuário para habilitar ou invocar a ferramenta de navegador usando o método de roteamento de seu cliente; para Codex, isso pode significar enviar uma solicitação que mencione explicitamente @browser. Se o usuário não rerrotear ou o cliente não tiver tal ferramenta, recorra a Playwright, capturas de tela, auditorias estáticas ou verificações de shell e declare que esta foi uma solução alternativa, não uma validação completa no navegador interativa.
Não use como padrão Playwright, scripts de captura de tela somente headless, janelas de navegador abertas por shell ou geração de captura de tela estática quando uma ferramenta de navegador interativa é realmente chamável. Capturas de tela são evidências úteis, mas não substituem uma passagem interativa no navegador. Use Playwright apenas como solução alternativa quando nenhuma ferramenta de navegador interativa for chamável, quando o usuário pedir explicitamente por Playwright ou quando uma regressão repetível e com script for especificamente necessária.
Use automação Chrome apenas quando a tarefa precisar do perfil Chrome do usuário, abas existentes, extensões, páginas remotas autenticadas ou comportamento específico do Chrome. Não confie na automação de extensão Chrome para páginas file://; use HTTP local.
Mesmo que a automação deva usar HTTP local, a fonte gerada ainda deve ser compatível com abertura direta, usando caminhos relativos e evitando suposições somente servidor para conteúdo principal. Se o aplicativo/navegador permitir uma verificação rápida file://, abra o index.html raiz diretamente e verifique se CSS, imagens, navegação e subpáginas representativas não estão quebradas. Se a automação de arquivo não estiver disponível, confie na auditoria de caminho absoluto raiz determinística e mencione se a abertura direta foi verificada manual ou automaticamente.
Verificações do navegador:
- Primeira tela desktop: composição, espaçamento, tipografia, navegação visível e estouro óbvio.
- Primeira tela mobile: comportamento da navegação, quebra de texto, prioridade de conteúdo e estouro horizontal.
- Navegação interna: todos os links de navegação primária renderizam.
- Cobertura de tipo de página: ao menos uma passagem de navegador ou captura de tela para cada tipo de página gerada.
- Cobertura de interação: alternâncias de tema, menus, filtros, busca, botões de copiar, paginação, acordeões, abas, estados hover/clique ou outros controles visíveis.
- Estado do console: sem erros JavaScript óbvios.
- Estado da rede: sem assets CSS, JS, imagem ou fonte locais ausentes.
- Básicos de acessibilidade: visibilidade de foco para controles interativos, contraste legível, títulos de página significativos e texto alt não vazio para imagens quando praticável.
Para sites pequenos, clique em cada página gerada. Para sites maiores, amostre cada tipo de página e qualquer rota mencionada em EDITING.md.
Cobertura de Tipo de Página
Infira tipos de página a partir de nomes de arquivo, rotas, navegação visível e EDITING.md.
Tipos de página típicos:
- Home.
- Sobre ou perfil.
- Blog, arquivo, categoria, tag, notas ou página de lista.
- Artigo ou página de detalhe.
- Projetos, portfólio, publicações ou página de trabalho.
- Links, amigos, recursos, agora, usa, jardim, busca, tema/configurações ou outra página especial.
Se um site gerado afirmar ser um blog mas não tiver uma página de artigo/detalhe, reporte. Se tiver navegação para subpáginas que não existem, reporte como bloqueador.
Codificação e Legibilidade da Fonte
Capturas de tela do navegador não são suficientes. Os arquivos fonte devem ser legíveis por modelos e humanos futuros.
Requisitos:
- Arquivos HTML incluem
<meta charset="utf-8">. - Texto não ASCII é armazenado como UTF-8.
- Comentários HTML, CSS, strings JavaScript, arquivos JSON/dados, texto SVG e
EDITING.mdsão legíveis em forma fonte. - Sem mojibake, caracteres de substituição ou recuperação acidental de codificação do navegador.
Se um terminal exibir mojibake mas o navegador parecer correto, confirme com uma leitura com reconhecimento UTF-8 antes de considerar quebrado. Se o conteúdo do arquivo em si contiver mojibake, reescreva strings afetadas a partir de texto limpo em vez de aplicar outra conversão de codificação.
Auditoria de Placeholder e Resíduo
Verifique se o site gerado ainda contém:
TODO,FIXME,lorem ipsum,placeholder,replace me,your name,example.comou texto de amostra/demo.- Emails fictícios, links sociais falsos, botões vazios ou chamadas para ação mortas.
- Nomes de autor do site original, domínios, títulos de artigos, emails, IDs de analytics, links sociais, links de amigos ou URLs privadas em recriações de estilo.
Não remova placeholders cegamente se o usuário ainda precisar deles como marcadores editáveis intencionais. Reporte-os claramente, ou substitua-os apenas quando o usuário tiver fornecido conteúdo real.
Privacidade e Resíduo Local
Trate estes como bloqueadores antes de publicar:
.env,.npmrc,.pypirc, arquivos de chave privada, arquivos JSON de credenciais, arquivos de conta de serviço ou arquivos de exportação de cofre de senhas dentro da raiz implantável.- Atribuições semelhantes a segredos, tokens de acesso, blocos de chave privada ou chaves API em HTML, CSS, JavaScript, JSON, Markdown, SVG ou arquivos de texto.
- Caminhos de sistema de arquivos absolutos locais, como caminhos de unidade Windows,
file:///...,/Users/...,/home/...ou/mnt/...na fonte gerada.
Trate logs, backups, arquivos temporários e metadados do SO como avisos, a menos que exponham conteúdo privado. Remova-os da saída implantável antes de empacotar ou publicar.
Política de Correção
Quando o usuário pedir para "verificar", "revisar" ou "me dizer o que está errado", reporte descobertas primeiro e evite edições amplas.
Quando a validação faz parte de uma construção