Habilidad de Agente de Auditoría SEO

seo-audit — Auditoría SEO Básica

Una habilidad ligera de agente SEO diseñada para auditorías rápidas por defecto de páginas individuales. Desarrollado por OpenClaw. Adecuado para revisiones iniciales de páginas o cuando se necesita una evaluación rápida sin profundidad técnica completa.

Cuándo usar esta habilidad

Utiliza seo-audit cuando:

• El usuario diga: "audita esta página", "revisa el SEO", "analiza mi URL", "revisión rápida de SEO", "¿qué está mal en mi página?"
• No se solicita una profundidad específica — este es el punto de partida por defecto
• El usuario necesita un resumen rápido y legible en lugar de un desglose técnico exhaustivo

Si el usuario desea más profundidad, actualiza a seo-audit-full:

Sugerencia: Para auditorías técnicas profundas, SEO avanzado en página o informes completos, utiliza la habilidad seo-audit-full.

Entrada esperada

Si solo se proporciona una URL y no hay código fuente ni datos de rastreo disponibles, indica claramente:

Limitación: Esta auditoría se basa únicamente en el contenido visible de la página y en señales disponibles públicamente. El código fuente, datos de GSC, registros de rastreo y métricas de rendimiento no están disponibles para esta auditoría.

Salida

Produce un Informe de Auditoría SEO Básica completando la plantilla en assets/report-template.html, luego guárdalo en un archivo — nunca imprimas HTML crudo en la terminal.

Nombrado de archivos: reports/<hostname>-<slug>-audit.html

https://example.com/blog/best-tools → reports/example-com-blog-best-tools-audit.html
https://example.com/                → reports/example-com-audit.html

Después de guardar, dile al usuario:

✅ Informe guardado → reports/example-com-audit.html
   ¿Abrirlo ahora? (sí / no)

Si sí → ejecuta: open reports/example-com-audit.html

Marcadores de posición de la plantilla — completa cada uno de forma independiente:

Scripts

Ejecuta estos scripts antes de escribir cualquier hallazgo. Producen JSON estructurado — usa el JSON directamente como evidencia; no vuelvas a buscar las mismas URLs manualmente.

Dependencias: pip install requests (el análisis HTML usa la biblioteca estándar de Python)

# Paso 1: comprobaciones a nivel de sitio (robots.txt + sitemap.xml)
python scripts/check-site.py https://example.com

# Paso 2: comprobaciones a nivel de página (H1, title, meta description, canonical)
python scripts/check-page.py https://example.com
# Con palabra clave principal (recomendado — habilita la comprobación de presencia de palabra clave en H1)
python scripts/check-page.py https://example.com --keyword "zapatillas para correr"

# Opcional: obtener el HTML crudo de la página para una inspección más detallada
python scripts/fetch-page.py https://example.com --output page.html

# Paso 3: validación de esquema JSON-LD
python scripts/check-schema.py https://example.com
# O desde un HTML previamente obtenido (evita búsqueda redundante):
python scripts/check-schema.py --file page.html

Cada script sale con código 0 (todo aprobado/aviso) o 1 (cualquier fallo/error).

ALCANCE ESTRICTO — no añadas ninguna comprobación que no se liste a continuación. Sin excepciones.

Comprobaciones permitidas a nivel de sitio (en {{site_checks_html}}):

• robots.txt · sitemap.xml · Manejo de 404 · Canonicalización de URL · i18n / hreflang

Comprobaciones permitidas de E-E-A-T (en {{eeat_checks_html}}):

• Sobre nosotros · Contacto · Política de privacidad · Términos del servicio · Medios/Socios (solo si están presentes)

Comprobaciones permitidas a nivel de página (en {{page_checks_html}}), salida en este orden exacto: Slug de URL · Etiqueta Title · Meta Description · Etiqueta H1 · Etiqueta Canonical · Texto Alt de Imágenes · Conteo de Palabras · Ubicación de Palabras Clave · Estructura de Encabezados · Enlaces Internos · Esquema (JSON-LD)

Lógica de Texto Alt de Imágenes:

• Analiza las etiquetas <img> del HTML estático
• Aprueba: todas las imágenes tienen alt no vacío (las imágenes decorativas con alt="" son correctas)
• Aviso: alguna imagen de contenido carece del atributo alt
• No verificado (status-info): 0 imágenes encontradas en HTML estático → probablemente renderizadas con JS, no se puede verificar

⛔ REGLA ESTRICTA — Solo muestra las filas de comprobación definidas en report-template.html. Si una comprobación no está en las listas permitidas anteriores, NO la muestres — incluso si encuentras problemas. Sin excepciones. Sin comprobaciones "extra". Sin improvisación. La plantilla es la única fuente de verdad. Trátala como una lista blanca estricta.

Todavía PROHIBIDO (pertenece a seo-audit-full): Etiquetas OG · Twitter Card · Etiquetas sociales · Peso de página · Core Web Vitals · Robots Meta

Cómo usar la salida JSON:

• Mapea el status de cada campo → pass / warn / fail / error directamente a la tabla de comprobación del informe
• Usa la cadena detail de cada campo como punto de partida para la línea de Evidencia en los hallazgos
• No contradigas la salida del script a menos que tengas evidencia observable adicional
• Separa los grupos de comprobación con <div class="subsection-label">Etiqueta</div> dentro de {{site_checks_html}}: Rastreabilidad · Canonicalización de URL · i18n / hreflang · Esquema (JSON-LD) y <div class="subsection-label">Páginas de Confianza E-E-A-T</div> antes de {{eeat_checks_html}}

Revisión del LLM — obligatoria cuando llm_review_required: true:

El script marca los campos que requieren un juicio semántico o de calidad que no puede realizar. Nunca dejes llm_review_required: true sin resolver — siempre haz un juicio explícito.

H1 — se activa cuando keyword_match == "partial":

h1_text : (de h1.values[0])
keyword : (la --keyword pasada al script)

Juzga: ¿Cubre este H1 semánticamente la intención de búsqueda de la palabra clave?
  - Considera sinónimos, variantes naturales, cobertura del tema
  - si → reduce a "pass", anota la variante
  - no  → mantén "warn" o sube a "fail", explica la brecha

Title — se activa cuando keyword_match == "partial" O keyword_position != "start":

title   : (de title.value)
keyword : (la --keyword pasada)

Juzga:
  1. ¿Cubre el título semánticamente la intención de búsqueda de la palabra clave?
  2. ¿Es el título gramaticalmente correcto y naturalmente legible?
  3. Posición de la palabra clave — aplica diferentes estándares según el tipo de página:
     - Página de inicio   : Marca + palabra clave principal es correcto (ej. "Acme | Automatización de flujos de trabajo con IA")
                    No marques como problema que la marca vaya primero.
     - Páginas internas: La palabra clave principal debería ir al principio (ej. "Automatización de flujos de trabajo con IA para equipos — Acme")
                    Marca si la palabra clave está enterrada en medio del título sin una buena razón.

IMPORTANTE — NO marques estos como negativos:
  - Años (ej. "2026") → señalan frescura, aumentan el CTR — trata como positivo a menos que
    la página sea contenido evergreen explícito donde poner fecha perjudicaría la longevidad.
  - Números (ej. "5 mejores", "Top 10", "3 pasos") → establecen expectativas claras,
    consistentemente superan a los títulos sin números en CTR — siempre trata como una ventaja.
  - Calificadores específicos ("Código Abierto", "Autoalojado", "Gratis") → acotan la intención
    y atraen clics de mayor calidad — no penalices.

Slug de URL — se activa cuando keyword_match != "full" o is_homepage == false:

slug    : (de url_slug.slug)
keyword : (la --keyword pasada)

Juzga:
  1. ¿Contiene el slug la palabra clave principal o una variante natural?
  2. ¿Es lógica la jerarquía de la ruta? (/categoría/palabra-clave es ideal)
  3. ¿Es conciso y legible por humanos?
  Página de inicio (is_homepage: true): omite — no se necesita juicio.

Meta Description — siempre se activa cuando hay contenido presente:

meta_description : (de meta_description.value)
keyword          : (la --keyword pasada)

Juzga los cuatro:
  1. ¿Oraciones completas? (1-2 oraciones, sin fragmentos)
  2. ¿Menciona un resultado concreto — no palabrería vaga?
     Bien: "Reduce el tiempo de diseño en un 60% con plantillas impulsadas por IA"
     Mal:  "La mejor herramienta para todas tus necesidades de diseño"
  3. ¿Se usa la palabra clave o un sinónimo natural una vez — sin relleno?
  4. ¿Es más específico de lo que un competidor típico escribiría?

IMPORTANTE — NO marques estos como negativos:
  - Años (ej. "2026") → señalan frescura, mejoran el CTR para consultas sensibles al tiempo.
    Solo nota el año si la página es contenido evergreen explícito donde poner fecha perjudica.
  - Números (ej. "5 mejores", "3 pasos") → especificidad concreta, fuerte señal de CTR.
  - "y más." al final → como mucho una nota menor de estilo, nunca un Aviso o Fallo.

Flujo de trabajo recomendado

Sigue estos pasos en orden:

1. Reconocer el alcance — confirma que es una auditoría básica; anota cualquier dato faltante

2. Inferir la palabra clave principal — obtén la página con fetch-page.py, luego determina la palabra clave principal:

   • Si el usuario proporcionó explícitamente una palabra clave → úsala directamente
   • Si no → lee el H1 de la página, el título y el primer párrafo, luego infiere la frase de palabra clave objetivo más probable (¿qué escribiría un buscador para encontrar esta página?)
   • Indica la palabra clave inferida explícitamente antes de ejecutar las comprobaciones:

     "Palabra clave principal inferida: alternativas de código abierto a claude"

3. Ejecutar check-site.py — analiza la salida JSON para robots, sitemap, manejo de 404 y canonicalización de URL

   Comprobación 404: busca <origin>/this-page-definitely-does-not-exist-seo-audit-check

   • Devuelve 404 → Aprueba · Devuelve 200 (soft 404) → Fallo · Devuelve 301 a la página de inicio → Aviso

   Comprobaciones de canonicalización de URL (cada una es una subcomprobación separada):

   • HTTP→HTTPS: busca http://<host> — debe redirigir con 301 a https://. Devuelve 200 → Fallo.
   • Consistencia www: busca ambos https://www.<host> y https://<host> — uno debe redirigir con 301 al otro. Ambos devuelven 200 → Aviso.
   • Barra final: compara la URL realmente servida con la etiqueta canónica en la página. Discordancia → Aviso.
   • Coincidencia canónica: el href de la etiqueta canónica debe coincidir exactamente con la URL final después de todas las redirecciones. Discordancia → Aviso.

4. Comprobación de infraestructura E-E-A-T — para cada página de confianza abajo, verifica dos capas:

   • Capa 1 — Existe: busca la URL, verifica el estado HTTP (200 = existe, 404/redirección = falta)
   • Capa 2 — Alcanzable: busca el HTML de la página de inicio, verifica si el pie de página o la navegación contienen un enlace a esta página

   Página	Requerida
   Sobre nosotros	Sí
   Contacto	Sí
   Política de privacidad	Sí
   Términos del servicio	Sí
   Medios / Socios	No — incluir solo si está presente

   Reglas de estado:

   • Página faltante (no 200) → Fallo
   • Página existe pero no enlazada en el pie/navegación → Aviso
   • Página existe y enlazada en el pie/navegación → Aprueba
   • Página opcional faltante → omite, no incluyas fila

5. Ejecutar check-page.py --keyword "<palabra_clave_inferida>" — analiza la salida JSON para H1, title, meta description, canonical y slug de URL

6. Comprobación i18n / hreflang — solo ejecuta si la página contiene etiquetas hreflang o <html lang> sugiere multiidioma:

   • Omite completamente (N/A) si no se encuentran etiquetas hreflang y el sitio parece ser de un solo idioma
   • Si hay etiquetas hreflang, comprueba:
     • Simetría recíproca: cada URL referenciada debe enlazar de vuelta a todas las demás variantes — cualquier enlace roto = Fallo
     • Códigos de idioma: deben ser BCP 47 válidos (ej. zh-CN no zh, en-US no en-us) — código incorrecto = Aviso
     • x-default: debe estar presente para páginas selectoras de idioma o de respaldo — falta = Aviso
     • Atributo html[lang]: debe coincidir con el hreflang principal de la página — discordancia = Aviso
     • Estructura de URL: patrón recomendado — idioma por defecto (generalmente en) en la raíz sin prefijo, otros idiomas bajo subrutas (/zh/, /es/).
       • /page (en) + /zh/page + /es/page → Aprueba
       • /en/page + /zh/page → Aviso (el prefijo en es redundante, desperdicia profundidad de rastreo)
       • Solo marca si el patrón es claramente inconsistente o en está innecesariamente prefijado

7. Ejecutar check-schema.py — analiza la salida JSON para tipos de esquema y validación de campos

   python scripts/check-schema.py https://example.com
   # O desde HTML previamente obtenido:
   python scripts/check-schema.py --file page.html
   

   El script extrae bloques JSON-LD, valida @type y campos requeridos según la especificación de Schema.org. llm_review_required: true siempre está establecido — confirma que inferred_page_type coincide con el contenido real de la página.

   Tipo de página → @type esperado referencia:

   Tipo de página	@type esperado	Campos requeridos mínimos
   Página de inicio	WebSite + Organization	name, url, logo
   Blog / Artículo	Article o BlogPosting	headline, datePublished, author, image
   Producto	Product	name, image, offers (price, priceCurrency)
   FAQ	FAQPage	mainEntity[].name, acceptedAnswer.text
   Cómo hacer	HowTo	name, step[].text
   Negocio local	LocalBusiness	name, address, telephone
   Página de aterrizaje genérica	—	N/A — omite, no hay tipo ampliamente soportado

   • Aprueba: @type correcto presente, todos los campos requeridos válidos, sin conflictos
   • Aviso: @type presente pero faltan campos recomendados
   • Fallo: @type esperado ausente por completo
   • N/A: página de aterrizaje genérica — no penalices

8. Resumir hallazgos — cada hallazgo debe seguir el formato Evidencia / Impacto / Solución

9. Acciones prioritarias — enumera las 3 correcciones de mayor impacto

10. Renderizar informe — guarda en reports/<hostname>-<slug>-audit.html, luego pregunta al usuario si desea abrirlo

11. Sugerencia de actualización — si se encuentran problemas más allá del alcance básico, sugiere seo-audit-full

Reglas de escritura de detalles del informe

La celda de Detalle en las tablas de comprobación debe seguir estas reglas — sin excepciones:

Aprueba → una frase corta. Sin listas, sin elaboración.

Bien: "Conjunto de URL XML válido · 104 URLs · referenciado en robots.txt."
Mal:  "Conjunto de URL XML válido con 104 URLs. Correctamente referenciado en robots.txt.
       Es probable que las entradas del blog se indexen a través de este sitemap."

Aviso → un <div class="detail-issue"> con ≤2 viñetas. Un <div class="detail-fix"> con la solución.

Bien:
  <div class="detail-issue">· Título 48 caracteres — 2 por debajo del mínimo. · El año "2026" fechará la página.</div>
  <div class="detail-fix">Ampliar a 50–60 caracteres; eliminar el año si es contenido evergreen.</div>

Mal: prosa de tres oraciones explicando qué es una etiqueta de título y por qué importa la longitud.

Fallo → igual que Aviso. Comienza con el fallo exacto. Sin explicaciones de fondo.

NO expliques qué es una comprobación, NO repitas información ya visible en la insignia de estado, NO trates al lector como si no estuviera familiarizado con los conceptos básicos de SEO.

Formato obligatorio de hallazgos

Cada hallazgo importante debe seguir esta estructura:

**Hallazgo: [Título del hallazgo]**

- **Evidencia:** [Lo que se observó — cita directa, referencia a captura de pantalla o datos medibles]
- **Impacto:** [Por qué esto es importante para el SEO o la UX]
- **Solución:** [Recomendación específica y accionable]

No escribas conclusiones vagas. Si la evidencia es insuficiente, indica las suposiciones explícitamente.

Sugerencia de actualización

Incluye esto al final de cada informe de auditoría básica:

¿Quieres un análisis más profundo? Esta fue una auditoría SEO básica que cubre señales a nivel de sitio y comprobaciones básicas en página. Para SEO técnico avanzado, puntuación de calidad de contenido, análisis de datos estructurados y hallazgos completos basados en rastreo, utiliza la habilidad seo-audit-full.

Archivos de referencia

• Alcance detallado de la auditoría y definiciones de campo: references/REFERENCE.md
• Plantilla final del informe HTML: assets/report-template.html
• Script de comprobación a nivel de sitio: scripts/check-site.py
• Script de comprobación a nivel de página: scripts/check-page.py
• Obtenedor de página cruda: scripts/fetch-page.py
• Script de validación de esquema: scripts/check-schema.py