Revisión de SEO en HTML
Resumen
Genera una lista de hallazgos clasificados por gravedad y procesables para uno o más archivos HTML estáticos. La habilidad agrupa un analizador HTML que solo utiliza la biblioteca estándar y que extrae cada señal relevante para SEO en un único documento JSON, una rúbrica completa y una plantilla de informe de hallazgos; todo ello permite que una auditoría se ejecute con resultados predecibles en cada ocasión.
Cuándo usarlo
Úsalo cuando la entrada sea uno o más archivos .html estáticos (o un directorio de ellos) y el usuario quiera hallazgos de SEO en página que pueda aplicar. Los desencadenantes incluyen "revisión SEO", "auditoría SEO", "verifica el SEO en este HTML", "revisa las metaetiquetas de esta página", "audita el SEO en página".
No lo uses cuando:
- El artefacto sea código fuente de un generador de sitios estáticos (Jekyll/Hugo/Astro/Eleventy/Next.js). Esos necesitan una revisión que tenga en cuenta el origen; difiere a una futura habilidad
ssg-seo-review. - El usuario quiera métricas de rendimiento en vivo (LCP, CLS, INP). Solo el HTML no puede producirlas; recomienda Lighthouse o PageSpeed Insights.
- El usuario quiera análisis de backlinks, autoridad de dominio u otros análisis fuera de página. Eso requiere herramientas de terceros (Ahrefs, SEMrush, etc.).
Flujo de trabajo
1. Extraer señales
Ejecuta el analizador contra el objetivo. Acepta un solo archivo o un directorio (recursivo *.html):
python3 scripts/extract_seo_signals.py <ruta> --pretty
La salida es un documento JSON con las siguientes claves de primer nivel: lang, title, meta, links, scripts, headings, images, links_audit, body_word_count. Cada elemento lleva un número de line para citarlo en los hallazgos.
Para un directorio, la salida es {"files": [<objeto por archivo>]}.
El script solo utiliza la biblioteca estándar de Python — no requiere pip install. Si el análisis falla en un archivo específico, el resultado para ese archivo contiene un campo error y la auditoría continúa con el resto.
2. Mapear las señales a la rúbrica
Carga references/seo-checklist.md. Recorre cada sección en orden y verifica la ruta JSON correspondiente. La rúbrica enumera explícitamente la ruta a inspeccionar para cada comprobación (por ejemplo, images.missing_alt, meta.description.length, scripts.render_blocking_candidates).
Para cada comprobación fallida, registra:
- La gravedad (P0/P1/P2/P3) de la rúbrica.
- El número de línea de la salida JSON.
- El marcado exacto citado o el valor del atributo del archivo (vuelve a leer el archivo con el número de línea para citar textualmente — nunca parafrasees).
- La corrección, escrita como una diferencia concreta de antes/después cuando el cambio sea mecánico.
3. Verificar cada hallazgo antes de informar
Antes de redactar un hallazgo, confirma el problema mecánicamente:
- Una afirmación de que un atributo "falta" debe provenir de la salida estructurada del analizador, no de hojear el HTML.
- Una afirmación de que un valor es "demasiado corto/largo" debe citar el recuento de caracteres real del JSON.
- El marcado citado debe ser exacto; si no se puede reproducir una cita carácter por carácter a partir del archivo, omítela.
Esto protege contra el fallo de revisión más común: inventar un problema que en realidad no existe.
4. Generar el informe de hallazgos
Usa assets/findings-template.md como estructura. Completa:
- Párrafo de resumen con veredicto general y recuentos de gravedad.
- Un bloque por hallazgo, ordenado por gravedad (P0 → P3) y luego por orden de archivo.
- Una sección opcional "Victorias rápidas" cuando el número de hallazgos supere ~10 — elige las 3-5 correcciones de mayor impacto.
- Una sección "Elementos fuera del alcance anotados" que enumere cualquier cosa que el usuario deba revisar con herramientas externas (Lighthouse para CWV real, curl para resolución canónica, etc.).
Si la auditoría cubre varios archivos, genera un informe que los cubra todos, con los hallazgos agrupados por archivo dentro de cada nivel de gravedad, no un informe por archivo.
5. Omitir con elegancia
Si una comprobación requiere información que el analizador no puede producir (por ejemplo, "¿esta URL canónica devuelve un 200?"), no adivines. Anótalo en la sección "Elementos fuera del alcance" del informe y continúa.
Referencia
scripts/extract_seo_signals.py— Analizador HTML. Solo biblioteca estándar. Genera JSON estructurado con números de línea.references/seo-checklist.md— Rúbrica completa, organizada por categoría, con niveles de gravedad y rutas JSON para cada comprobación.assets/findings-template.md— Formato de salida para el informe de auditoría.