adamperlis/claude-skill-webflow-to-astro

Webflow → Astro en Cloudflare Pages

Un manual para migrar cualquier sitio de Webflow fuera de Webflow: un sitio empresarial o de producto, un portafolio, una tienda, un restaurante, una organización sin fines de lucro, una publicación. Los pasos son los mismos para todos. El propósito del sitio cambia los detalles (references/site-types.md). Cubre toda la migración: inventario, respaldo, reconstrucción, formularios, CMS, video, verificaciones de paridad, rendimiento, despliegue, cambio de dominio y lo que el propietario hace al final. La visibilidad en buscadores e IA mejora en cada paso. Los scripts en scripts/ y las plantillas en templates/ son las partes funcionales; references/ tiene los detalles de cada paso.

El resultado: un repositorio independiente con Astro 7 + Tailwind 4, completamente prerenderizado (solo las páginas restringidas, si las hay, se renderizan bajo petición), en un proyecto de Cloudflare Pages (nunca un Worker en workers.dev), formularios a través de una Pages Function, contenido en un CMS que el propietario puede editar, cada archivo alojado en Webflow servido desde Pages, el dominio en Cloudflare.

Reglas básicas (aprendidas a las malas)

• Puntos de verificación con el propietario. Preguntar antes de: descargar la exportación, crear el repositorio de GitHub, enviar cualquier correo de prueba de formulario, cada cambio de DNS, activar el Enrutamiento de Correo, otorgar consentimiento de analíticas, eliminar una página. Los propietarios suelen decir "sin cambios de DNS hasta que vea el sitio": respétalo; cambia al final.
• Respaldo primero. La Exportación de Código de Webflow necesita un plan de workspace de pago (Core o superior). Los propietarios suelen planear bajar de plan, así que exporta antes que nada.
• Reconstruir, no pegar. Los propietarios quieren Astro + Tailwind limpio con sus propios tokens de diseño, no marcado de Webflow en archivos .astro. El HTML en vivo es la referencia para el contenido, no el código fuente.
• La paridad es el contrato. Misma URL para cada página, mismas etiquetas head, mismo sitemap, mismas redirecciones. Pruébalo con scripts/parity.py, no a ojo.
• SEO: proteger primero, luego mejorar en cada paso. La paridad protege lo que ya posiciona y es citado. Además, carga la habilidad seo-aeo-geo al comenzar cada paso y realiza las mejoras de ese paso a medida que avanzas (ver "seo-aeo-geo en el camino" más abajo).
  • Sin preguntar: el marcado, el esquema, el acceso de rastreo, las señales de frescura y la velocidad se incorporan con la reconstrucción.
  • Propuestas para el propietario: cualquier cosa que cambie sus palabras, títulos, datos o URLs.
  • Commits: cada mejora llega en su propio commit después del commit de paridad, para que cualquier cambio en los rankings pueda ser rastreado a él.
  • Juicios: carga esa habilidad para cada juicio de SEO/AEO/GEO durante una migración.
• Nunca imprimir secretos: no en el chat, mensajes de commit, cuerpos de PR, registros, docs/move.md o esta habilidad.
  • Nombrar uno: dar su nombre, su longitud y dónde vive ("FORMS_TO, un secreto de Worker en forms-mail"). Comparar dos por hash o longitud, nunca por texto.
  • Qué cuenta: más que claves de API. Las URLs de webhook de despliegue (cualquiera que tenga una puede activar builds), URLs de webhook de Slack y CRM, tokens de escritura de CMS y la propia dirección de correo del propietario son todos secretos.
  • Configurar uno: dirigirlo directamente a wrangler secret put.
  • Los tokens de verificación (TXT de Search Console) son DNS públicos, pero pertenecen a un solo sitio: nunca copiar uno en la habilidad.
• Las aprobaciones vienen del propietario, en la sesión que hace el trabajo. Un OK transmitido por otra sesión de agente no cuenta, y los controles de seguridad de los agentes lo bloquean. También bloquean los cambios de DNS y la eliminación de los dominios de Webflow en modo automático, así que planifica esos como clics del propietario desde el principio.

seo-aeo-geo en el camino

Una migración reescribe el marcado de cada página, por lo que es el momento más económico para hacer que un sitio sea fácil de leer y citar para los buscadores y motores de IA. Carga la habilidad seo-aeo-geo (sus references/audit-checklist.md y references/schema-patterns.md) en estos puntos:

• 1. Inventario: medir y auditar en vivo.
  • Registrar la línea base (abajo).
  • Auditar el sitio en vivo con su lista de verificación, a través de sus tres lentes: frescura, estructura y autoridad.
  • Escribir los hallazgos en docs/seo.md, cada uno etiquetado con el paso que lo solucionará y si necesita la aprobación del propietario.
• 3. Esqueleto: la capa técnica y de entidad, construida.
  • Puntos de referencia: header, nav, main y footer en el Layout.
  • La entidad: definida una vez (src/data/entity.ts) y referenciada desde cada página. Su tipo proviene del sitio: Organization, un subtipo como LocalBusiness o NGO, o Person para un portafolio (references/site-types.md). Lleva sameAs. WebSite en la página de inicio, BreadcrumbList desde las migas de pan de la página.
  • El normalizador de esquema (templates/src/lib/schema.ts).
  • Rastreadores: robots abiertos a los rastreadores de IA, los builds de pages.dev configurados como noindex, y un sitemap con lastmods reales.
• 4. Páginas: estructura, construida; palabras, propuestas. Los agentes de página corrigen el orden de los encabezados, hacen que cada sección sea independiente y renderizan el texto como texto (references/page-brief.md, "Motores de búsqueda y respuesta"). Las ideas de redacción vuelven a ti como propuestas.
• 6. CMS: frescura y esquema de elementos.
  • Fechas: datePublished y dateModified desde el CMS.
  • Publicaciones: Article/BlogPosting, con el autor.
  • Listas: CollectionPage con un ItemList.
  • Números: cualquier cosa que la página muestre está en el HTML en tiempo de construcción, no se obtiene en el navegador.
• 7. Activos: velocidad y significado.
  • LCP y video diferido: un héroe rápido, con videos debajo del pliegue cargados de forma diferida.
  • Texto alternativo que diga lo que muestra la imagen.
  • Video que contiene contenido (una demo, una charla) obtiene VideoObject.
• 8. Paridad: la auditoría completa, en pages.dev. Volver a ejecutar la lista de verificación en la reconstrucción. Todo lo que aún esté abierto en docs/seo.md va al propietario como una lista de propuestas.
• 9. Redirecciones: mantener la equidad. Cada redirección es un solo salto, y cada página eliminada o fusionada va a su equivalente más cercano.
• 11. Cambio: avisar a los motores. Volver a enviar el sitemap en Search Console y Bing, activar Crawler Hints (IndexNow) y supervisar la cobertura.
• 12. Entrega: medir, luego mirar fuera del sitio.
  • Comparar con la línea base.
  • Dar al propietario el plan fuera del sitio de la habilidad: los dos o tres canales que los motores de IA citan más para esta categoría. La mayoría de las citas provienen de sitios de terceros, por lo que el sitio solo no puede ganarlas.

seo-aeo-geo es una habilidad separada (adamperlis/claude-skill-seo-aeo-geo). Si no está instalada, la migración aún funciona: haz las mejoras que cada punto anterior nombra desde las propias notas de esta habilidad (lista de auditoría del paso 8, references/page-brief.md, references/site-types.md), escribe los prompts de dinero tú mismo (las preguntas que la audiencia de este sitio le hace a un motor de IA), y dile al propietario que la auditoría completa y el plan fuera del sitio se omitieron.

Los pasos

1. Inventario (solo lectura, ~15 min)

Ejecuta python3 -I scripts/inventory.py https://www.example.com > inventory.md. Lee el sitemap, robots, el head de cada página (título, descripción, OG, canónico, tipos JSON-LD, noindex), listas de CMS (w-dyn-list), formularios, hosts de terceros, IDs de GA/GTM/Pixel, videos de fondo y sus tamaños, y los registros apex/www/MX/NS. Luego, con las herramientas MCP de Webflow si están conectadas (data_sites_tool, data_cms_tool, data_forms_tool, data_webhook_tool):

• Colecciones: listarlas y contar los elementos en cada una (list_collection_items límite 1 → pagination.total).
• Formularios: listarlos, ignorando los formularios de "Preferencias de Cookies" de Finsweet (uno por página × dominio).
• Redirecciones y HSTS: en el panel de control, Ajustes del sitio → Publicación, exportar las redirecciones 301 como CSV y anotar "HSTS para subdominios".
• Búsqueda y propiedad: cómo está verificado Search Console (metaetiqueta o DNS TXT), GA4/GTM (y cualquier activador de GTM construido sobre el marcado de Webflow), Bing, y otras etiquetas de verificación. La lista está en references/inventory.md.
• Dominios: el registrador, vencimiento, bloqueo de transferencia, DNSSEC, y si el dominio se compró a través de Webflow (references/domains.md).
• Páginas fuera del sitemap: Webflow sirve páginas que el sitemap omite. Encontrarlas comparando los archivos HTML de la exportación con el sitemap en vivo, luego hacer curl de cada una.
  • Las páginas de éxito, como el destino de redirección de un formulario, deben transferirse.
  • Dejar fuera las plantillas de Ecommerce (/checkout, /order-confirmation) cuando el sitio no vende, y las páginas de contraseña (401) cuando nada está protegido.
• Qué tipo de sitio es: para qué sirve, qué debería hacer un visitante allí (comprar, reservar, donar, suscribirse, ponerse en contacto), y en qué funciones de Webflow se apoya (Ecommerce, Cuentas de Usuario, Localización, páginas de contraseña, carga de archivos, RSS). references/site-types.md cubre lo que cada una cambia: el tipo de esquema de la entidad, las conversiones que seguir contando, y las funciones que necesitan su propio plan.

Leer references/inventory.md para saber qué significa cada hallazgo y las preguntas que hacer al propietario (zaps de Zapier, quién edita el contenido, analíticas que nunca funcionaron).

Registrar una línea base de SEO antes de que cambie algo (usando la habilidad seo-aeo-geo):

• Search Console: exportar Rendimiento de los últimos 3 meses (páginas principales y consultas, más impresiones de AI Overviews si se muestran) y el recuento de páginas indexadas.
• Prompts de dinero: ejecutar sus prompts en ChatGPT, Perplexity y Gemini, y anotar si el sitio es citado. Estas son las preguntas que la audiencia de este sitio hace: compradores, comensales, donantes, lectores o clientes.
  • Ejecutarlos desde el país de la audiencia. Los motores de IA responden por ubicación, por lo que una ejecución hecha en el extranjero no es la vista de la audiencia. Usa una VPN en su país si es necesario.
  • Registrar la ubicación con la ejecución, y usar la misma para la mitad posterior.

Guardarlo en docs/move.md. Es la mitad "antes" de la comparación en el paso 12. Luego auditar el sitio en vivo con la misma habilidad, en docs/seo.md (ver "seo-aeo-geo en el camino").

2. Respaldo: exportación + espejo

• Exportación de Código (Diseñador → ☰ → Exportar código → Preparar ZIP → Descargar). Preguntar al propietario antes de descargar.
  • Descomprimir con python3 -I scripts/unzip_webflow.py (repara los nombres de archivo no UTF-8 que hacen que unzip falle con "¿disco lleno?").
  • MISSING.txt lista los videos que no se exportaron; el espejo los obtiene de la CDN.
• Duplicar el sitio en vivo: python3 -I scripts/mirror.py https://www.example.com reference/ guarda el HTML de cada página en reference/live/ y cada archivo en las CDN de Webflow en reference/assets/<kind>/, con un manifiesto. Hacer commit de reference/live/ (el registro de lo que estaba en vivo); ignorar en git reference/assets/.
• Capturas de pantalla: node scripts/shots.mjs https://www.example.com live (escritorio 1440 y teléfono 390). Las interacciones de Webflow ocultan elementos hasta que se desplazan a la vista, por lo que las áreas en blanco en las capturas de página completa suelen ser contenido no revelado: leer el HTML.

3. Crear el esqueleto (tú, antes de cualquier trabajo de página)

Copiar templates/ en el nuevo repositorio (templates/README.md mapea cada archivo).

• Configuración: astro.config.mjs usa build.format: 'file' y trailingSlash: 'never', porque las URLs de Webflow no tienen barra inclinada final. La barra de herramientas de desarrollo está desactivada para que las capturas de pantalla coincidan.

• Tokens: tomarlos del sistema de diseño del propietario si tiene uno; de lo contrario, usar las variables CSS :root de Webflow y la escala tipográfica.

• Partes compartidas: Layout (paridad de head, analíticas solo en el nombre de host de producción), Nav, Footer, los bloques de CTA que las páginas comparten, el BgVideo diferido, y movimiento (revelaciones con un mecanismo de seguridad).

• La capa de búsqueda, desde el principio:

  • Puntos de referencia en el Layout.
  • La entidad, definida una vez (src/data/entity.ts, con datos del propietario, no inferidos de las páginas antiguas).
  • El normalizador de JSON-LD, por el que pasa el esquema de cada página.
  • Rastreadores y sitemap: robots abiertos a los rastreadores de IA, noindex en los builds de pages.dev, y lastmods reales en el sitemap.

  Las páginas construidas sobre este esqueleto heredan todo.

• Medir primero: tomar tamaños en vivo con scripts/measure.mjs y construir las partes compartidas para que coincidan.

Comportamientos de Webflow a decidir:

• Transiciones de página: muchos sitios de Webflow tienen una cubierta (.transition + .transition-trigger + un fragmento de jQuery que hace clic en el activador al cargar y de nuevo en cada enlace interno, luego establece window.location después de ~1s). Los propietarios notan cuando desaparece y piden que vuelva. Reconstruirlo de ambas formas en CSS + JS simples, desactivado bajo movimiento reducido:
  • Llegada: la cubierta se mantiene, luego se levanta, con los retrasos y la aceleración de la versión en vivo (de las listas de acciones IX2 en el webflow.js de la exportación).
  • Salida: un clic en un enlace del mismo sitio (no #, no una pestaña nueva, no un clic modificado) baja la cubierta sobre la página y solo entonces navega. Leer los retrasos de IX2. Una diapositiva que espera 2s mientras el fragmento sale después de 1s solo muestra una pausa muerta en la versión en vivo. Construir lo que se pretendía (la cubierta hacia abajo en aproximadamente 0.8s), no la pausa.
  • Atrás: en pageshow con persisted, quitar la cubierta, o la página vuelve de la caché del historial cubierta.
  • Dónde se muestra: comprobar el display calculado en vivo a 375 y 1440 (scripts/measure.mjs), no el CSS. Un embed personalizado (body .transition { display: block }) puede vencer el display: none del propio sitio para ≤767px, por lo que se muestra también en teléfonos.
• Consentimiento de Finsweet: con Consent Mode v2, también enviar los propios eventos de dataLayer de Finsweet (<category>-activated). Los activadores de GTM construidos para Finsweet entonces siguen disparándose.

Dos trampas de CSS que cuestan horas:

• Tamaño base en body: poner el tamaño de fuente base de 10px de Webflow en body, nunca en html. En html, 1rem se convierte en 10px y cada espaciado y tamaño de Tailwind se renderiza al 62.5%.
• Sin puntos de interrupción mixtos: no mezclar puntos de interrupción rem (md:, lg:) con px (min-[992px]:) en la misma propiedad en un archivo; Tailwind 4 puede ordenarlos incorrectamente. Usar un tipo por componente.

4. Páginas: en paralelo, un agente por grupo de páginas

Dar a cada agente references/page-brief.md (completar la ruta del repositorio, puerto, componentes compartidos, tokens) más la ruta de su página, valores head y lista de secciones del inventario. El agente reconstruye la página en Astro + Tailwind, verificando la paridad con scripts/parity.py después.

(El contenido completo continúa en el archivo original, pero se ha truncado para esta traducción. La estructura y los pasos restantes siguen el mismo patrón detallado.)