Revisar Sitio Estático
Objetivo
Validar una salida de sitio web estático antes de que el usuario la edite más, la publique o la trate como finalizada.
Esta skill es un control de calidad para sitios generados con HTML/CSS/JS. No elige un tema, recrea una referencia, migra contenido ni despliega el sitio. Verifica que la carpeta generada se comporte como un sitio estático real.
Verificaciones principales:
- Los archivos fuente son UTF-8 válido y legibles por humanos.
- Los enlaces locales, scripts, hojas de estilo, imágenes y otros assets se resuelven.
- Los enlaces y assets locales del sitio usan rutas relativas a la página por defecto, no rutas absolutas a la raíz como
/assets/style.css. - La salida se puede abrir directamente desde
index.htmlpara una vista previa manual a menos que el usuario haya aceptado explícitamente un comportamiento solo-servidor. - Las páginas generadas cubren los tipos de página esperados.
- El sitio se renderiza en un navegador real a través de HTTP local.
- Los diseños de escritorio y móvil son utilizables.
- Se reportan o corrigen errores de consola, interacciones rotas, placeholders restantes y texto fuente específico copiado.
Contrato
Entradas:
- Raíz del sitio estático, como
site/,dist/,out/,public/,docs/o raíz del repositorio. - Opcional: alcance de página esperado, URL de vista previa local,
EDITING.md, URL/captura de referencia y cadenas fuente específicas prohibidas.
Salidas:
- Hallazgos ordenados por severidad, o correcciones cuando la validación es parte de una tarea de compilación/corrección.
- Resultados de auditoría estática, páginas del navegador/viewports verificados y archivos modificados si los hay.
- Estado claro de éxito/fallo para la preparación de publicación o entrega.
Límites:
- No elegir temas, recrear sitios web, migrar contenido, personalizar identidad ni desplegar.
- No rediseñar el sitio durante la validación a menos que un problema visual bloquee la usabilidad y el usuario haya solicitado correcciones.
- No aprobar rutas absolutas a la raíz del sitio a menos que se use intencionalmente
--allow-root-absolutey se indique la limitación.
Puerta de éxito:
- No queda ningún bloqueador: navegación primaria rota, tipo de página requerida faltante, codificación fuente ilegible, fallo de asset local, cuelgue de consola, inutilizabilidad en móvil o problema accidental de ruta absoluta a la raíz.
- Las advertencias están corregidas, documentadas o aceptadas por el usuario.
Si la puerta falla:
- Corregir problemas locales sencillos cuando la validación es parte de la compilación.
- Enrutar fallos mayores a
make-personal-site,copy-website-style,personalize-site,add-blog-postsoedit-site-partsegún la superficie fallida. - Re-ejecutar la auditoría determinista y las verificaciones de navegador afectadas.
Usar Con
Usa esta skill después de:
make-personal-sitecrea o rediseña un sitio personal estático original.copy-website-stylerecrea el estilo de un sitio objetivo como archivos estáticos.- Un usuario señala una carpeta de salida estática existente y pregunta si es suficientemente buena.
- Un usuario pide verificar, validar, hacer QA, inspeccionar, auditar o probar un sitio estático antes de publicar.
Si el usuario da un proyecto con framework, valida la carpeta de salida estática ya construida cuando sea posible. No introducir un flujo de trabajo de compilación de framework aquí a menos que el usuario lo solicite explícitamente.
Entradas
Usa cualquier entrada disponible:
- Carpeta raíz del sitio estático, como
site/,dist/,out/opublic/. - URL de vista previa local, si ya hay un servidor en ejecución.
- Alcance de página esperado: solo página de inicio, sitio personal completo, blog, portafolio, notas, enlaces, recreación de estilo, etc.
EDITING.md, mapa de páginas o cualquier nota de entrega producida por otra skill.- URL de referencia o captura de pantalla, al validar una recreación de estilo.
- Cadenas conocidas que no deben permanecer, como nombres de autores originales, dominios, correos electrónicos, IDs de analytics o texto placeholder antiguo.
Si la raíz del sitio no está clara, inspecciona las carpetas cercanas y elige la que contenga index.html y assets estáticos.
Flujo de Trabajo
- Identificar la raíz del sitio estático y el alcance de página esperado.
- Leer
EDITING.mdo inferir el mapa de páginas desde archivos HTML y enlaces de navegación. - Ejecutar el script de auditoría de archivos determinista.
- Iniciar o reutilizar un servidor HTTP local para la raíz estática.
- Validar el sitio en un navegador real con anchos de escritorio y móvil.
- Abrir al menos una página representativa por cada tipo de página generado.
- Probar interacciones principales como navegación, cambio de tema, búsqueda/filtro, botones de copia, menú móvil y paginación.
- Verificar errores de consola del navegador y recursos de red faltantes.
- Auditar compatibilidad de rutas relativas, placeholders, legibilidad UTF-8 y texto fuente específico sobrante.
- Corregir defectos sencillos cuando el usuario solicitó validación como parte de una compilación; de lo contrario, informar los hallazgos primero.
Auditoría de Archivos Determinista
Usa el script incluido antes de la validación en navegador:
python scripts/static_site_check.py <site-root>
Para recreaciones de estilo o limpiezas de sitios copiados, pasa cadenas fuente específicas prohibidas:
python scripts/static_site_check.py <site-root> --forbid "original-author" --forbid "original-domain.com"
El script verifica:
- Decodificación UTF-8 para archivos HTML, CSS, JS, JSON, Markdown, SVG, XML y texto.
- Mojibake sospechoso y caracteres de reemplazo.
- Falta de
<meta charset="utf-8">en archivos HTML. - Referencias locales rotas en
href,src,srcset,poster,actionydata-src. - Referencias locales absolutas a la raíz como
/assets/...,/posts/...,/data/...o/images/...a menos que estén explícitamente permitidas. - Referencias a assets en CSS
url(...), incluyendo URLs locales faltantes o absolutas a la raíz. - Cadenas locales absolutas a la raíz comunes dentro de HTML, JavaScript y datos JSON.
- Enlaces que escapan de la raíz del sitio.
- Cadenas placeholder comunes.
- Cadenas prohibidas proporcionadas con
--forbid. - Archivos sensibles a la privacidad en la raíz de despliegue como
.env, claves privadas, archivos de credenciales y artefactos locales de cuentas de servicio. - Asignaciones similares a secretos, patrones de token conocidos, bloques de clave privada y rutas absolutas del sistema de archivos local en texto fuente.
- Artefactos temporales, de registro, copia de seguridad y del sistema operativo que no deberían publicarse.
- Recuento de páginas HTML y tipos de página inferidos.
- Si existe
EDITING.md.
La auditoría de archivos debe verificar la legibilidad UTF-8 incluso para archivos de proveedores, pero no debe tratar palabras similares a placeholder dentro de bundles minificados de terceros como contenido placeholder del sitio.
Trata los errores del script como bloqueadores a menos que el usuario solo quisiera una revisión exploratoria rápida. Trata las advertencias como elementos para inspeccionar manualmente.
Si el sitio está diseñado intencionalmente para requerir rutas relativas a la raíz bajo un dominio raíz personalizado, ejecuta el script con --allow-root-absolute e indica que no se garantizan la apertura directa con file:// ni el despliegue en subrutas de proyectos de GitHub. No uses esta excepción para sitios personales estáticos generados a menos que el usuario acepte explícitamente esa compensación.
Compatibilidad de Rutas
Los sitios estáticos generados deben funcionar en tres contextos comunes:
- Abrir directamente
index.htmldesde el sistema de archivos para una vista previa manual rápida. - Servir la carpeta sobre HTTP local para automatización de navegador y verificaciones de consola/red.
- Desplegar en un host estático que pueda servir el sitio desde una raíz de dominio o una subruta.
Regla por defecto:
- Usar rutas relativas a la página para enlaces y assets locales del sitio.
- Desde páginas raíz, usar
assets/style.css,posts/example.htmlyabout.html. - Desde páginas anidadas, usar
../assets/style.css,../blog.htmly enlaces relativos entre hermanos según corresponda. - No usar
/assets/style.css,/posts/example.html,/data/posts.json,/images/foo.pngni/para navegación interna por defecto.
También verificar enlaces generados por JavaScript, resultados de búsqueda, filtros de etiquetas, botones de copia, tarjetas dinámicas, referencias RSS/sitemap, portadas de imágenes, valores CSS url(...), favicons, fuentes y assets de proveedores KaTeX/math. No es suficiente que los atributos HTML estáticos sean relativos si JavaScript luego inserta rutas absolutas a la raíz.
Las rutas absolutas a la raíz solo son aceptables cuando el usuario quiere explícitamente un despliegue solo de raíz de servidor, como un dominio raíz personalizado, y entiende que la apertura directa de archivos y las subrutas de GitHub Pages pueden romperse.
Validación en Navegador
Usa un navegador real antes de la entrega final. Sirve los archivos locales sobre HTTP, no con file://:
python -m http.server 8000
Luego abre:
http://127.0.0.1:8000/
Usa una herramienta de navegador interactiva realmente disponible como primera opción de validación para destinos HTTP locales. "Disponible" significa que la herramienta está expuesta en la lista de herramientas invocables del turno actual, no solo mencionada en una skill, lista de plugins o descripción del sistema. En Codex puede ser el plugin Browser/navegador en la aplicación cuando el usuario o cliente lo ha enrutado al turno; en otros agentes puede ser un navegador visible equivalente, herramienta browser-use o navegador con soporte de devtools. Debe abrir la URL local, inspeccionar viewports de escritorio/móvil, ejercitar interacciones y verificar problemas visibles de consola/red.
Si ninguna herramienta de navegador interactiva está expuesta en el turno actual, no pretendas que la pasada del navegador ocurrió. Si la validación depende de ello, pide al usuario que habilite o invoque la herramienta de navegador usando el método de enrutamiento de su cliente; para Codex, puede significar enviar una solicitud que mencione explícitamente @browser. Si el usuario no re-enruta o el cliente no tiene tal herramienta, recurre a Playwright, capturas de pantalla, auditorías estáticas o verificaciones de shell e indica que esto fue un recurso de respaldo, no una validación completa de navegador interactivo.
No recurras por defecto a Playwright, scripts de captura de pantalla solo headless, ventanas de navegador abiertas por shell o generación estática de capturas cuando una herramienta de navegador interactiva es realmente invocable. Las capturas de pantalla son evidencia útil, pero no reemplazan una pasada de navegador interactiva. Usa Playwright solo como recurso de respaldo cuando no haya una herramienta de navegador interactiva invocable, cuando el usuario pida explícitamente Playwright o cuando se necesite específicamente una regresión scripteada repetible.
Usa automatización de Chrome solo cuando la tarea necesite el perfil de Chrome del usuario, pestañas existentes, extensiones, páginas remotas autenticadas o comportamiento específico de Chrome. No confíes en la automatización de extensiones de Chrome para páginas file://; usa HTTP local en su lugar.
Aunque la automatización debe usar HTTP local, el código fuente generado debe seguir siendo compatible con apertura directa usando rutas relativas y evitando suposiciones solo de servidor para el contenido principal. Si la aplicación/navegador permite una verificación rápida con file://, abre index.html directamente y verifica que CSS, imágenes, navegación y subpáginas representativas no estén rotos. Si la automatización de archivos no está disponible, confía en la auditoría determinista de rutas absolutas a la raíz y menciona si la apertura directa fue verificada manual o automáticamente.
Verificaciones del navegador:
- Primera pantalla en escritorio: composición, espaciado, tipografía, navegación visible y desbordamiento evidente.
- Primera pantalla en móvil: comportamiento de navegación, ajuste de texto, prioridad de contenido y desbordamiento horizontal.
- Navegación interna: todos los enlaces de navegación principal se renderizan.
- Cobertura de tipos de página: al menos una pasada de navegador o captura para cada tipo de página generado.
- Cobertura de interacciones: cambios de tema, menús, filtros, búsqueda, botones de copia, paginación, acordeones, pestañas, estados hover/click u otros controles visibles.
- Estado de consola: sin errores obvios de JavaScript.
- Estado de red: sin assets CSS, JS, imagen o fuente locales faltantes.
- Conceptos básicos de accesibilidad: visibilidad de enfoque para controles interactivos, contraste legible, títulos de página significativos y texto alternativo no vacío para imágenes cuando sea práctico.
Para sitios pequeños, haz clic en cada página generada. Para sitios más grandes, muestrea cada tipo de página y cualquier ruta mencionada en EDITING.md.
Cobertura de Tipos de Página
Infiere los tipos de página a partir de nombres de archivo, rutas, navegación visible y EDITING.md.
Tipos de página típicos:
- Inicio.
- Acerca de o perfil.
- Blog, archivo, categoría, etiqueta, notas o lista.
- Artículo o página de detalle.
- Proyectos, portafolio, publicaciones o trabajo.
- Enlaces, amigos, recursos, ahora, usos, jardín, búsqueda, tema/configuración u otra página especial.
Si un sitio generado dice ser un blog pero no tiene página de artículo/detalle, repórtalo. Si tiene navegación a subpáginas que no existen, repórtalo como bloqueador.
Codificación y Legibilidad de Fuente
Las capturas de pantalla del navegador no son suficientes. Los archivos fuente deben ser legibles por modelos futuros y humanos.
Requisitos:
- Los archivos HTML incluyen
<meta charset="utf-8">. - El texto no ASCII se almacena como UTF-8.
- Los comentarios en HTML, CSS, cadenas de JavaScript, archivos JSON/datos, texto SVG y
EDITING.mdson legibles en forma fuente. - Sin mojibake, caracteres de reemplazo ni recuperación accidental de codificación del navegador.
Si un terminal muestra mojibake pero el navegador se ve correcto, confirma con una lectura consciente de UTF-8 antes de declararlo como roto. Si el contenido del archivo en sí contiene mojibake, reescribe las cadenas afectadas desde texto limpio en lugar de añadir otra conversión de codificación.
Auditoría de Placeholders y Residuos
Verifica si el sitio generado aún contiene:
TODO,FIXME,lorem ipsum,placeholder,replace me,your name,example.como texto de muestra/demo.- Correos electrónicos ficticios, enlaces sociales falsos, botones vacíos o llamadas a la acción muertas.
- Nombres de autores del sitio original, dominios, títulos de artículos, correos electrónicos, IDs de analytics, enlaces sociales, enlaces de amigos o URLs privadas en recreaciones de estilo.
No elimines placeholders a ciegas si el usuario todavía los necesita como marcadores editables intencionales. Repórtalos claramente, o reemplázalos solo cuando el usuario haya proporcionado contenido real.
Privacidad y Residuos Locales
Trata estos como bloqueadores antes de publicar:
.env,.npmrc,.pypirc, archivos de clave privada, archivos JSON de credenciales, archivos de cuenta de servicio o archivos de exportación/almacén de contraseñas dentro de la raíz desplegable.- Asignaciones similares a secretos, tokens de acceso, bloques de clave privada o claves API en archivos HTML, CSS, JavaScript, JSON, Markdown, SVG o texto.
- Rutas absolutas del sistema de archivos local como rutas de disco de Windows,
file:///...,/Users/...,/home/...o/mnt/...en el código fuente generado.
Trata los registros, copias de seguridad, archivos temporales y metadatos del sistema operativo como advertencias a menos que expongan contenido privado. Elimínalos de la salida desplegable antes de empaquetar o publicar.
Política de Corrección
Cuando el usuario pida "verificar", "revisar" o "decirme qué está mal", reporta los hallazgos primero y evita ediciones amplias.
Cuando la validación sea parte de una compilación o tarea de corrección explícita, aplica correcciones locales para:
- Placeholders y residuos de texto fuente específico, pero solo cuando el usuario haya proporcionado contenido de reemplazo real.
- Cambios de rutas absolutas a la raíz a rutas relativas a la página para enlaces y assets locales, siempre que el sitio no esté diseñado intencionalmente para un dominio raíz.
- Adición de
<meta charset="utf-8">faltante. - Corrección de mojibake en bloques de texto pequeños y bien definidos.
- Eliminación de archivos sensibles a la privacidad, artefactos de registro y archivos temporales de la carpeta de salida.
- Ajustes visuales menores que no requieran rediseño de diseño ni cambios estructurales, como márgenes claramente rotos, superposiciones de texto o problemas de desbordamiento que bloqueen la usabilidad en viewports de escritorio o móvil.
Cuando la corrección requiera elegir una dirección de diseño (por ejemplo, qué variante de estilo usar, qué contenido de reemplazo insertar para placeholders o si eliminar un enlace de navegación que apunta a una página faltante), detente y pregunta. No tomes decisiones subjetivas de diseño por el usuario.
Cuando la validación se ejecute como control previo a make-personal-site, copy-website-style u otra skill que regenere o reescriba el sitio, limítate a informar hallazgos y no modifiques archivos. La skill siguiente gestionará la corrección.
Integración
from-idea-to-personal-site invoca esta skill para validar la salida de make-personal-site, y personalize-site para verificar la personalización.
copy-website-style invoca esta skill para validar que la recreación de estilo no haya copiado residuos fuente específicos ni haya dejado enlaces de navegación apuntando al sitio original.
Herramientas Comunes
- Buscador de archivos / grep / glob para inspeccionar estructura y contenido.
- Scripts de Python para auditoría de archivos determinista (
scripts/static_site_check.py). - Servidor HTTP local (
python -m http.server). - Herramienta de navegador interactiva, Playwright o automatización de Chrome para pruebas en navegador.
- Lector/Buffer de archivos para verificar legibilidad UTF-8.
- Editor de archivos para correcciones, cuando esté autorizado.
Nota sobre Scripts
Si scripts/static_site_check.py no existe en el repositorio, muñeca los mismos controles usando herramientas de línea de comandos (grep, find, file, python3) o escribe un script de verificación ad-hoc que implemente la misma lógica de verificación. El script no debe depender de paquetes externos de terceros; debe ejecutarse solo con la biblioteca estándar de Python y herramientas comunes de shell.