Communitygithub.com

MCERQUA/jam-skills

Construye sitios web Next.js 15 listos para producción desde cero con un flujo de trabajo basado en investigación: descubrimiento → investigación profunda (palabras clave, competidores, estrategia de contenido, mapa temático) → planificación de diseño → andamiaje → construcción → despliegue. ACTIVADOR: 'construir un sitio web', 'crear un sitio para mi negocio', iniciar un nuevo proyecto web. NO ACTIVAR para editar un sitio existente (web-dev) o un solo artículo (article-writer).

¿Qué es jam-skills?

Esta habilidad está diseñada para guiar a agentes de IA (como Claude Code, Cursor, etc.) en la construcción completa de sitios web profesionales con Next.js 15, desde la fase inicial de investigación hasta el despliegue. Su enfoque principal es un flujo de trabajo estructurado en 13 fases, donde las primeras cuatro fases se dedican exclusivamente a la investigación y planificación, sin escribir una sola línea de código. Esto garantiza que cada decisión de diseño, contenido y desarrollo esté respaldada por datos reales de palabras clave, análisis de competidores y una estrategia de contenido sólida. La habilidad es especialmente útil para proyectos como sitios de servicios locales, SaaS, portafolios o generación de leads SEO, integrando reglas de optimización de conversión (CRO) y un tech stack moderno que incluye Next.js 15, React 19, Tailwind CSS v3, shadcn/ui y Motion. Además, impone reglas estrictas para evitar errores comunes como usar contenido predeterminado, copias sin investigación de palabras clave, o prácticas que violan las políticas de spam de Google, como el secuestro del botón de retroceso.

Compatible con✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/MCERQUA/jam-skills/tree/HEAD/website-builder

Preguntar en tu IA favorita

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

Documentación

⚠️ LEE PRIMERO: PNPM_11_REQUIREMENTS.md en este directorio de habilidad. Los contenedores Webdev (donde Mike previsualiza tus sitios) usan pnpm 11.1.1 desde 2026-05-13. CADA nuevo proyecto DEBE declarar pnpm.onlyBuiltDependencies en package.json (como mínimo: ["sharp"] para cualquier proyecto Next.js) o el servidor de desarrollo NO INICIARÁ. Ignorar esto provoca bucles de reinicio del contenedor, el sitio da error 502 y el usuario te culpa. Lectura de 60 segundos; ignóralo bajo tu propio riesgo.

Constructor de Sitios Web — Habilidad Completa para Next.js

Construcción de sitios web basada en investigación y diseño intencional. Cada decisión respaldada por datos, cada sección justificada por la investigación.

Cuándo Usar Esta Habilidad

ACTÍVALA cuando el usuario pida:

  • Construir un nuevo sitio web
  • Crear un sitio web para su negocio
  • Iniciar un nuevo proyecto web
  • "Hazme un sitio"

NO USAR para:

  • Páginas Canvas (usa la habilidad canvas-web-design)
  • Editar un proyecto de sitio web existente (sigue el archivo .claude/CLAUDE.md de ese proyecto)
  • Proyectos de video Remotion (usa la habilidad remotion-video)

REGLAS NO NEGOCIABLES

  1. NUNCA escribas código antes de completar la investigación y la planificación del diseño. Las fases 1-4 producen cero código. Eso es correcto.
  2. NUNCA entregues una página con valores predeterminados de plantilla. Si ves "Logo", "(555) 000-0000", "[email protected]", "Servicio Uno" — HAS FALLADO.
  3. NUNCA escribas texto sin investigación de palabras clave. Cada título debe apuntar a una palabra clave específica de la Fase 3.
  4. NUNCA te saltes el plan de diseño. Cada sección, color y animación debe tener una RAZÓN documentada.
  5. NUNCA uses tácticas de miedo o titulares basados en el miedo. Escribe textos centrados en beneficios y orientados a SEO.
  6. SIEMPRE ejecuta la limpieza de contenido predeterminado antes de presentar cualquier sitio. Tolerancia cero.
  7. SIEMPRE personaliza cada sección. Si una sección renderiza valores predeterminados, olvidaste pasar las props.
  8. NUNCA implementes secuestro del botón de retroceso. Sin bucles history.pushState, trampas de redirección, o cadenas de modales/superposiciones que impidan que el botón Atrás del navegador devuelva al usuario a la SERP — una violación de la política de spam de Google (prácticas maliciosas, aplicada desde 2026-06-15) que conlleva riesgo de acción manual y degradación. Audita scripts de intención de salida, intersticiales y cualquier código de anuncios/bibliotecas incluidas (la violación a menudo se origina allí, no en el código propio). Verifica en la Fase 12. (developers.google.com/search/blog/2026/04/back-button-hijacking)

Tipos de Sitio

Identifica durante la recepción del proyecto — cambia todo:

TipoObjetivoSecciones ClaveEstilo de Texto
Generación de Leads SEOPosicionar + capturar leadsHero + BarraDeConfianza + CuadrículaDeCobertura + CómoFunciona + FAQ + Testimonios + CTARico en palabras clave, centrado en beneficios, profesional
Servicio LocalLlamadas telefónicas + formulariosHero + BarraDeConfianza + Servicios + ÁreasDeServicio + Reseñas + CTADirecto, genera confianza, orientado a ubicación
PortafolioMostrar trabajoHero + CuadrículaDeProyectos + AcercaDe + Proceso + ContactoVisual, texto mínimo, deja que el trabajo hable
SaaS / ProductoRegistros / pruebas gratuitasHero + Características + Precios + Testimonios + FAQ + CTACentrado en beneficios, impulsado por comparaciones

Sitios de servicio local: Consulta la sección Reglas CRO para Servicio Local a continuación antes de construir cualquier sitio de servicios para el hogar o contratistas. La mayoría de los sitios locales convierten por debajo del 1%. Estas reglas apuntan a un 3–5%.


Reglas CRO para Servicio Local

Fuente: Auditoría de conversión de Noah Igler (@noahiglerSEO) en sitios de servicios para el hogar (fontaneros, HVAC, techadores, electricistas, paisajistas, etc.). La mayoría de los sitios reciben buen tráfico pero el teléfono no suena — porque el sitio pierde leads, no tráfico.

La mayoría de los sitios de servicios para el hogar convierten por debajo del 1%. Estas reglas apuntan a un 3–5% con el mismo tráfico.

Sobre el Pliegue (el 80% de las conversiones se ganan o pierden aquí)

En 3 segundos desde que aterrizan, los visitantes deben saber: qué haces, dónde lo haces, que eres confiable y cómo llamarte. Cada elemento a continuación es obligatorio, no opcional.

  • Formato del titular: "[Servicio] en [Ciudad]" o "La empresa de [Servicio] de confianza en [Ciudad]" — NO "Su socio de servicios para el hogar de confianza desde 2003"
  • Número de teléfono: Arriba a la derecha, fuente grande, fijo mientras el usuario se desplaza — enlace directo a tel: (SIN modal, SIN ventana emergente, SIN paso de confirmación — un modal le causó a un cliente una caída del 30% en las llamadas)
  • Barra de confianza / subtitular: Calificación de estrellas + número de reseñas + años en el negocio + número de licencia + área de servicio — todo en el hero
  • CTA principal: "Llamar Ahora" o "Obtener Presupuesto Gratuito" — muestra el número de teléfono EN el botón o inmediatamente debajo
  • Imagen del hero: Fotos reales de tu equipo con camisetas de la marca, camionetas en obras, o trabajos reales — SIN fotos de stock de familias sonrientes (los visitantes las detectan al instante; la confianza se vuelve negativa)

Visibilidad del Teléfono — La Palanca Más Importante

  • Encabezado fijo: el número de teléfono siempre visible en móvil mientras el usuario se desplaza
  • Barra de pie fija en móvil: dos botones — "Llamar Ahora" (enlace tel:) y "Reservar Online" — siempre a la vista
  • Botón de acción flotante en páginas largas
  • Aumenta el volumen de llamadas en un 15–25% en la práctica

Formularios — Cada Campo Adicional Cuesta ~10% de Conversiones

Máximo 4 campos para cualquier formulario de leads de servicios para el hogar:

  1. Nombre
  2. Teléfono
  3. Servicio necesario (menú desplegable — no texto libre)
  4. Dirección

Nunca agregues: correo electrónico, "mejor hora para llamar", "¿cómo nos conociste?", cuadro de comentarios, comprobante de dirección, ni ninguna pregunta de calificación. No estás procesando una solicitud de crédito — estás obteniendo su número de teléfono para poder devolver la llamada. La calificación ocurre en la llamada.

Velocidad Móvil — No Negociable

  • Por debajo de PageSpeed 50 en móvil = perder 2–3 posiciones en el Map Pack
  • Por debajo de PageSpeed 70 = perder 20–30% de los visitantes móviles antes de que la página cargue
  • Objetivo: PageSpeed 70+ en móvil, carga de página < 2 segundos

Soluciones de velocidad (en orden de impacto):

  1. Comprimir la imagen del hero a 200–400KB (la mayoría de los sitios envían imágenes de hero de 2–3MB)
  2. Eliminar plugins y scripts de seguimiento innecesarios
  3. Usar una CDN real (no solo la opción empaquetada del hosting)
  4. Carga diferida de todo lo que esté debajo del pliegue
  5. Minimizar widgets de terceros (chat en vivo, embeds de redes sociales, agregadores de reseñas) — cargan tarde y cubren el número de teléfono

Reseñas / Prueba Social — Deben Aparecer en Cada Profundidad de Desplazamiento

No pongas toda la prueba en una sección de testimonios a medio camino. Los visitantes necesitan verla en cada nivel:

  • Sobre el pliegue: "4.9 estrellas de 312 reseñas de Google" — recuento + calificación en la barra de confianza del hero
  • Sección hero: 2–3 citas cortas de reseñas reales, preferiblemente dinámicas desde GBP
  • Páginas de servicio: sección de reseñas dedicada que extraiga citas que mencionen ese servicio específico
  • Junto al formulario: repite la prueba justo antes de la solicitud

El objetivo: para cuando lleguen al formulario, han visto la prueba 5–6 veces.

Fotos — Imágenes Reales Siempre en Lugar de Stock

  • Fotos reales del equipo con camisetas de la marca en obras
  • Camionetas estacionadas en casas de clientes reales
  • Fotos de antes y después (limpieza de desagües, trabajo en paneles, instalaciones de AC, conductos, reemplazos de techos)
  • Documentos de licencia, certificaciones del fabricante, certificados de seguro fotografiados y mostrados
  • El sitio debe parecer un negocio físico con personas reales, no una plantilla en la que una agencia de marketing puso un logotipo

Financiamiento — Requerido para Servicios de Alto Costo ($5K+)

~60% de los clientes para trabajos de reemplazo quieren financiamiento. Si tu competidor muestra el logotipo de Synchrony / GreenSky / Wisetack y tú no, ellos cierran el trato antes de que puedas cotizar.

  • Logotipo del socio financiero visible sobre el pliegue en las páginas de servicio
  • "Financiamiento al 0% disponible" o "Pagos desde $89/mes" en el hero
  • Página de financiamiento separada enlazada desde la navegación principal
  • Widget de precalificación integrado en páginas de servicio de alto costo

Errores Comunes que Matan las Conversiones

Estos aparecen constantemente en las auditorías — no implementes ninguno:

  • Formularios más largos para "calificar" leads — no los estás calificando, los estás perdiendo
  • Ocultar el teléfono para forzar el llenado de formularios — simplemente se van
  • Video con reproducción automática en la sección hero — mata la velocidad móvil, molesta al visitante
  • Ventanas emergentes en la primera visita — gatillo inmediato del botón de retroceso en móvil
  • Widgets de chat en vivo — tardan 4s en cargar, cubren el número de teléfono, no aportan valor para servicios del hogar

Stack Tecnológico (cada proyecto)

HerramientaPaquetePropósito
Next.js 15nextApp Router, componentes del servidor, acciones del servidor
React 19reactFramework de UI
TypeScripttypescriptSeguridad de tipos
Tailwind CSS v3tailwindcssEstilos basados en utilidades (v3 — NO v4, v4 tiene problemas con PostCSS)
shadcn/uishadcn (CLI)Librería de componentes (Radix + Tailwind)
MotionmotionAnimaciones (física de muelle, scroll, layout)
LenislenisScroll suave (< 4kb, accesible)
Lucide Reactlucide-reactIconos SVG

Opcional (instalar cuando sea necesario)

HerramientaPaqueteCuándo
Pretext@chenglou/pretextMedición de texto sin reflujo del DOM — listas virtualizadas, interfaces de chat, cuadrículas de mampostería, contenedores de texto con autoajuste, renderizado de texto en canvas. ~500x más rápido que getBoundingClientRect. Cero dependencias. Ver /mnt/shared-skills/pretext/SKILL.md
GSAPgsapSecuencias de scroll complejas, SplitText, MorphSVG
Three.jsthree + @react-three/fiberFondos 3D o elementos hero
MDX@next/mdxBlog con contenido enriquecido
PrismaprismaAcceso a base de datos

Flujo de Trabajo en 13 Fases

Sigue estas fases EN ORDEN. No te saltes fases. Las fases 1-4 producen CERO código — producen investigación y un plan. Ese es el objetivo.

Fase 1: DESCUBRIMIENTO

Lee: instructions/brand-intake.md

Haz al cliente las preguntas de recepción de marca ANTES que cualquier otra cosa:

  • Identidad del negocio, industria, cliente objetivo
  • Colores de marca, tono, personalidad
  • Objetivos SEO, competidores, qué buscan los clientes
  • Páginas necesarias, características especiales, CTA principal
  • Tipo de sitio (generación de leads SEO, servicio local, portafolio, SaaS)

Entregable: Respuestas completas de la recepción

Fase 2: CONFIGURACIÓN

Lee: instructions/folder-setup.md

Crea la estructura de carpetas ai/ dentro del directorio del proyecto:

  1. Crea todos los directorios de investigación (01-07)
  2. Crea los directorios de diseño, contenido e investigación de blog
  3. Inicializa research-status.json
  4. Rellena 01-business-profile/profile.md con las respuestas de la recepción

Entregable: Estructura de carpetas ai/ completa con el perfil del negocio rellenado

Fase 3: INVESTIGACIÓN (la base — NO TE APRESURES)

Lee: instructions/research-plan.md

Seis tareas de investigación que informan TODO lo que sigue:

  1. Investigación de palabras clave — Encuentra 50-100+ palabras clave en categorías primarias, secundarias, de cola larga y de ubicación. Documenta en ai/research/02-keyword-research/. Busca en Google, captura preguntas de PAA, construye grupos de palabras clave.

  2. Análisis profundo de competidores — Revisa 5-10 sitios de competidores en detalle. Para cada uno: documenta las secciones de su página de inicio, diseño del hero, CTAs, diseño visual, tipografía, animaciones, calidad del contenido, fortalezas, debilidades. Crea archivos de revisión por competidor en ai/research/03-competitor-analysis/site-reviews/. Luego sintetiza en pattern-analysis.md (patrones comunes en el nicho) y gaps-opportunities.md (lo que explotamos).

  3. Estrategia de contenido — Mapa de cada página: URL, palabras clave, secciones, H1, metaetiquetas. Crea briefs de contenido por página en ai/research/04-content-strategy/content-briefs/. Investiga preguntas de FAQ desde PAA, Reddit, foros.

  4. Mapa temático — Construye la arquitectura de clusters de temas: páginas pilar, contenido de cluster, estrategia de enlazado interno. Documenta en ai/research/05-topical-map/.

  5. SEO Local (si aplica) — Áreas de servicio objetivo, competidores locales, palabras clave específicas de la ciudad. Documenta en ai/research/06-local-seo/.

  6. Patrones de conversión — Analiza los CTAs de los competidores, señales de confianza, patrones de prueba social. Mapa del embudo de conversión. Documenta en ai/research/07-conversion-patterns/.

Entregable: 20-40 archivos de investigación en 7 directorios. Actualiza research-status.json.

Fase 4: PLAN DE DISEÑO (la fase de pensamiento — cada decisión intencional)

Lee: instructions/design-plan.md

Aquí es donde un sitio pasa de ser "otra plantilla" a algo que FUNCIONA. Seis documentos de diseño:

  1. Auditoría visual de competidores (ai/design/competitor-visual-audit.md) — Revisa todos los sitios de competidores en busca de patrones visuales: tipos de hero, orden de secciones, esquemas de color, tipografía, animaciones, estilo de fotografía. Clasifícalos por calidad visual. Identifica qué superar.

  2. Dirección de estilo (ai/design/style-direction.md) — Elige la estética con justificación. Colores, fuentes, modo oscuro/claro, espaciado — cada elección trazada hasta la recepción de marca + análisis de competidores + contexto de la industria.

  3. Plan de componentes (ai/design/component-plan.md) — Cada componente necesario, en orden, con su propósito. ¿Por qué este diseño de hero? ¿Por qué este estilo de barra de confianza? ¿Por qué estas secciones en este orden? Mapa hacia el embudo de conversión.

  4. Plan de animación (ai/design/animation-plan.md) — Qué se mueve, por qué, cómo. Animaciones de entrada, estados hover, efectos de scroll. Movimiento intencional, no decoración aleatoria.

  5. Wireframes de página (ai/design/page-wireframes.md) — Diseño sección por sección para cada página. Wireframes ASCII que muestran la estructura.

  6. Brief de diseño (ai/design/design-brief.md) — Documento maestro. Resume todas las decisiones de diseño, enumera lo que hace que este sitio "destaque" frente a los competidores, conecta cada elección con la investigación.

Entregable: 6 documentos de diseño. El brief de diseño es la referencia para toda la construcción.

Fase 5: ANDAMIAJE

Lee: instructions/architecture.md Usa: directorio templates/project/

  1. Copia templates/project/ a Websites/<project-name>/
  2. Ejecuta pnpm install
  3. Instala shadcn: pnpm dlx shadcn@latest init
  4. Instala componentes centrales de shadcn: pnpm dlx shadcn@latest add button card badge separator input textarea label
  5. Instala dependencias de animación: pnpm add motion lenis
  6. Inicializa git, haz commit del andamiaje
  7. Crea un repositorio privado en GitHub, haz push, crea la rama web-dev
  8. Rellena .claude/CLAUDE.md usando templates/config/claude-project.md

Fase 6: SISTEMA DE DISEÑO

Lee: instructions/design-system.md Usa: templates/config/design-tokens/

  1. Configura las variables de Tailwind: colores (desde la recepción de marca), fuentes, espaciado, breakpoints
  2. Configura los tipos de letra globales (variable font + font familia de respaldo)
  3. Crea componentes de sistema base: Button, Badge, Card, Section, Container con variantes del brief de diseño
  4. Configura el modo oscuro si aplica
  5. Prueba la coherencia visual en todas las páginas

Entregable: Sistema de diseño implementado con todos los tokens y componentes base configurados

Fase 7: COMPONENTES DEL HERO

Lee: instructions/hero-component.md Usa: templates/components/Hero/

Siempre comienza con el hero. Es la primera impresión del sitio.

  1. Implementa el diseño del hero desde el plan de diseño
  2. Componente Hero principal con: titular, subtitular, CTA, imagen/fondo
  3. Componente TrustBar integrado en el hero
  4. Añade animaciones de entrada con motion
  5. Asegura que el hero responda
  6. Haz commit del hero en su propia rama

Entregable: Hero implementado, versionado en su rama

Fase 8: SECCIÓN DE SERVICIOS / CARACTERÍSTICAS

Lee: instructions/services-section.md

Construye la sección que explica qué ofreces:

  1. Implementa la cuadrícula de servicios desde el plan de diseño
  2. Añade animaciones de entrada para cada tarjeta
  3. Implementa la navegación por pestañas (si aplica)
  4. Añade animaciones de scroll
  5. Responde en todos los tamaños de pantalla

Entregable: Sección de servicios completa con animaciones

Fase 9: SECCIONES RESTANTES

Lee: instructions/remaining-sections.md

Construye todas las secciones restantes en orden del plan de diseño:

  1. Sección Acerca de
  2. Sección de Proceso / Cómo funciona
  3. Sección de Testimonios / Reseñas
  4. Sección de FAQ
  5. Sección de Precios (si aplica)
  6. Sección de CTA / Contacto
  7. Pie de página

Cada sección debe:

  • Coincidir con el wireframe del plan de diseño
  • Incluir animaciones de entrada
  • Responder a todos los tamaños de pantalla
  • Personalizar valores predeterminados

Entregable: Todas las secciones construidas y estilizadas

Fase 10: CONTENIDO Y COPIA

Lee: instructions/content-copy.md

Usando la investigación de palabras clave de la Fase 3, escribe todo el texto del sitio:

  1. Escribe titulares dirigidos a palabras clave específicas
  2. Escribe descripciones y contenido del cuerpo
  3. Escribe meta descripciones y etiquetas de título
  4. Escribe texto FAQ con términos de búsqueda reales
  5. Añade texto alternativo a las imágenes
  6. Asegura que cada sección tenga contenido único

Entregable: Todo el texto del sitio escrito y optimizado para SEO

Fase 11: REFINAMIENTO DE ANIMACIONES

Lee: instructions/animation-refinement.md

Refina todas las animaciones:

  1. Añade animaciones de scroll a las transiciones de sección
  2. Configura la duración, el retraso y la función de temporización de las animaciones
  3. Añade animaciones hover a elementos interactivos
  4. Asegura que las animaciones no interfieran con la accesibilidad (prefers-reduced-motion)
  5. Prueba el rendimiento (sin parpadeo del layout, sin tartamudeo)

Entregable: Animaciones refinadas y que funcionan bien

Fase 12: QA FINAL Y DESPLIEGUE

Lee: instructions/final-qa.md

Ejecuta la lista de verificación final:

  1. Limpieza de contenido predeterminado: Sin contenido de relleno, sin datos de muestra, sin marcadores de posición de imagen
  2. Verificación de accesos directos: Sin bucles de history.pushState, sin trampas de redirección, el botón Atrás funciona correctamente
  3. Pruebas de velocidad: Prueba PageSpeed Insights, apunta a 70+ en móvil
  4. Pruebas de conversión: Verifica los enlaces tel:, los formularios funcionan, los CTAs son visibles
  5. Pruebas de SEO: Verifica metaetiquetas, etiquetas de título, texto alternativo, estructura de encabezados
  6. Pruebas de respuesta: Prueba en todos los tamaños de pantalla
  7. Pruebas del navegador: Prueba en Chrome, Firefox, Safari
  8. Despliegue: Despliega el sitio, verifica que funcione en producción

Entregable: Sitio desplegado, probado y funcionando


Comandos Rápidos

# Crear nuevo proyecto
cp -r templates/project Websites/<project-name>
cd Websites/<project-name>
pnpm install
pnpm dlx shadcn@latest init
pnpm dlx shadcn@latest add button card badge separator input textarea label
pnpm add motion lenis

# Desarrollo
pnpm dev

# Construcción
pnpm build

Apéndice: Archivos de Instrucciones

Todos los archivos de instrucciones referenciados arriba existen en el directorio instructions/ dentro de esta habilidad. Cada uno contiene guías detalladas paso a paso para su fase.

  • instructions/brand-intake.md — Preguntas de recepción de marca
  • instructions/folder-setup.md — Configuración de estructura de proyecto
  • instructions/research-plan.md — Plan de investigación detallado
  • instructions/design-plan.md — Guía de planificación de diseño
  • instructions/architecture.md — Decisiones de arquitectura
  • instructions/design-system.md — Guía del sistema de diseño
  • instructions/hero-component.md — Construcción del hero
  • instructions/services-section.md — Sección de servicios
  • instructions/remaining-sections.md — Construcción de secciones restantes
  • instructions/content-copy.md — Escritura de contenido SEO
  • instructions/animation-refinement.md — Refinamiento de animaciones
  • instructions/final-qa.md — Lista de verificación de QA final y despliegue

Apéndice: Archivos de Plantilla

El directorio templates/ contiene todas las plantillas de inicio referenciadas en las fases:

  • templates/project/ — Estructura de proyecto Next.js completa
  • templates/config/ — Archivos de configuración
  • templates/components/ — Componentes de ejemplo
  • templates/styles/ — Estilos base

Skills relacionados