ChaoticSurfer/seo-suite

Analítica: medir, diagnosticar, informar

Convierte datos de primera mano (Search Console, Bing Webmaster, GA4, registros del servidor) en decisiones. Diagnostica caídas con un árbol de decisión fijo en lugar de adivinar, y mide los cambios con honestidad.

Cuándo usar / no usar

Úsalo para:

• Exportaciones de Search Console, Bing Webmaster y GA4.
• Caídas de tráfico y preguntas sobre actualizaciones de algoritmos.
• Objetivos de optimización del CTR.
• Canibalización.
• Análisis de registros de rastreo.
• Paneles de KPIs.
• Pruebas antes/después.

No para:

• Encontrar defectos en el sitio → seo-technical, seo-audit. Este skill los llama cuando el árbol de caídas apunta hacia allí.
• Ideas de palabras clave para nuevas páginas → seo-keywords.
• Visibilidad de competidores → seo-competitors.

Entradas que recopilar

• Exportaciones de rendimiento de Search Console.
  • Exportación de la IU: Queries.csv / Pages.csv (solo las 1.000 primeras filas).
  • Exportación de la API o Looker Studio con filas de consulta+página: necesaria para la canibalización. Límite de la API: 25k filas/solicitud, ~50k filas/día/tipo (google-rules §11).
  • Para comparaciones: dos ventanas de igual duración, alineadas por día de la semana, excluyendo los últimos 2-3 días (los datos de GSC tienen retraso).
• Expresión regular de marca. Nombre de la marca más errores ortográficos, ej. acme|acme ?corp|აკმე.
• Opcional:
  • Exportación de Bing Webmaster (misma estructura; funciona con gsc_analyze).
  • Informe de páginas de aterrizaje orgánico de GA4.
  • Registros de acceso al servidor (.log / .gz).
  • Las fechas de cambios en el sitio, despliegues y migraciones.
• Para caídas: cuándo comenzó, qué sección/país/dispositivo, y si las conversiones también cayeron.

Flujo de trabajo

A. Análisis de oportunidades (exportación de GSC/Bing)

1. Ejecuta el análisis:

   mkdir -p seo-work
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gsc_analyze.py" Queries.csv --brand "brand|brnd" --min-impressions 50 > seo-work/gsc.json
   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gsc_analyze.py" query_page.csv --brand "brand" > seo-work/gsc-qp.json   # canibalización
   

   Banderas: --striking-from 4 --striking-to 20 (valores por defecto); aumenta --min-impressions en sitios grandes.

2. Lee striking_distance (posiciones 4-20, ordenadas por est_extra_clicks_at_pos3 [estimación]). Estas son las páginas que mejorar primero. Envía cada una a seo-onpage / seo-content con su consulta.

3. Lee ctr_underperformers. Las 10 consultas principales cuyo CTR está por debajo de la mitad de la mediana de CTR de este sitio para esa posición (ctr_curve_used; recurre a valores por defecto cuando hay muy pocos datos).

   • Causas: título/snippet débil, una función SERP o AI Overview por encima del resultado, o desajuste de intención.
   • Inspecciona la SERP en vivo con WebSearch antes de reescribir.

4. question_queries: material para secciones de FAQ y pasajes con respuesta prioritaria (seo-content, seo-ai-search).

5. brand_split: informa los clics no relacionados con la marca por separado. La demanda de marca no es rendimiento SEO.

6. cannibalization: una consulta donde 2+ páginas reciben cada una ≥10% de las impresiones. Decide por caso: fusionar + 301, diferenciar la intención, o dirigir enlaces internos a la página principal. No toda división es un problema: si ambas páginas posicionan bien, déjalas.

B. Comparación de períodos y diagnóstico de caídas de tráfico

1. Ejecuta la comparación:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/gsc_analyze.py" last_28d.csv --compare prev_28d.csv > seo-work/gsc-compare.json
   

   Cada perdedor recibe un likely_cause:

   • "rankings dropped"
   • "fewer impressions at similar rank" (demanda, o una función SERP)
   • "CTR fell at similar rank"

   Estas son heurísticas: fórmulalas como "consistente con".

2. Recorre el árbol de caídas en orden y detente en la primera rama que la evidencia respalde. Registra la evidencia para cada rama:

   1. ¿Es real la caída?

      • Clics de GSC vs sesiones orgánicas de GA4, comparando la dirección de la tendencia (espera una diferencia de nivel del 10-20%).
      • Una caída solo en GA4 → problema de seguimiento/consentimiento/etiqueta, no SEO.
      • Compara año contra año para descartar estacionalidad.

   2. Técnico. Ejecuta en paralelo:

      • robots_check.py
      • sitemap_check.py
      • page_audit.py en las principales URL perdedoras
      • crawl.py en la sección afectada

      Busca:

      • noindex, cambios en canonical, 5xx/429, bloqueos de robots, cambios en redirecciones, un desafío de bot (bot-challenge).
      • Despliegues en la fecha de la caída.
      • El informe de indexación de páginas de Search Console para picos en "Excluidas" (seo-technical).

   3. Actualización de algoritmo. Compara la fecha de la caída con el Panel de estado de búsqueda de Google (https://status.search.google.com/ → incidentes de posicionamiento; recupéralo). La forma importa:

      • Un cambio abrupto en todo el sitio en una fecha de actualización coincide con una reevaluación de sistemas (contenido útil / core / spam). Ver google-rules §4.
      • Cambios específicos de sección apuntan a problemas a nivel de página.
      • Nunca digas "penalizado" a menos que Search Console muestre una acción manual.

   4. Estacionalidad / demanda. Año contra año en GSC (16 meses de datos; google-rules §11), más Google Trends para los términos principales. Impresiones bajas con posición estable = demanda.

   5. Desplazamiento en SERP. Posición estable pero CTR bajo. WebSearch las consultas:

      • ¿AI Overview presente? ¿Nuevas funciones (vídeo, PAA, compras, foros)? ¿Anuncios?
      • ¿Está disponible el informe "Search generative AI performance" de Search Console? (google-rules §10)

   6. Competidores. Posición perdida frente a URL específicas → seo-competitors (compare_pages en los ganadores). Consulta Wayback CDX para saber cuándo cambió su página.

3. Usa datos de registro cuando estén disponibles:

   python3 "${CLAUDE_PLUGIN_ROOT}/scripts/log_analyze.py" access.log access.log.1.gz --verify-dns --sitemap-urls seo-work/urls.txt > seo-work/logs.json
   

   Busca:

   • Visitas de Googlebot por día colapsando (problema de capacidad de rastreo: 5xx/429 o servidor lento; google-rules §1).
   • Errores servidos a bots.
   • Proporción de URL con parámetros (desperdicio de rastreo).
   • Rutas de sitemap nunca rastreadas.
   • IPs "Googlebot" falsas (unverified_ips).
   • Si los bots de IA (OAI-SearchBot, Claude-SearchBot, PerplexityBot) llegan al sitio en absoluto.

C. Informes y paneles

• KPIs. Separa los adelantados de los rezagados:
  • Adelantados: páginas indexadas (GSC), impresiones, posición media para clústeres objetivo, tasa de aprobación de CWV, errores de rastreo.
  • Rezagados: clics no relacionados con la marca, conversiones/ingresos orgánicos (GA4), tasa de citas de IA (seo-ai-search).
• Panel gratuito: Looker Studio con el conector nativo de Search Console (tablas de impresiones de sitio + URL) y el conector de GA4. Páginas:
  • Resumen.
  • Tendencia no relacionada con la marca (filtro de expresión regular).
  • Clústeres (agrupación por ruta de URL).
  • Oportunidades (posiciones 4-20).
  • CWV (el conector CrUX, o instantáneas de psi.py).
• Informe mensual: qué cambió, por qué (etiquetado con evidencia), qué hicimos (de SEO-WORKLOG.md), qué sigue.

D. Medir si un cambio SEO funcionó

1. Pre-registra. Antes del cambio, escribe en el registro de trabajo:
   • URL modificadas.
   • URL de control (similares, sin cambios).
   • Métrica (clics/impresiones/CTR/posición para las consultas objetivo).
   • Dirección esperada.
   • Ventana: ≥4 semanas después de la indexación; comprueba la fecha de re-rastreo en URL Inspection.
2. Exporta ventanas iguales antes y después para ambos grupos, luego ejecuta gsc_analyze.py after.csv --compare before.csv para cada grupo.
3. Informa el cambio del tratamiento menos el cambio del control. Con pocas páginas o pocos clics, di "no concluyente". Nunca afirmes causalidad a partir de un único antes/después.

Seguimiento de posiciones

• Gratuito: posición media por consulta en Search Console (ponderada por impresiones, todas las ubicaciones). Bueno para tendencias; no es una vista "dónde estoy ahora".

• De pago: posiciones diarias para una lista fija de palabras clave, por ubicación/dispositivo, con funciones SERP. Justifícalo cuando:

  • las posiciones locales o en varias ciudades importan,
  • el contrato del cliente necesita informes de posiciones, o
  • debes hacer seguimiento de palabras clave que aún no tienen impresiones.

  Opciones: Semrush Position Tracking, Ahrefs Rank Tracker, SE Ranking, o la API SERP de DataForSEO para comprobaciones con script (tools.md).

Comprobaciones

Comprobación	Regla	Fuente
Ventanas de comparación de igual duración, alineadas por día de la semana, excluyendo los últimos 2-3 días	Los datos de GSC tienen un retraso de 2-3 días	google-rules §11 [documento de Google]
Retención de GSC	16 meses	google-rules §11 [documento de Google]
Afirmaciones de "penalización"	solo con una entrada en el informe de acciones manuales	google-rules §4 [documento de Google]
Tráfico de AI Overviews/AI Mode	contabilizado dentro de Rendimiento → Web; sin clics separados	google-rules §10 [documento de Google]
Caída en la tasa de rastreo de Googlebot	coincide con respuestas 5xx/429/lentas	google-rules §1 [documento de Google]
Expectativas de CTR	primero la curva propia del sitio; los valores por defecto son heurísticos	heurístico
Umbral de canibalización	≥2 páginas ≥10% de impresiones, ≥100 impresiones	heurístico

Datos: gratuitos vs de pago

Lo gratuito cubre casi todo aquí. Search Console (+API), Bing Webmaster (+ su informe de rendimiento de IA, si está disponible; google-rules §10), GA4, Looker Studio, registros del servidor, el Panel de estado de búsqueda de Google, Google Trends.

Lo de pago añade (ver ${CLAUDE_PLUGIN_ROOT}/references/tools.md):

• Semrush / Ahrefs.
  • Historial de visibilidad de competidores y movimiento de palabras clave (tus propios datos son mejores en GSC).
  • Sus sensores de volatilidad de algoritmo (Semrush Sensor) para ver si una caída es general en la industria.
  • Justificado para la pregunta "¿es solo a nosotros?" durante una actualización.
  • Táctica de coste: consulta la página gratuita del Sensor y el historial de Organic Research de un solo competidor en lugar de un proyecto completo.
• Rastreadores de posiciones: ver más arriba. Rastrea solo las palabras clave monetarias y limita las ubicaciones/dispositivos a los que importan. La mayoría de las herramientas facturan por palabra clave × ubicación × dispositivo × frecuencia, así que prefiere semanal a diario para conjuntos no volátiles.
• Screaming Frog Log File Analyser (## Screaming Frog). Útil si los registros son enormes y el usuario prefiere una interfaz gráfica. log_analyze.py cubre las preguntas principales de forma gratuita.

Etiqueta los números de tráfico de terceros como [datos del proveedor] / [estimación]. Son modelados, no medidos.

Resultado

1. seo-work/gsc.json y similares, más un breve resumen de hallazgos:
   • Las 10 mejores oportunidades de posición de alcance: consulta, página, clics extra estimados [estimación].
   • Principales correcciones de CTR.
   • Decisiones de canibalización.
2. Diagnóstico de caída: el árbol con ✅/❌ y evidencia por rama, la explicación más probable en lenguaje "consistente con", y próximas acciones dirigidas al skill adecuado.
3. Una especificación de panel de KPIs (fuentes de datos de Looker Studio, campos, filtros) o un borrador de informe mensual.
4. Registro del experimento (pre-registro + resultado).

Errores y mitos

• La posición media está ponderada por impresiones en todas las consultas/ubicaciones. Un nuevo posicionamiento en la página 2 puede bajar la media mientras el tráfico aumenta.
• Las exportaciones de la IU tienen un límite de 1.000 filas y ocultan consultas anonimizadas, por lo que los totales no coincidirán con el gráfico.
• Una caída en una fecha de actualización no es prueba de que la actualización la causara. Descarta primero causas técnicas y de seguimiento.
• Año contra año supera a mes contra mes para negocios estacionales.
• Los clics bajan mientras las impresiones se mantienen suele ser AI Overviews u otra función SERP, no una pérdida de posicionamiento.
• "Orgánico" en GA4 depende del modo de consentimiento y la agrupación de canales, así que comprueba cambios de configuración en la fecha de la caída.
• No optimices el CTR con títulos clickbait. Google puede reescribirlos (google-rules §3).

Registra el trabajo

Añade a SEO-WORKLOG.md (${CLAUDE_PLUGIN_ROOT}/references/worklog.md):

• Exportaciones utilizadas (rangos de fechas).
• Scripts ejecutados.
• Hallazgos con etiquetas de evidencia.
• Veredicto del diagnóstico.
• Experimentos pre-registrados.
• Uso de herramientas de pago.
• La fecha para volver a comprobar (ej. "volver a obtener GSC el 2026-11-21 para la prueba del título").