Communitygithub.com

geo-audit

Realiza una auditoría externa de visibilidad en buscadores de IA (GEO / AEO) de un sitio web únicamente con su URL, para uno o varios países o idiomas, y genera un informe accionable.

¿Qué es geo-audit?

Este skill de agente de IA realiza una auditoría completa de optimización para motores de búsqueda generativos (GEO/AEO) de un sitio web, analizando exclusivamente desde fuera, sin acceso al código fuente. Evalúa la visibilidad del sitio en respuestas de IA (ChatGPT, Perplexity, Google AI Overviews, Gemini, Claude, Copilot, etc.) para uno o varios mercados objetivo, siguiendo un proceso estructurado: verifica la capacidad de rastreo de los rastreadores de IA (robots.txt, bloqueo de UA, sitemaps), analiza la legibilidad del contenido renderizado frente al HTML sin procesar, audita la estructura de la página (títulos, datos estructurados, autoría), evalúa la cobertura de preguntas típicas de los usuarios en cada mercado, y comprueba la presencia fuera del sitio (menciones en plataformas clave). Todo el análisis se basa en un conjunto de evidencias (E1–E16) con niveles de prioridad (P0, P1, P2) y referencias a mercados específicos. El informe resultante sigue una plantilla fija y está diseñado para que el cliente pueda actuar directamente sobre las recomendaciones, priorizando: ser rastreado > ser indexado > ser absorbido por la IA > ser mencionado externamente. El skill es compatible con herramientas de agente como Claude Code, Codex y Cursor, y se instala mediante un script bash.

Compatible con✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ClydeKuo/geo-skill/tree/HEAD/geo-audit

Preguntar en tu IA favorita

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

Documentación

Auditoría GEO del sitio web

Resumen

A partir de una sola URL, examina externamente la visibilidad del sitio en búsquedas de IA para uno o varios mercados de país/idioma, y genera un informe que el cliente puede aplicar directamente.

Principio fundamental: Asignar el esfuerzo según la solidez de la evidencia. Las mayores palancas, en orden descendente, son: ser rastreable → ser indexable → ser absorbible → ser mencionado externamente, y no recurrir a trucos de redacción. Cada recomendación debe citar el número de evidencia y su intensidad de references/evidence.md.

Este skill sigue el formato abierto Agent Skills y puede usarse en herramientas como Claude Code, Codex, Cursor, etc., instalándose con bash <skill>/install.sh en el directorio de skills de cada herramienta. Todas las rutas a continuación son relativas al directorio donde se encuentra este SKILL.md (denotado como <skill>).

Cuándo no usarlo

  • Auditoría SEO tradicional completa (backlinks, rankings de palabras clave): solo mencionar si es relevante para GEO.
  • Probar la visibilidad llamando a la API de IA: no se hace, en el informe solo se indican métodos manuales.
  • Modificar directamente el sitio web del cliente: solo se emite un informe, como máximo se incluyen 1–2 párrafos de ejemplo reescritos.

Capacidades de entorno requeridas

CapacidadUsoQué hacer si no está disponible
shell + Python 3Ejecutar los scripts en <skill>/scripts/ (solo biblioteca estándar)No se puede auditar, informar al usuario
Acceso a redLos scripts obtienen el sitio del clienteLa ejecución de prueba en el paso 1 lo detectará, detenerse y pedir al usuario que active la conexión
Herramienta de búsqueda web (WebSearch en Claude Code)Menciones externasEn la sección de externos escribir "No se pudo detectar (el entorno actual no tiene búsqueda web)", no omitir esa sección
Herramienta de captura web (WebFetch en Claude Code)Leer páginas externasUsar curl como alternativa
Herramienta de escritura de archivosEscribir el informeUsar heredoc de shell
Chrome / Chromium (opcional)Comparación de renderizadoEl script marcará automáticamente "No detectado"

Archivos

ArchivoUso
scripts/crawl_check.pyVerificar robots.txt para rastreadores de IA (RFC 9309), bloqueo de UA, sitemap, canonical, noindex, HTTPS, llms.txt, ICP, hreflang (fuentes: HTML / cabecera HTTP Link / sitemap y verificación bidireccional)
scripts/render_diff.pyComparación de proporción de texto sin ejecutar JS frente al renderizado
scripts/page_audit.pyJerarquía de títulos, unidades de evidencia, datos estructurados, autor y fecha de actualización, canonical, hreflang; --save-html guarda el HTML original
references/checklist.mdLista de verificación general y reglas P0/P1/P2
references/markets/<código>.mdPerfiles de mercado: cn us jp kr de fr es; mercados no perfilados usar _generic.md
references/evidence.mdBase de evidencias E1–E16
references/ai-crawlers.mdUsos de rastreadores, motores sin UA público, limitaciones de UA falsificados
references/report-template.mdEstructura del informe y reglas de redacción (obligatorio)

Parámetros comunes de todos los scripts: python3 <skill>/scripts/<script>.py <url> [más url…] [--proxy URL] [--timeout segundos] [--lang etiqueta_idioma] [--out archivo.json], la salida es JSON en stdout, el código de salida siempre es 0. crawl_check.py acepta solo una url, y además tiene --markets cn,us,jp.

Proceso de auditoría

Primero, crear el directorio de salida geo-report-<nombre_host>-<AAAAMMDD>/ (en el directorio de trabajo actual; <nombre_host> es el nombre de host de la URL final de la página de inicio, ej. www.example.com), y todos los datos originales se guardan allí. El archivo del informe geo-report-<nombre_host>-<AAAAMMDD>.md se coloca en el mismo nivel.

  1. Recopilar contexto

    • La URL es obligatoria. Preguntar una vez por la marca y el negocio principal; si el usuario no responde, inferir desde la página de inicio y escribir en la sección "Alcance de la auditoría y supuestos" del informe.
    • Idioma del informe = el idioma que el usuario usó para iniciar la auditoría; si el usuario lo especifica, prevalece.
    • Mercados objetivo (lista de códigos de mercado): Prioridad a los mencionados por el usuario. Si no se especifica, ejecutar primero el paso 2, luego inferir desde hreflang y el selector de idioma en crawl.json, y pedir confirmación al usuario. Una auditoría tiene como máximo 3 mercados por defecto; si no hay respuesta, tomar "el mercado correspondiente al idioma predeterminado del sitio + hasta 2 mercados perfilados del hreflang (en orden: cn, us, jp, kr, de, fr, es)", el resto se lista como "Mercados no auditados esta vez". Si el usuario lo pide explícitamente, se hace, pero el presupuesto de páginas y tiempo no aumenta.
    • Los mercados se dividen por país o región. zh-TW / zh-HK, en-GB y otros inglés no estadounidense, de-AT / de-CH, fr-BE / fr-CA, etc. usan _generic. Ver la sección 1 de markets/_generic.md para las relaciones de referencia.
    • Confirmar el país de salida de red de la máquina de auditoría (ej. curl -s https://ipinfo.io/country).
  2. Verificación de rastreabilidad (también es la prueba de conexión)

    python3 <skill>/scripts/crawl_check.py <url> --markets <lista_códigos> --lang <etiqueta_idioma_del_primer_mercado> --out <directorio_salida>/crawl.json
    
    • Si tanto homepage como robots son errores de red, el entorno actual no tiene conexión: detenerse, informar al usuario que necesita activar la conexión (cómo hacerlo en Codex está en el README), no emitir un informe vacío.
    • Leer ai_crawlers (prestar atención a los que tengan relevant: true), ua_blocking, homepage, robots.value.source, meta_robots, x_robots_tag, canonical, https, sitemap, icp, hreflang, other_domains. Las reglas de decisión están en references/checklist.md; rastreadores locales, ver la sección 4 de cada perfil de mercado.
    • Si sitemap.value.truncated es true, count es solo la cantidad leída, no el total del sitio.
    • Versiones de idioma en otros hosts: Las versiones en otros dominios/subdominios declarados en hreflang.declared que pertenezcan a los mercados objetivo seleccionados, se incluyen en esta auditoría, ejecutando crawl_check.py nuevamente en su página de inicio, con salida crawl-<nombre_host>.json. Los otros dominios no declarados en hreflang (other_domains) solo se mencionan en el informe, recomendando auditoría separada.
  3. Seleccionar páginas clave: Al menos 2 páginas por mercado objetivo (versión en el idioma de ese mercado), máximo 20 en total. Prioridad: página de inicio, páginas de producto/servicio principales, página de comparativa, página de precios, página "Acerca de", página de contenido. La fuente principal es el sitemap y la navegación.

  4. Comparación de renderizado: De 1 a 5 URL a la vez, timeout 30 segundos, usando el idioma del mercado correspondiente:

    python3 <skill>/scripts/render_diff.py <url1> <url2> --timeout 30 --lang ja-JP --out <directorio_salida>/render-1.json
    
  5. Auditoría de página individual y lectura del contenido:

    python3 <skill>/scripts/page_audit.py <url1> <url2> … --lang ja-JP --save-html <directorio_salida>/html --out <directorio_salida>/pages-jp.json
    
    • El script solo cuenta y excluye enlaces y títulos dentro de <nav> y <header>, <footer> a nivel de página.
    • Para leer el contenido, usar los archivos guardados con --save-html, no escribir otro script de captura, y no colocar archivos intermedios fuera del directorio de salida.
    • Contenido a evaluar: ¿hay frases de definición, comparativas, pasos, datos verificables? ¿Cada párrafo trata solo un tema? ¿Hay contenido oculto (FAQ plegado solo en datos de JS, animaciones numéricas que en HTML muestran 0)? ¿La versión local es traducción humana o tiene rastros de traducción automática? Puntos clave de localización en la sección 7 del perfil de mercado.
  6. Evaluación de indexabilidad: Para cada mercado objetivo, generar de 10 a 20 preguntas en el idioma local, siguiendo los patrones de la sección 6 del perfil de mercado, cubriendo: conocimiento / comparación / decisión / postventa. Evaluar una por una si hay una página en la versión de idioma de ese mercado que responda directamente, y rellenar la "tabla de cobertura de preguntas" del informe (texto original en idioma local + traducción al idioma del informe).

  7. Menciones externas: Usar la herramienta de búsqueda web, buscar plataforma por plataforma según la sección 5 del perfil de mercado, y registrar: presente / ausente / no detectado, con enlaces representativos. No buscar en plataformas que requieran inicio de sesión.

  8. Guardar selección de auditoría: Escribir en <directorio_salida>/audit.json:

    {"target": "", "markets": ["jp", "us"], "report_language": "ja", "brand": "", "business": "",
     "pages": {"jp": ["…"], "us": ["…"]}, "questions": {"jp": ["…"], "us": ["…"]},
     "offsite_queries": {"jp": ["…"], "us": ["…"]}, "extra_hosts": ["…"],
     "proxy_country": {"jp": "JP"}, "date": "YYYY-MM-DD"}
    

    proxy_country solo registra qué país de salida se usó (si no se usó, escribir {}), no la dirección del proxy.

  9. Escribir el informe: Según la estructura de references/report-template.md, escribir en el idioma del informe. Las secciones tienen números fijos; si no aplica, escribir "No aplica".

Modo de revisión

Cuando el usuario proporciona un directorio geo-report-<nombre_host>-<fecha>/ anterior: leer su audit.json, usar los mismos mercados, páginas clave, preguntas y términos de búsqueda externa, y re-ejecutar los pasos 2–7, completando la sección "Comparativa antes/después de las correcciones" del informe.

Las versiones antiguas de audit.json usan "market": "cn" | "global" | "both", que se convierten según estas reglas: "cn" → cn; "global" → us; "both" → cn,us. En versiones antiguas, la clave questions con "global" corresponde a "us".

Límites de tasa y presupuesto de tiempo

  • Los scripts ya incluyen retroceso: ante un 429 o un 503 con Retry-After, esperan y reintentan una vez, y automáticamente ralentizan las solicitudes posteriores. Si en los resultados aparece rate_limited: true, o varias páginas consecutivas devuelven 429:
    • Reducir las páginas clave restantes a 2 por mercado;
    • En la sección "Alcance de la auditoría y supuestos" del informe, escribir "El sitio está limitado, el número de páginas muestreadas se ha reducido".
  • Cuando hay limitación, un script puede tardar varios minutos (esperando Retry-After). Al ejecutar scripts, establecer el timeout del shell en 10 minutos, o ejecutar en segundo plano, no interrumpir por timeout y perder la salida JSON.
  • Se recomienda que la auditoría completa se complete en 45 minutos. Si se supera, detener nuevas capturas, escribir el informe con los datos existentes, e indicar las comprobaciones no realizadas.
  • Prohibido rotar proxies o IPs de salida para evitar límites de tasa, ni cambiar la UA ni acelerar los reintentos.
  • Solo hay dos casos en los que se puede usar --proxy para especificar la salida de un país: probar la accesibilidad desde ese mercado objetivo; el sitio devuelve contenido diferente según la región de acceso. Registrar qué país de salida se usó en el informe, solo el país, no la dirección del proxy (la dirección del proxy es información interna del auditor; el informe y audit.json se entregan al cliente).

Puntos clave de interpretación

Resultado del scriptSignificadoCómo escribirlo en el informe
En ai_crawlers, los de tipo búsqueda o activados por usuario son failrobots.txt los bloquea explícitamenteP0
En ai_crawlers, es unknownNo se pudo leer robots.txtEscribir "No se pudo detectar" y el motivo
En ai_crawlers, los de tipo entrenamiento son warnBloquea rastreadores de entrenamientoSolo explicar pros y contras
ua_blocking es suspectUA de navegador normal, UA de IA falsificado es bloqueadoP1, "Sospechoso", pedir al cliente que verifique CDN/WAF o logs del servidor
ua_blocking es warn / unknownTodos bloqueados / limitados o fallo en la solicitudIndicar que la auditoría está limitada
homepage es unknownLa máquina de auditoría fue desafiada por WAFNo significa "sitio no disponible", verificar desde otra red
render_diff tiene ratio < 0.5El rastreador de IA apenas ve contenidoP0, listar js_only_headings
En hreflang.alternates, es fail / warnLa versión de idioma no se abre / no es bidireccionalP1 / P2
Cualquier elemento es unknownNo se pudo detectarEscribir "No se pudo detectar" y el motivo, no evaluar
llms_txtSolo registrar si existe o noIncluir en "No se recomienda invertir"
raw_words / rendered_wordsCaracteres CJK cuentan como 1 cada uno, otros idiomas cuentan por palabraEl recuento de palabras en diferentes idiomas no es directamente comparable

Líneas rojas

  • Cada problema debe tener evidencia; cada recomendación debe incluir el número de evidencia y su intensidad. Si el mercado objetivo no es us, añadir "(inferido)" a menos que la sección 8 del perfil de mercado indique lo contrario. Para mercados no perfilados, indicar "Este mercado no está perfilado, la evidencia es débil".
  • Si no se pudo capturar contenido, escribir "No se pudo detectar", no evaluar de memoria.
  • No recomendar: inventar datos, falsificar reseñas, comprar reseñas, ocultar instrucciones a la IA, menospreciar competidores, ni usar traducción automática para generar versiones multilingüe en masa (E13).
  • No considerar llms.txt, FAQ, Schema, tono de autoridad como recomendaciones principales (E10, E9, E7).
  • No prometer mejoras en tráfico o rankings (E15).
  • El idioma del informe debe coincidir con el idioma en que el usuario hizo la pregunta (a menos que el usuario especifique otro).

Errores comunes

  • Considerar suspect como bloqueo confirmado: Solo el bloqueo explícito en robots.txt es P0.
  • Usar rankings de Google para inferir visibilidad en IA: La superposición es baja (E13), y cada mercado y motor deben verse por separado.
  • Generar preguntas en el idioma del informe: Las preguntas deben redactarse en el idioma local del mercado objetivo y según el uso de los usuarios locales.
  • Conclusiones solo basadas en recuentos de scripts: Que numbers sea alto no significa que los datos sean verificables; external_links puede incluir enlaces de pie de página escritos con <div>, hay que leer el contenido.
  • Considerar el count del sitemap como el número total de páginas: Cuando truncated es true, hay que indicarlo.
  • Insistir cuando hay limitación: Seguir la sección "Límites de tasa y presupuesto de tiempo", reducir el número de páginas y no escribir bucles propios esperando mucho tiempo.
  • Omitir versiones de idioma en otros hosts: Las versiones de mercados objetivo declaradas en hreflang en otros dominios deben incluirse en la auditoría.

Skills relacionados