¿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
- 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.
- 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.
- 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. - APIs de pago con un límite.
budgets.dataforseo_usdybudgets.perplexity_usdson aplicados por los scripts antes de cada llamada; cada costo se registra. Reporta el total gastado. - 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.
| Script | Pista | Qué hace |
|---|---|---|
sitemap.py | código | árbol completo del sitemap, cada URL con tipo e idioma, honestidad de lastmod, duplicados |
gsc.py performance | 16 meses por mes y tipo de página, 28 días vs. anterior, consultas, países, secciones | |
gsc.py sitemaps | sitemaps enviados, errores, pendientes, última lectura por Google | |
gsc.py echantillon / inspecter / analyser | Inspección de URL estratificada (cuota de 2000/día, reanudable), cobertura por tipo, movimiento desde una ejecución anterior | |
ga4.py | canales durante un año, Google orgánico antes y ahora, asistentes de IA, proporción similar a robot | |
pages.py | código | lectura en página de una muestra: idioma, canonical, hreflang, robots, palabras, JSON-LD, enlaces al blog, Googlebot vs. navegador |
logs.py | servidor | Googlebot real (verificado por DNS) por día, por tipo, desperdicio, tiempos de respuesta, primera visita de URLs seguidas |
ttfb.py | servidor | tiempo hasta el primer byte por tipo, cálido, frío y origen |
dataforseo.py | externo | SERPs reales, palabras clave rankeadas, backlinks del sitio y competidores, volúmenes, bilan |
perplexity.py | externo | investigació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 sitemapsresponde, GA4 responde, los logs son legibles (a menudo solo por root y el grupoadm: 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.
| Pista | Archivo | Pregunta clave |
|---|---|---|
| references/track-google.md | ¿Conoce Google las páginas, las rastrea, las mantiene? ¿Está mejorando o empeorando? | |
| Servidor | references/track-server.md | ¿Viene el Googlebot real, qué lee, hay algo que lo ralentiza o bloquea? |
| Código y contenido | references/track-code-content.md | ¿Qué encuentra Google cuando lee el sitio: cuántas páginas, qué tan delgadas, qué tan enlazadas, qué tan honestas? |
| Externo | references/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.