ssheleg/seo-aeo-audit

seo-aeo-audit — auditar la visibilidad en buscadores y motores de respuesta, y entregar un plan

Un objetivo: mirar un sitio real, probar qué está mal con evidencia, y devolver un plan priorizado de cambios que cubra la búsqueda clásica (Google, Yandex, Bing) y los motores de respuesta (AI Overviews / AI Mode, ChatGPT, Perplexity, Claude, Copilot, Gemini, Alice AI).

No es trabajo de esta habilidad: escribir el contenido, construir las páginas, comprar enlaces. Termina en un diagnóstico verificado y un plan ejecutable.

Innegociables

1. Evidencia o silencio. Cada hallazgo lleva: lo que observaste, dónde (URL, archivo:línea, nombre del informe), el valor observado, y la fecha. Nunca reportes un hallazgo que no verificaste en este sitio. "Las buenas prácticas dicen" no es evidencia.
2. Etiqueta el nivel de evidencia de cada recomendación (ver referencias/niveles-evidencia.md): CONFIRMADO (documentado por el motor o reproducido en este sitio) · ESTUDIO (datos publicados de múltiples sitios) · CAMPO (reporte de caso único) · HIPÓTESIS. Nunca permitas que una HIPÓTESIS supere a un bloqueador CONFIRMADO.
3. Diagnostica antes de recetar. Ninguna corrección entra al plan hasta que se localice su causa. "Añade schema" no es un diagnóstico.
4. Rechaza la lista de mitos. Ver "Guardián de mitos" abajo — recomendar esos desperdicia el presupuesto del cliente y es un defecto, no un detalle.
5. Nunca recomiendes tácticas engañosas. El cloaking, las redes de consenso fabricadas, la manipulación de reseñas, el abuso de denuncias a competidores y la suplantación de señales de clic se quedan fuera del plan. Aparecen en esta habilidad solo en referencias/amenazas-y-defensa.md, como cosas a detectar y defender.
6. Indica lo que no pudiste comprobar. Un inicio de sesión de GSC faltante es una brecha en el informe, no una omisión silenciosa.
7. Nunca mezcles lo medido con lo supuesto. Cuando un entregable lleva ambos — un CSV de construcción de enlaces siempre lo hace — una columna fuente los separa y las celdas de volumen de una fila no medida permanecen en blanco, no en cero. Un 0 se lee como "medido, sin demanda"; en blanco se lee como "nadie ha comprobado". La distinción importa más en el trabajo que alguien más ejecuta con un presupuesto.
8. Conoce el punto ciego de cada instrumento y dilo en el resultado. Las reglas 1 y 7 rigen lo que tú escribes; no ven una herramienta que mezcla u omite antes de que tú mires. Dos llegan constantemente. Una obtención estática no puede ver JSON-LD que el CMS inyecta con JavaScript, así que "no se encontró schema" es un hallazgo falso en cualquier sitio con Yoast/RankMath/AIOSEO — scripts/page_audit.py imprime la advertencia junto a cada inventario de schema, y la ausencia solo es reportable tras una verificación de renderizado. GA4 con modelado de modo de consentimiento devuelve comportamiento observado y estimado dentro de un mismo número — ver referencias/medicion.md J1 para las tres condiciones de activación, el indicador visible y el fallback solo observado. La regla se generaliza: antes de que el silencio de un instrumento se convierta en un hallazgo, establece que el instrumento podría haber visto la cosa en absoluto.

Paso 0 — Detectar modo, nunca preguntes dos veces

Inspecciona primero, luego actúa. En orden:

1. Lee docs/seo/ (o la ruta que nombre el usuario). Si existe una auditoría previa, esta ejecución es una re-auditoría: compárala con ella y comienza con lo que cambió.
2. Establece a qué puedes acceder: el sitio en vivo, una URL de staging, robots.txt, sitemap.xml, Search Console / Bing Webmaster / acceso a analíticas, una exportación de rastreo (Screaming Frog, Sitebulb), registros del servidor, cualquier herramienta MCP conectada (Ahrefs, GSC, analíticas, un MCP de rastreador, o el MCP Prowl para datos masivos de competidores y demanda sin un asiento por proveedor). Prueba el acceso, no lo asumas. Un servidor conectado no es uno funcional: los niveles de API limitan los endpoints, y los tokens tienen alcances más estrechos que el panel de control. Prueba la única llamada para la que está cada fuente antes de planificar alrededor de ella, y registra lo que devolvió — "conectado pero devuelve Plan insuficiente" es un hallazgo que la próxima auditoría necesita.
3. Elige el alcance con el usuario solo si la respuesta cambia el trabajo: sitio completo, una plantilla/sección, una pregunta ("¿por qué cayó el tráfico en mayo?"), o una extracción para construcción de enlaces — objetivos, palabras clave y anclajes para un contratista. Ese es un entregable más que un diagnóstico: lee referencias/construccion-enlaces.md cuando sea la solicitud. Funciona con o sin Search Console.
4. Reporta el estado en tres líneas — entradas disponibles, entradas faltantes, alcance — luego comienza. Sugiere exactamente una siguiente acción al final de cada ejecución.

scripts/preflight.py realiza la mitad automatizable del paso 2 en lugar de scripts/preflight.py ejecuta la mitad automatizable de este paso y reporta en qué puerta independiente falló un bloqueo — Search Console, la API de GSC y PageSpeed todos responden 403 por diferentes razones. Lee referencias/preflight.md para exactamente qué prueba y qué te deja a ti (Bing/Yandex, analíticas, registros del servidor, exportaciones de rastreo y cada herramienta MCP). Un preflight verde no es un paso cubierto.

# Plugin de Claude Code: ${CLAUDE_PLUGIN_ROOT} se expande dentro del contenido de la habilidad.
SKILL_DIR="${CLAUDE_PLUGIN_ROOT}/skills/seo-aeo-audit"
# Cualquier otro canal: el directorio base que el cargador nombra cuando carga esta
# habilidad — el directorio donde reside este SKILL.md. Confírmalo antes de confiar en él:
ls "$SKILL_DIR/scripts/preflight.py"

No such file or directory aquí no es una característica faltante ni una razón para proceder en silencio. Significa que los seis instrumentos son inalcanzables, por lo que cada verificación que habrían hecho baja al escalón más bajo de la escalera de evidencia — y el escalón de un hallazgo limita su nivel. Dilo en el estado de tres líneas; una auditoría que silenciosamente se vuelve manual ha cambiado lo que valen sus conclusiones (innegociable #6).

python3 "$SKILL_DIR/scripts/preflight.py" --site sc-domain:example.com --origin https://example.com

Reglas de acceso: solo lectura por defecto. Nunca envíes formularios, solicites indexación, desautorices enlaces o cambies una propiedad activa sin aprobación explícita en esta sesión; esas son acciones hacia afuera.

Paso 1 — Línea base antes que opiniones

Registra, con fechas, para que cada afirmación posterior pueda medirse contra ella:

• clics orgánicos / impresiones / posición promedio por país y dispositivo, 12 meses (GSC + Bing), y la ventana de caída o meseta si la hay;
• recuentos de URL indexadas vs publicadas por plantilla (site: es una prueba rápida, el informe de Páginas de GSC es el número);
• páginas de las 20 principales por ingresos o conversiones y sus posiciones actuales;
• línea base de superficie de IA: ejecuta el conjunto de prompts de marca y categoría desde referencias/aeo-geo.md contra cada motor al que puedas acceder, y registra las respuestas textualmente;
• qué rastreadores de IA realmente obtienen el sitio (registros del servidor; DNS inverso confirmado hacia adelante para filtrar suplantadores) y qué referentes de IA aparecen en las analíticas;
• la línea de tiempo de actualizaciones: alinea cada cambio en la curva con fechas contra referencias/actualizaciones-algoritmo.md antes de formar cualquier hipótesis sobre una causa.

Cuando no hay acceso de primera parte en absoluto, dilo en el estado de tres líneas y recurre a lo que un índice de terceros puede establecer: para qué clasifica el dominio hoy, quÉ tan grande es su perfil de enlaces contra un conjunto competitivo dimensionado, y si sus frases objetivo tienen demanda medible (referencias/prowl-mcp.md). Esa línea base está limitada a ESTUDIO y no puede responder "¿por qué no está indexada esta página?" — pero es suficiente para distinguir un arranque en frío de una disminución, y esos necesitan planes opuestos.

Si el sitio afirma una caída de tráfico, primero separa una falla de informe de una falla de posicionamiento: un informe congelado de GSC fija los clics en una fecha, mientras que un impacto real sigue produciendo nuevos puntos descendentes. Cruza las sesiones de GA4, los registros del servidor y un rastreador de posiciones independiente antes de diagnosticar una causa algorítmica.

Paso 2 — Las diez pistas

Ejecuta cada pista que esté dentro del alcance. Cada una tiene su propio archivo de referencia con las verificaciones concretas, los errores actuales de 2026 y la evidencia a capturar.

#	Pista	Responde	Referencia
A	Acceso y economía de indexación	¿Pueden los bots obtener, renderizar y costear esto? ¿Dónde se quema el presupuesto de rastreo?	verificaciones-tecnicas.md
B	Canonicalización y duplicación	¿Qué URL es canónica, y está de acuerdo el motor? Incluyendo hreflang.	verificaciones-tecnicas.md
C	Arquitectura y equidad de enlaces	¿Reciben las páginas de dinero autoridad, profundidad y frecuencia de rastreo?	arquitectura-y-equidad.md
D	Intención y ajuste SERP	¿Coincide cada página con la SERP, y se canibalizan las páginas?	intencion-y-contenido.md + verificaciones-onpage.md
E	Valor del contenido	¿Una razón para clasificar que la IA no pueda replicar?	intencion-y-contenido.md + modelo-de-clasificacion.md
F	Extraibilidad y AEO/GEO	¿Puede un motor de respuesta recuperarlo, leerlo y citarlo?	aeo-geo.md
G	Entidad y consenso de marca	¿Conocen los modelos la marca, de manera consistente, y la nombran?	entidad-y-marca.md
H	Experiencia, conversión y atribución	¿Tarea completada aquí o devuelta? ¿Convertido y medido?	senales-experiencia.md + demanda-y-conversion.md
I	Riesgo y amenazas	Penalizaciones, secuestros, inyecciones, eliminaciones.	amenazas-y-defensa.md
J	Medición	¿Podrá alguien saber si el plan funcionó?	medicion.md

Discover no es una de las diez pistas, y no es parte de la pista A. Tiene su propio pase de clasificación, su propia puerta (dos metaetiquetas, sin las cuales no se renderiza ninguna tarjeta en absoluto) y su propia curva de actualización, por lo que un sitio donde Discover es una fuente de tráfico material necesita referencias/discover.md ejecutada como undécimo pase — y un sitio donde no lo es puede omitirlo por completo. Revisa el informe de Discover de GSC antes de decidir: la referencia se envió accesible solo desde la lista al final de este archivo, lo que significaba que un agente que trabajaba las pistas en orden nunca la abrió.

Antes de cualquier diagnóstico de disminución, ejecuta el protocolo de alineación de fechas y respuesta a actualizaciones en referencias/actualizaciones-algoritmo.md — "nos afectó una actualización central" no es un hallazgo, y la mitad de las interrupciones documentadas de GSC coincidieron con lanzamientos.

Cada pista tiene dos mitades: el trabajo diagnóstico (qué está mal y por qué) y un barrido mecánico para completitud — verificaciones-tecnicas.md §A3 para las pistas A/B y verificaciones-onpage.md para D/E. Ejecuta el diagnóstico primero; el barrido después atrapa las fallas aburridas, y solo los elementos del barrido con un impacto observable se promueven a la tabla de hallazgos.

El orden importa. Un bloqueador de la pista A (sitio no obtenible, noindex en la fuente pre-renderizada, acción manual) hace que todos los demás hallazgos sean irrelevantes — una acción manual es un multiplicador binario: nada de lo que mejores cuenta hasta que se levante. Trabaja A → B → C antes de gastar tiempo en F/G.

Escalera de evidencia — el enrutamiento completo reside en referencias/herramientas.md; está ordenado por fuerza de evidencia, no por conveniencia: registros del servidor → Search Console / Bing / Yandex → rastreo completo → datos de rendimiento de campo → índices de terceros → obtención manual y DevTools. Usa el escalón más alto al que realmente puedas llegar para cada verificación, y indica en el informe en qué escalón se basa un hallazgo. Una auditoría solo pública sin acceso a la propiedad es trabajo válido, pero sus hallazgos de indexación y consultas son inferencias, no observaciones, y se clasifican en consecuencia.

Los seis scripts incluidos — preflight.py, gsc_pull.py, page_audit.py, url_inspection.py, sitemap_audit.py, psi_pull.py — recopilan la mitad mecánica de cada pista. Lee referencias/scripts.md para invocación, banderas, cuotas y los límites por script.

Cuatro trampas que deciden si un hallazgo es real:

• El inventario de schema de page_audit.py lee solo HTML renderizado por el servidor. Donde un CMS inyecta JSON-LD con JavaScript, un inventario vacío no es evidencia de marcado ausente (innegociable #8).
• --format json emite un array, un objeto por página, incluso para una sola URL: indexa data[0].
• Una respuesta truncada por --max-bytes descarta cada hallazgo basado en recuentos en lugar de publicar un fragmento como medición.
• Cada hallazgo emitido lleva un nivel de evidencia además de una severidad, y solo el nivel entra en la fórmula de triaje. La severidad es qué tan ruidoso es un hallazgo; el nivel es lo que lo respalda. url_inspection.py pregunta al índice en lugar de inferir de una obtención, que es la única forma en que un hallazgo alcanza CONFIRMADO — con un límite de 2000/día y 600/minuto por propiedad, así que muestra una URL por plantilla más las páginas sobre las que realmente trata un hallazgo.

Paso 3 — Triaje

Puntúa cada hallazgo, luego ordena. No presentes una lista sin clasificar.

prioridad = (impacto × confianza) / esfuerzo

• impacto 1–5: páginas de ingresos bloqueadas = 5; una fuga en toda la plantilla = 4; una sola página informativa = 1. Estima en términos de tráfico o ingresos donde la línea base lo permita.
• confianza: CONFIRMADO 1.0 · ESTUDIO 0.7 · CAMPO 0.4 · HIPÓTESIS 0.2.
• esfuerzo 1–5 en días de ingeniería, contando el proceso de lanzamiento, no solo la edición.

Agrupa la salida en cuatro cubos, en este orden:

1. Bloqueadores — indexación, penalizaciones, secuestros, páginas de ingresos inalcanzables.
2. Fugas — presupuesto de rastreo, equidad, canibalización, desperdicio de presupuesto de lectura.
3. Ganancias — ajuste de intención, ganancia de información, extraibilidad, consenso de entidad.
4. Experimentos — cualquier cosa por debajo de CONFIRMADO que merezca una prueba dividida en lugar de un despliegue. Diseñarlos según referencias/experimentos.md; nunca implementes una HIPÓTESIS.