Communitygithub.com

IncomeStreamSurfer/astro-builder-skill

Construye sitios web completos y optimizados para SEO usando Astro con Tailwind CSS, colecciones de contenido y la base de datos opcional Turso. Usa esta habilidad cada vez que el usuario quiera crear un sitio web, construir un sitio que posicione en Google, iniciar un proyecto Astro, hacer una landing page, un sitio de negocio, un blog o cualquier proyecto web donde el SEO importe.

¿Qué es astro-builder-skill?

Esta habilidad te permite construir sitios web profesionales con Astro, optimizados para motores de búsqueda y con un diseño premium. Sigue un flujo de trabajo estructurado en cinco fases: descubrimiento e investigación, configuración del proyecto, construcción de cada página con SEO y diseño de calidad, implementación de colecciones de contenido y base de datos opcional, y preparación para el despliegue. La pila tecnológica incluye Astro (framework estático), React para componentes interactivos, Tailwind CSS para estilos, colecciones de contenido de Astro para contenido tipo Markdown/MDX, y Turso con Drizzle para datos dinámicos. Destaca por su enfoque en SEO (meta tags, datos estructurados, sitemaps) y diseño no genérico (tipografía Geist, paletas neutras, diseños asimétricos). Es ideal para agencias, freelancers o desarrolladores que quieran lanzar sitios rápidos, escalables y bien posicionados.

Compatible con✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/IncomeStreamSurfer/astro-builder-skill/tree/HEAD/skill

Preguntar en tu IA favorita

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

Documentación

Constructor de Sitios Web SEO con Astro

Construyes sitios web completos y listos para desplegar en Astro, diseñados para posicionar en Google. Cada sitio incluye meta tags adecuados, datos estructurados, HTML semántico, imágenes optimizadas, sitemaps y contenido real investigado, no texto de relleno.

Cada interfaz que produzcas debe ser premium y no genérica. Lee references/taste-skill.md antes de escribir cualquier código de UI — contiene las reglas de diseño que evitan la salida genérica de "IA barata".

Stack Tecnológico

  • Astro — Framework estático primero, cero JS por defecto, perfecto para SEO
  • React — Componentes interactivos mediante islas Astro (formularios, nav, animaciones)
  • Tailwind CSS — Todo el estilo. Sin valores predeterminados de shadcn — personaliza todo según las reglas de taste-skill
  • Astro Content Collections — Contenido Markdown/MDX con tipado seguro para entradas de blog, servicios, testimonios
  • Turso + Drizzle — Base de datos SQLite en el edge (opcional, para formularios/datos dinámicos)

Resumen del Flujo de Trabajo

Cada proyecto sigue esta secuencia. No omitas pasos.

Fase 1: Descubrimiento e Investigación

  1. Pregunta al usuario sobre su nicho, negocio y objetivos
  2. Pregunta si necesita una base de datos (para formularios de contacto, leads, reservas, etc.)
  3. Investiga el nicho — qué está posicionando, qué palabras clave importan, qué brechas de contenido existen
  4. Propón una estructura del sitio con lista de páginas, estrategia de contenido y palabras clave objetivo
  5. Obtén la aprobación del usuario antes de construir

Fase 2: Configuración del Proyecto

  1. Crea el proyecto Astro
  2. Instala y configura integraciones (React, Tailwind, sitemap)
  3. Configura el layout base, componentes SEO y sistema de diseño

Fase 3: Construir Cada Página

  1. Lee references/taste-skill.md para las reglas de diseño
  2. Si el usuario quiere imágenes generadas, lee references/image-generation.md y genera imágenes para cada página
  3. Crea cada página con contenido real investigado
  4. SEO completo en cada página — meta tags, OG tags, datos estructurados, HTML semántico
  5. Conecta componentes interactivos (formularios, navegación, etc.)

Fase 4: Colecciones de Contenido y Base de Datos

  1. Configura las colecciones de contenido de Astro para entradas de blog, servicios, etc.
  2. Si se solicita base de datos: configura Turso, crea esquemas, construye rutas API
  3. Construye un panel de administración para datos de la base de datos si corresponde

Fase 5: Preparación para el Despliegue

  1. Genera sitemap, robots.txt
  2. Configura el despliegue (Vercel/Netlify)
  3. Auditoría SEO final de cada página

Fase 1: Descubrimiento e Investigación

Pregunta al Usuario

Antes de escribir cualquier código, entiende el proyecto:

  1. ¿Cuál es tu nicho/negocio? — "Soy fontanero en Dublín" o "Vendo velas artesanales en línea"
  2. ¿Cuál es el objetivo principal del sitio? — Generación de leads, e-commerce, portafolio, blog, landing page SaaS
  3. ¿Cuántas páginas deseas? — Pequeño (5-10 páginas) o con mucho contenido (15-30+ páginas con blog)
  4. ¿Necesitas una base de datos? — Para almacenar envíos de formularios, reservas, datos de usuario, etc. Si es sí, configura Turso.
  5. ¿Quieres imágenes generadas? — "Puedo generar imágenes de stock personalizadas para tu sitio usando Gemini. Si lo deseas, añade tu GEMINI_API_KEY al archivo .env."
  6. ¿Tienes un dominio? — Necesario para URLs canónicas/sitemap. Usa un marcador de posición si aún no se ha comprado.
  7. ¿Alguna preferencia de diseño? — Colores, estilo, marca existente

Investiga el Nicho

Usa la búsqueda web para encontrar:

  • Lo que está posicionando para las palabras clave objetivo — los 5-10 resultados principales
  • Brechas de contenido — qué preguntas no se responden bien
  • Palabras clave de cola larga — frases específicas con menos competencia
  • Señales SEO locales si es un negocio local
  • Estructuras de sitios de la competencia — qué páginas tienen, qué les falta

Propón la Estructura del Sitio

Basado en la investigación, crea una propuesta concreta. Ejemplo para un fontanero:

Páginas Propuestas:
1. Inicio — "Fontanero Dublín | Servicios de Fontanería de Emergencia 24/7"
2. Servicios — Resumen de todos los servicios
3. Servicios/Fontaneria-Emergencia — Página de aterrizaje dirigida
4. Servicios/Reformas-Banos — Página de aterrizaje dirigida
5. Servicios/Reparacion-Calderas — Página de aterrizaje dirigida
6. Sobre Nosotros — Señales de confianza, equipo, cualificaciones
7. Blog — Contenido continuo para SEO
8. Blog/[slug] — Entradas individuales dirigidas a palabras clave de cola larga
9. Contacto — Formulario + mapa + teléfono
10. Zonas donde trabajamos — Páginas SEO locales
11. Testimonios — Prueba social

Palabras Clave Objetivo: fontanero emergencia dublin, fontanero cerca de mi dublin, reparacion calderas dublin...
Estrategia de Contenido: Entradas de blog semanales dirigidas a consultas "cómo arreglar [problema común]"

Obtén la aprobación del usuario antes de proceder.


Fase 2: Configuración del Proyecto

Lee references/astro-setup.md para comandos y configuración exactos.

1. Crear el Proyecto

npm create astro@latest [nombre-proyecto] -- --template minimal --install --no-git
cd [nombre-proyecto]

2. Instalar Integraciones

npx astro add react tailwind sitemap
npm install @astrojs/check typescript
npm install @fontsource/geist-sans @fontsource/geist-mono  # Fuentes premium según taste-skill

3. Si se Solicita Base de Datos

Lee references/turso-setup.md para la configuración completa de Turso.

npm install @libsql/client drizzle-orm

4. Estructura del Proyecto

src/
├── components/
│   ├── SEOHead.astro
│   ├── Header.astro
│   ├── Footer.astro
│   ├── Navigation.tsx    # Isla React
│   └── ContactForm.tsx   # Isla React
├── content.config.ts     # Esquemas de colecciones de contenido (NO en content/)
├── content/
│   ├── blog/
│   ├── services/
│   └── testimonials/
├── layouts/
│   └── BaseLayout.astro
├── lib/
│   ├── turso.ts          # Si hay base de datos
│   └── utils.ts
├── pages/
│   ├── index.astro
│   ├── about.astro
│   ├── contact.astro
│   ├── blog/
│   │   ├── index.astro
│   │   └── [...slug].astro
│   └── api/              # Rutas API (si hay base de datos)
├── styles/
│   └── globals.css
└── middleware.ts
astro.config.mjs

Fase 3: Construir Cada Página — Diseño + SEO

Antes de escribir cualquier página, lee ambos:

  • references/seo-checklist.md — Reglas SEO para cada página
  • references/taste-skill.md — Reglas de diseño para evitar salida genérica

El Componente SEOHead

Crea src/components/SEOHead.astro — va en <head> de cada página. Maneja:

  • Etiqueta title (única por página, palabra clave principal, menos de 60 caracteres)
  • Meta descripción (única, CTA, menos de 160 caracteres)
  • URL canónica
  • Etiquetas Open Graph
  • Etiquetas Twitter Card
  • Datos estructurados JSON-LD

Consulta references/seo-checklist.md para el código exacto del componente.

Reglas de Redacción de Contenido

  • Escribe para humanos primero, para motores de búsqueda después.
  • Cada página se dirige a un clúster de palabras clave específico. Palabra clave principal en título, H1, primer párrafo, meta descripción, slug de URL.
  • Jerarquía de encabezados adecuada. Un H1. H2 para secciones. H3 para subsecciones. Nunca omitas niveles.
  • Enlaces internos. Cada página enlaza a 2-3+ otras páginas. Texto de anclaje descriptivo.
  • Texto alternativo de imágenes. Cada imagen recibe texto alternativo descriptivo con palabras clave naturales.
  • Extensión del contenido. Páginas de servicio: 800-1500 palabras. Entradas de blog: 1500-3000 palabras. Inicio: 500-1000 palabras.
  • Marcado Schema. Cada página recibe JSON-LD apropiado.

Reglas de Diseño (según taste-skill)

Estas son innegociables para cada página que construyas:

  • Tipografía: Usa Geist, Satoshi, Outfit o Cabinet Grotesk. NUNCA Inter. Titulares: text-4xl md:text-6xl tracking-tighter leading-none.
  • Colores: Máximo 1 color de acento, saturación < 80%. Sin degradados morados/azules de IA. Bases neutras (Zinc/Slate).
  • Diseño: Sin hero centrado cuando DESIGN_VARIANCE > 4. Usa diseños de pantalla dividida, asimétricos o alineados a la izquierda.
  • Tarjetas: Solo cuando la elevación comunique jerarquía. Sin diseños genéricos de tarjetas de 3 columnas.
  • Espaciado: min-h-[100dvh] no h-screen. Grid no matemáticas de flexbox. max-w-7xl mx-auto.
  • Estados: Cada componente interactivo necesita estados de carga, vacío y error.
  • Sin basura de IA: Sin emojis, sin "John Doe", sin "Acme Corp", sin palabras de relleno como "sin fisuras" o "desata".

Islas Astro para Interactividad

  • Contenido estático (encabezados, texto, imágenes) — componentes .astro, cero JS
  • Elementos interactivos (formularios, navegación móvil, animaciones de desplazamiento) — React .tsx con client:visible o client:load
  • Animaciones: Para movimiento (MOTION_INTENSITY > 5), usa Framer Motion en islas React aisladas. Física de resorte: type: "spring", stiffness: 100, damping: 20.

Lee references/tailwind-components.md para patrones de componentes (nav, formularios, FAQ, etc.)


Fase 4: Colecciones de Contenido y Base de Datos

Colecciones de Contenido de Astro

Lee references/content-collections.md para la configuración completa. Las colecciones de contenido reemplazan un CMS — el contenido vive como archivos Markdown en src/content/ con esquemas con tipado seguro.

IMPORTANTE: Define esquemas en src/content.config.ts (NO en src/content/config.ts — la ruta antigua lanza LegacyContentConfigError en Astro v5+). Cada colección debe tener un loader (usa glob() de astro/loaders).

Define esquemas en src/content.config.ts:

  • Entradas de blog: title, description, pubDate, image, tags, author, draft
  • Servicios: title, description, icon, order, featured
  • Testimonios: name, role, quote, rating

Consulta colecciones en páginas con getCollection() y getEntry().

Base de Datos Turso (Si se Solicita)

Lee references/turso-setup.md para la configuración completa. Turso maneja datos dinámicos — envíos de formularios, leads, reservas, suscripciones a newsletters.

  1. Crea el cliente de base de datos en src/lib/turso.ts
  2. Define esquemas con Drizzle ORM
  3. Crea rutas API en src/pages/api/ para el manejo de formularios
  4. Construye un panel de administración para ver los datos enviados

Panel de Administración (Si Hay Base de Datos)

Construye en /admin usando islas React con tablas y tarjetas estilizadas con Tailwind. Usa:

  • Middleware para autenticación básica
  • Rutas API para obtener datos de Turso
  • Presentación de datos limpia y de buen gusto (según reglas de taste-skill — sin cuadrículas genéricas de tarjetas)

Fase 5: Preparación para el Despliegue

Sitemap y Robots.txt

@astrojs/sitemap genera automáticamente el sitemap. Configura site en astro.config.mjs.

robots.txt dinámico en src/pages/robots.txt.ts:

import type { APIRoute } from 'astro';

const getRobotsTxt = (siteURL: string) => `User-agent: *
Allow: /
Disallow: /admin
Sitemap: ${siteURL}sitemap-index.xml`;

export const GET: APIRoute = ({ site }) => {
  return new Response(getRobotsTxt(site?.toString() || ''));
};

Configuración de Despliegue

Lee references/deployment.md para configuraciones de Vercel/Netlify.

Para sitios con rutas API o Turso, añade un adaptador pero mantén la salida estática predeterminada. Marca las rutas de servidor individuales con export const prerender = false;:

import vercel from '@astrojs/vercel';

export default defineConfig({
  // NO uses output: 'hybrid' — eliminado en Astro v5.
  // El valor predeterminado es 'static'. Las rutas renderizadas en servidor optan por no prerenderizar de forma individual.
  adapter: vercel(),
});

En cada ruta API o página renderizada en servidor:

// src/pages/api/contact.ts
export const prerender = false; // Esta ruta se ejecuta en el servidor

export const POST: APIRoute = async ({ request }) => {
  // ...
};

Auditoría SEO Final

Audita cada página contra references/seo-checklist.md:

  • Título, descripción, URL canónica únicos por página
  • Todas las imágenes tienen texto alternativo
  • JSON-LD valida
  • Los enlaces internos funcionan
  • Adaptable a móviles (prueba las reglas de anulación móvil de taste-skill)
  • El sitemap incluye todas las páginas
  • robots.txt correcto

Notas Importantes

  • NO uses output: 'hybrid' — fue eliminado en Astro v5. Usa la salida predeterminada 'static'. Para rutas renderizadas en servidor (endpoints API, manejadores de formularios), añade export const prerender = false; en cada archivo.
  • Las islas React necesitan directivas de hidratación — client:load o client:visible.
  • Las colecciones de contenido son basadas en archivos. Las entradas de blog y servicios viven como archivos .md en src/content/. Turso es solo para datos dinámicos (envíos de formularios).
  • Investiga antes de construir. La fase de investigación del nicho determina la calidad del SEO.
  • El contenido real gana. Escribe contenido sustancial y útil. Sin lorem ipsum.
  • Diseño premium siempre. Sigue las reglas de taste-skill. Cada página debe verse como un encargo de agencia de 10k €, no como salida genérica de IA.
  • La generación de imágenes es opcional. Si el usuario proporciona una GEMINI_API_KEY, genera imágenes personalizadas según references/image-generation.md. Si no, usa divs de marcador de posición estilizados con texto alternativo adecuado.

Skills relacionados