Communitygithub.com

Heraut SEO

Investigación SEO profunda y de solo lectura de un sitio web y su servidor que responde 'por qué Google no indexa ni envía visitantes a este sitio, y qué hacemos exactamente al respecto'.

¿Qué es Heraut SEO?

Heraut SEO es una habilidad técnica para agentes de IA (como Claude Code) que realiza una auditoría SEO exhaustiva y de solo lectura en un sitio web, diseñada para diagnosticar por qué Google no indexa ni envía tráfico orgánico significativo. Funciona en cuatro pistas paralelas: Google (Search Console y GA4 con inspección de URL en una muestra estratificada), servidor (logs con Googlebot verificado por DNS, velocidad y bloqueos), código y contenido (como Google lo lee), y visión externa (con DataForSEO pagado para SERPs, rankings y backlinks, y Perplexity para investigación profunda). La síntesis final sigue un estilo de consultoría: situación, complicación, pregunta, árbol de causas, plan por fases, KPIs a 30, 60 y 90 días, y decisiones para el propietario. Es útil cuando un sitio no recibe tráfico orgánico, los artículos del blog no se indexan, un programa SEO no produce resultados medibles, antes de gastar más en contenido, o para auditar toda una flota de sitios de la misma manera. Incluye activadores en francés para detectar peticiones como 'enquete SEO', 'pourquoi Google n'indexe pas mon site', etc. La habilidad prioriza la evidencia medible, no escribe cambios en producción, y respeta cuotas de API y límites de servidor.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/koffih/claude-skill-heraut-seo/tree/HEAD

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

¿Qué hace Heraut SEO?

El heraut (heraldo) es quien da a conocer un dominio al mundo. Cuando nadie lo escucha, esta habilidad investiga por qué, con pruebas para cada afirmación, y devuelve un plan que el propietario puede ejecutar.

Surgió de un caso real: un sitio con 58 000 URLs y 1000 artículos generados, un piloto de contenido gastando dinero cada día, cero impresiones en el blog. La respuesta no estaba donde el piloto buscaba (reescribir páginas) sino en la calidad, autoridad y demanda del sitio en su conjunto. El método a continuación está diseñado para encontrar ese tipo de respuesta, en lugar de confirmar la primera hipótesis.

Las reglas

  1. Solo lectura, en todas partes. Sin cambios en producción, sin escritura en base de datos, sin reinicios, nada enviado a Google (sin solicitudes de indexación, sin añadir o eliminar sitemaps). La investigación describe; el plan se aplica después, un cambio decidido a la vez.
  2. Prueba para cada afirmación. Comando, número, fecha, archivo. Marca qué es MEDIDO y qué es SUPUESTO. Una muestra no es un conteo: da n.
  3. Sé amable con el sitio. Una solicitud a la vez, una pausa de al menos 1.5 segundos (politesse.delai_s). Los servidores pequeños fallan bajo las auditorías.
  4. APIs de pago con un límite. budgets.dataforseo_usd y budgets.perplexity_usd son aplicados por los scripts antes de cada llamada; cada costo se registra. Reporta el total gastado.
  5. Sin secretos en ninguna salida. Nombra dónde vive una clave, nunca su valor. Los scripts leen las claves del entorno o de archivos de entorno nombrados en la configuración.

Dónde están las cosas

Scripts en scripts/ (normalmente ~/.claude/skills/heraut-seo/scripts), solo biblioteca estándar de Python, openssl para tokens de Google. Cada script acepta --config <site.json> --dossier <carpeta de investigación> y escribe CSV y JSON allí, además de un resume.json para leer primero.

ScriptPistaQué hace
sitemap.pycódigoárbol completo del sitemap, cada URL con tipo e idioma, honestidad de lastmod, duplicados
gsc.py performancegoogle16 meses por mes y tipo de página, 28 días vs. anterior, consultas, países, secciones
gsc.py sitemapsgooglesitemaps enviados, errores, pendientes, última lectura por Google
gsc.py echantillon / inspecter / analysergoogleInspección de URL estratificada (cuota de 2000/día, reanudable), cobertura por tipo, movimiento desde una ejecución anterior
ga4.pygooglecanales durante un año, Google orgánico antes y ahora, asistentes de IA, proporción similar a robot
pages.pycódigolectura en página de una muestra: idioma, canonical, hreflang, robots, palabras, JSON-LD, enlaces al blog, Googlebot vs. navegador
logs.pyservidorGooglebot real (verificado por DNS) por día, por tipo, desperdicio, tiempos de respuesta, primera visita de URLs seguidas
ttfb.pyservidortiempo hasta el primer byte por tipo, cálido, frío y origen
dataforseo.pyexternoSERPs reales, palabras clave rankeadas, backlinks del sitio y competidores, volúmenes, bilan
perplexity.pyexternoinvestigación profunda fechada y con fuentes (API Agent, effort)

La investigación, paso a paso

0. Marco (10 minutos, con el propietario si es necesario)

  • Escribe la pregunta del propietario con sus palabras y los síntomas con números (impresiones, clics, artículos publicados, dinero gastado).
  • Encuentra lo que ya se sabe: auditorías anteriores, notas, el pipeline de contenido y su base de datos. Trátalos como hipótesis a verificar, no como hechos para copiar.
  • Construye el archivo del sitio a partir de config.example.json: dominio, sitemap, idiomas, tipos de página como expresiones regulares de ruta (la parte más importante: cada recuento es por tipo), secciones a seguir (el blog), propiedad de Search Console, id de GA4, ruta de clave de cuenta de servicio, mercados (códigos de ubicación de DataForSEO), 3 a 6 competidores, 15 a 30 consultas reales que la gente escribiría, presupuestos.
  • Verifica el acceso antes de comenzar: gsc.py sitemaps responde, GA4 responde, los logs son legibles (a menudo solo por root y el grupo adm: pídele al propietario, nunca trabajes alrededor de una negativa).

1. Cuatro pistas en paralelo

Crea la carpeta enquete-AAAA-MM-DD/ junto a los otros archivos de auditoría del sitio, escribe BRIEF.md allí a partir de references/brief.md, luego lanza cuatro investigadores (subagentes) a la vez, cada uno con el brief y su archivo de pista. Cada uno escribe volet-<pista>.md con un resumen de 10 líneas en la parte superior, y sus datos brutos al lado.

PistaArchivoPregunta clave
Googlereferences/track-google.md¿Conoce Google las páginas, las rastrea, las mantiene? ¿Está mejorando o empeorando?
Servidorreferences/track-server.md¿Viene el Googlebot real, qué lee, hay algo que lo ralentiza o bloquea?
Código y contenidoreferences/track-code-content.md¿Qué encuentra Google cuando lee el sitio: cuántas páginas, qué tan delgadas, qué tan enlazadas, qué tan honestas?
Externoreferences/track-outside.md¿Quién gana las búsquedas reales, con qué autoridad, y hay demanda para lo que el sitio escribe?

Ejecuta sitemap.py primero (los demás muestrean a partir de él), luego las pistas. gsc.py inspecter puede tomar horas en una muestra completa: ejecútalo en segundo plano.

2. Síntesis

Lee los cuatro informes, luego construye la respuesta con references/cause-tree.md: enumera las causas vistas en la práctica, la medida que confirma o descarta cada una, y las trampas (una auditoría técnica que sale limpia no significa que el sitio esté bien).

Escribe el informe siguiendo references/report.md: respuesta corta primero, situación, complicación, pregunta, árbol de causas con la evidencia en cada rama, por qué el programa actual no funciona, el plan en fases con un "hecho cuando" para cada paso, KPIs a 30, 60, 90 días, decisiones para el propietario, límites de la investigación, fuentes. Publícalo como una página cuando la sesión pueda (privada por defecto), de lo contrario como un archivo HTML.

3. Entrega

  • Dale al propietario el enlace, el diagnóstico central en cinco líneas, el costo de la investigación, lo que no se pudo medir.
  • Luego las decisiones, una a la vez, cada una con el hecho detrás y una recomendación. Aplica cada paso decidido antes de preguntar el siguiente.
  • Guarda el veredicto y la regla operativa que implica (por ejemplo "sin contenido nuevo hasta que las páginas principales estén indexadas") donde el proyecto guarda su memoria.

Ejecutarlo en otro servidor o sitio

Instala la habilidad en la máquina que tiene el acceso (clave de Search Console, logs), copia config.example.json a la carpeta del sitio, complétalo, ejecuta los pasos 0 a 3. Mantén una carpeta por fecha de investigación para que la siguiente ejecución pueda comparar: gsc.py analyser --avant <old inspection.jsonl> muestra URL por URL lo que entró o salió del índice.

Vuelve a ejecutar la investigación de 60 a 90 días después de que comience el plan. Entre ejecuciones, una inspección rotativa diaria de 50 a 100 URLs es la forma más económica de ver cómo se mueve el índice.

Lo que esta habilidad no hace

No cambia el sitio, escribe contenido, solicita indexación ni compra enlaces. No juzga el producto o el modelo de negocio, solo si la búsqueda puede traer personas al sitio. Las puntuaciones de herramientas SEO (rango, puntuación de spam, tráfico estimado) son modelos, no medidas: dilo cuando las cites.

Skills relacionados