seo-playbook

SEO Playbook

Esta habilidad convierte el SEO en un flujo de trabajo de ingeniería repetible: encontrar consultas que el sitio puede ganar realmente, dar a cada página un trabajo claro, poner las palabras adecuadas en los elementos HTML correctos, asegurarse de que Google pueda rastrear, renderizar e indexar el resultado, conseguir enlaces, y luego medir e iterar.

Destila lo que funcionó (y lo que se rompió silenciosamente) mientras se llevaba un sitio joven de herramientas en Next.js desde cero a primeras posiciones en consultas de cola larga. Las lecciones se generalizan a cualquier stack.

La mentalidad, en cinco frases

1. Los rankings siguen a la capacidad de ganar, no a los deseos. Un dominio joven no alcanzará el top 5 para un término cabeza como "generador de códigos QR" este año; puede posicionarse en semanas para "generador de códigos QR gratuito sin registro" o "enlace de deseo de cumpleaños con nombre". Apunta primero a la cola larga y deja que la autoridad temática eleve el término cabeza más tarde.
2. Una página, una intención de búsqueda, una palabra clave principal. Dos páginas apuntando a la misma consulta dividen las señales (canibalización); una página apuntando a dos intenciones no sirve a ninguna.
3. Google clasifica el HTML que recibe, no la aplicación que ve el usuario. Si el contenido, el H1, las respuestas de FAQ o los enlaces solo aparecen después de que JavaScript se ejecute, asume que no existen. Verifica la respuesta cruda del servidor cada vez.
4. Los errores de indexabilidad superan a la redacción. Un soft 404, una canónica fuera de lugar o un noindex heredado de un layout pueden borrar meses de trabajo de contenido sin ningún error. Verifica los códigos de estado, las canónicas y los robots en cada tipo de página que toques.
5. Mide con Search Console, no con intuición. Las impresiones en la posición 8–20 son las victorias más baratas; la posición 50+ significa un problema de autoridad o intención que más ajustes en la página no solucionarán.

Establece las expectativas del usuario de manera honesta: las primeras impresiones para páginas de cola larga suelen aparecer en 2–6 semanas; los términos cabeza toman meses y backlinks. El SEO "rápido" significa elegir peleas que el sitio pueda ganar.

Elige primero la profundidad

La mayoría de las solicitudes de SEO son pequeñas. Elige el modo antes de hacer nada, porque el flujo de trabajo completo cuesta varias veces más tiempo y tokens de los que necesita un cambio pequeño.

Modo rápido es para ediciones en una o dos páginas donde la palabra clave es conocida u obvia: renombrar una página, escribir una meta descripción, añadir FAQs, corregir un problema marcado, o añadir una página a un proyecto que ya tiene un patrón SEO para copiar. En modo rápido:

• No leas los archivos de referencia ni investigues el SERP en vivo, a menos que una verificación siguiente falle o que realmente no puedas decidir.
• Sigue el patrón SEO existente del proyecto: su helper de metadatos, configuración de contenido y componentes de esquema.
• Haz el cambio, luego ejecuta la lista de verificación rápida a continuación sobre el resultado. Si hay HTML construido o servido, ejecuta scripts/seo_check.py una vez sobre él.
• Informa en pocas líneas. Menciona cualquier cosa más grande que hayas notado como una línea "También vale la pena hacerlo", sin investigarlo.

Lista de verificación rápida (solo la página bajo cambio):

1. El título es único, comienza con la palabra clave, ≤ 60 caracteres. La descripción tiene 120–160 caracteres y solo hace afirmaciones verdaderas.
2. Exactamente un H1, y la copia principal, el H1 y las respuestas de FAQ están en el HTML del servidor (no solo en cliente, no con opacity:0, no desmontados).
3. La página establece su propia canónica, es indexable y está en el sitemap. Las páginas ocultas usan noindex y no están deshabilitadas en robots.txt.
4. 3–5 enlaces internos salientes, y al menos un enlace entrante.
5. Los datos estructurados coinciden con el contenido visible, sin calificaciones que no sean propias del sitio.

Modo completo es el flujo de trabajo siguiente. Úsalo para:

• un nuevo sitio, conjunto de páginas o clúster
• elegir palabras clave cuando el objetivo correcto no está claro
• diagnosticar "por qué no está posicionando" o "el tráfico está plano"
• una auditoría previa al lanzamiento o de todo el sitio
• un plan off-page

Una comprobación rápida puede revelar un problema en todo el sitio, como una canónica heredada, un patrón de soft-404 o calificaciones inventadas. No expandas el trabajo silenciosamente: termina el cambio solicitado, pon el problema al principio de tu informe con una línea sobre por qué importa, y ofrece el pase completo. El usuario decide si gastar en ello. La excepción es cuando el cambio solicitado no puede funcionar sin la corrección, por ejemplo, cuando la página que estás editando no tiene un H1 renderizado en el servidor. En ese caso, corrige el mínimo necesario y dilo.

Flujo de trabajo (modo completo)

Ejecuta las fases en orden para un nuevo sitio o conjunto de páginas. Para un cambio en una sola página, haz al menos las fases 3, 4 y 6. Lee el archivo de referencia vinculado cuando llegues a una fase; cada uno contiene la lista de verificación detallada y las plantillas.

Escala el trabajo a la solicitud. Una revisión de página es una revisión de página; un mapa de palabras clave es un mapa de palabras clave. Haz el trabajo solicitado a fondo y coloca las oportunidades adyacentes (palabras clave, ideas off-page) en una lista corta "También vale la pena hacerlo" en lugar de producir planes adicionales completos que nadie pidió. Los entregables adicionales diluyen el que el usuario necesita y cuestan tiempo.

Verifica antes de afirmar. Comprueba los hechos que puedas comprobar (el SERP en vivo, si el nombre de la marca ya está tomado, qué contiene realmente una página, qué hace realmente una característica). Cuando no puedas comprobar algo — una página que solo conoces por URL, un sitio que no carga, una característica que no has visto — di que es una suposición e indícale al usuario qué confirmar. Las suposiciones seguras sobre el sitio de alguien son la forma más común en que los consejos SEO salen mal.

Los scripts son para ti. Ejecuta scripts/*.py tú mismo. En las instrucciones escritas para el usuario, describe la comprobación en términos simples o da un comando que puedan ejecutar sin esta habilidad (curl, pasos de Search Console). Haz referencia a las rutas de los scripts de la habilidad solo cuando sepas que el usuario tiene la habilidad instalada.

Fase 1 — Reconocimiento (antes de cambiar nada)

• Identifica el stack y cómo se renderizan las páginas (SSR, SSG, SPA, híbrido). Para trampas de frameworks, lee la sección relevante de references/technical-seo.md (Next.js App Router tiene su propia sección).
• Inventaría lo que existe: cómo se establecen los metadatos, dónde vive la copia de la página, generación de sitemap y robots, componentes de datos estructurados, analíticas. Reutiliza patrones existentes en lugar de añadir otros paralelos.
• Obtén una página representativa de cada tipo como Googlebot y registra la línea base: python3 <skill-dir>/scripts/seo_check.py <url> [<url> ...] Reporta estado, longitudes de título/descripción, canónica, robots meta y X-Robots-Tag, recuento de H1, recuento de palabras visibles, tipos de JSON-LD, imagen OG y banderas rojas como un elemento principal de "Cargando…".
• Si los datos de Search Console están disponibles (una exportación, un helper de API, o la habilidad seo-google si está instalada), extrae 90 días de filas de consulta+página y ejecuta scripts/gsc_opportunities.py (ver Fase 6). Las impresiones existentes te dicen lo que Google ya asocia con el sitio.
• Busca documentos SEO del proyecto o notas de memoria de auditorías anteriores y constrúyelas.

Fase 2 — Investigación de palabras clave y mapa de palabras clave

Lee references/keyword-research.md. En resumen:

1. Siembra desde el producto: qué hace la página, quién la usa, las palabras que los usuarios escriben cuando quieren exactamente eso.
2. Expande con señales gratuitas: autocompletado de Google y "La gente también pregunta", búsquedas relacionadas, títulos de competidores, consultas de GSC, frases de Reddit/Quora. Usa APIs de pago solo si el proyecto las tiene (por ejemplo, las habilidades seo-dataforseo o seo-ahrefs, si están instaladas).
3. Clasifica la intención (hacer / saber / ir / comprar) y mira el SERP en vivo para cada candidato. Si la primera página son todas grandes marcas o un tipo de página diferente (por ejemplo, listicles cuando tienes una herramienta), la palabra clave aún no es ganable para esta página.
4. Puntúa la capacidad de ganar: competidores débiles (páginas indie delgadas, foros, repositorios de GitHub, sitios *.vercel.app) en la primera página es la señal más fuerte.
5. Verifica el nombre de la marca: búscalo desnudo, más npm/PyPI/GitHub/app stores donde sea relevante. Si está tomado, recomienda usar la forma de dominio ("Marca.app") de manera consistente.
6. Produce un mapa de palabras clave: una fila por URL con palabra clave principal, 3–8 términos secundarios/cola larga, intención, y dónde va cada término (título, H1, H2, introducción, FAQ). Ninguna palabra clave principal aparece en dos filas, y cada fila en cada tabla tiene una intención.

Los volúmenes sin una herramienta de pago son niveles direccionales (muy alto / alto / medio / bajo). Dilo en tu salida en lugar de inventar números.

Fase 3 — Implementación en página

Lee references/on-page.md para la lista de verificación completa y el modelo de contenido de la página. Los esenciales para cada página indexable:

• Título: único, palabra clave principal primero, idealmente ≤ 60 caracteres incluyendo cualquier sufijo de marca, y escrito para ganar el clic.
• Meta descripción: única, 120–160 caracteres, indica lo que el usuario obtiene y el diferenciador ("gratuito, sin registro, se ejecuta en tu navegador") solo cuando es verdadero.
• Exactamente un H1 en el HTML del servidor, que coincida con la intención principal de la página (una variante cercana del título, no una copia).
• Cuerpo: responde la consulta en el primer párrafo, luego añade profundidad que una página de la competencia no tenga: pasos prácticos, ejemplos trabajados, problemas comunes con soluciones, limitaciones, FAQs. Cada sección existe porque un buscador la necesita, no para alcanzar un recuento de palabras.
• FAQs visibles en el HTML (no solo en acordeones colapsados, desmontados y no solo en JSON-LD), redactadas como consultas reales.
• Enlaces internos: 3–5 enlaces contextuales a páginas relacionadas y al menos un enlace hacia la página desde un centro o artículo relevante. Sin páginas huérfanas.
• Datos estructurados que coincidan con el contenido visible: ver references/structured-data.md para qué tipos aún generan resultados enriquecidos.
• Confianza: autor u organización real, afirmaciones precisas, fecha de última revisión que cambia cuando el contenido cambia, fuentes para números. Nunca publiques reseñas o testimonios de relleno — Google los trata como tergiversación.

Almacena el contenido SEO de la página como datos (un objeto de configuración tipado o campos de CMS) en lugar de dispersar cadenas a través de JSX. Eso hace posibles las comprobaciones de unicidad, pruebas de longitud y revisiones masivas.

Fase 4 — Puertas técnicas (no saltar)

Lee references/technical-seo.md. Antes de dar por terminada cualquier página, confirma en el HTML construido o desplegado:

• Estado 200 para páginas reales y un 404 real (no un 200 con texto "no encontrado") para URLs desconocidas.
• Canónica absoluta autoreferenciada, y sin canónica/robots heredados por accidente de un layout padre.
• Las páginas indexables están en el sitemap con un lastmod honesto; las páginas noindex no lo están.
• Las páginas que quieras ocultar usan noindex (meta o X-Robots-Tag) y no están bloqueadas en robots.txt, de lo contrario Google nunca puede leer el noindex.
• El contenido principal, H1, respuestas de FAQ y enlaces internos están presentes en el HTML crudo (recuento de palabras y verificación de H1 de seo_check.py).
• Un host preferido (https, www o apex) con redirecciones 301 de un solo salto desde los demás.
• Core Web Vitals no han empeorado (LCP ≤ 2.5 s, INP ≤ 200 ms, CLS ≤ 0.1). Para datos de campo usa PageSpeed Insights / CrUX, o las habilidades seo-performance / seo-google si están instaladas.

Fase 5 — Off-page y distribución

Lee references/off-page.md. El trabajo en la página hace que una página sea elegible; los enlaces y la demanda de marca deciden qué tan alto llega para cualquier cosa competitiva. Planifica la ganancia de enlaces junto con la página, no después:

• Construye un activo enlazable por clúster (herramienta gratuita, repositorio de plantillas, tabla de datos, guía original).
• Envía a los pocos directorios y plataformas de lanzamiento que se ajusten a la audiencia, escritos como publicaciones genuinas.
• Usa plataformas visuales (Pinterest, YouTube Shorts) para nichos visuales; GitHub para audiencias de desarrolladores.
• Configura Bing Webmaster Tools e IndexNow (el índice de Bing alimenta la búsqueda de ChatGPT y Copilot).
• Nunca compres enlaces, te unas a esquemas de enlaces, ni envíes masivamente a directorios basura.

Cuando no puedas hacer el trabajo off-page tú mismo, produce un kit listo para ejecutar para el usuario: lista de objetivos, borradores de publicaciones, borradores de correos de divulgación y un calendario.

Fase 6 — Verificar, publicar, monitorear

Lee references/measurement.md.

• Vuelve a ejecutar seo_check.py contra las páginas construidas o desplegadas y compara con la línea base de la Fase 1. Para cambios en layouts o componentes compartidos, compara todos los tipos de página, no solo el que editaste — un cambio en todo el sitio puede alterar silenciosamente páginas que ya clasifican.
• Después del despliegue: reenvía el sitemap, solicita indexación solo para el puñado de URLs nuevas más importantes, haz ping a IndexNow.
• Después de 2–4 semanas: ejecuta python3 <skill-dir>/scripts/gsc_opportunities.py <gsc-export.json|csv> para listar consultas a distancia de ataque, páginas con bajo CTR y canibalización, luego itera en títulos, secciones y enlaces internos para esas.

Reglas ganadas con esfuerzo

Estas provinieron de regresiones reales. Cada una costó rankings o indexación antes de ser encontrada.

• Verifica lo que los rastreadores realmente reciben. Un spinner de carga a nivel de ruta, importaciones dinámicas con ssr: false, o un fundido de entrada que comienza en opacity: 0 pueden dejar el HTML del servidor con solo "Cargando…" mientras el navegador se ve perfecto. Los rastreadores de IA no ejecutan JavaScript en absoluto.
• Las animaciones de entrada ocultan el hero. Las bibliotecas de animación (framer-motion initial={{ opacity: 0 }}, AOS, GSAP) renderizan en servidor su estado inicial, por lo que el H1 y la introducción se envían invisibles hasta la hidratación, retrasando el LCP. Usa initial={false} o animación solo con CSS para cualquier cosa en la parte superior; busca en el HTML construido opacity:0.
• Los cuerpos de CMS añaden un segundo H1. El Markdown que comienza con # Título debajo de un H1 a nivel de página lo duplica. Reduce los H1 del cuerpo a H2 en el renderizador.
• Soft 404s de SSR con streaming. Una vez que una respuesta transmitida ha comenzado, un notFound() posterior no puede cambiar el 200. Rechaza slugs desconocidos antes de renderizar (parámetros estáticos con params dinámicos deshabilitados), o devuelve un noindex explícito desde la rama de falta de metadatos.
• Canónicas heredadas. Una canónica en un layout raíz se filtra a todas las páginas que no establecen la suya propia. Un soft 404 que la hereda se convierte en un duplicado indexable de una página real.
• "API caída" no es "sin resultados". El código que decide notFound() o noindex debe distinguir una captura fallida de un resultado vacío, o una interrupción desindexa páginas reales.
• Contenido oculto. Los acordeones que desmontan paneles cerrados eliminan las respuestas de FAQ del HTML. Mantenlos montados (hidden="until-found" o CSS) para que sean rastreables y encontrables por búsqueda en la página.
• Los componentes compartidos son radio de explosión. Cuando una página clasifica bien, cambia los componentes SEO compartidos detrás de props opt-in y compara el HTML construido de las otras páginas antes y después.
• Calificaciones inventadas. Cualquier esquema aggregateRating sin reseñas reales de usuarios es una violación de las políticas de Google. Nunca generes datos estructurados de calificaciones que no provengan de un sistema de reseñas real.

Buena suerte. Escribe HTML que Google pueda leer, elige peleas que puedas ganar y mide antes de optimizar.