Communitygithub.com

GanderBite/relay

Habilidad integral para crear sitios web con Astro.build. Úsala cuando el usuario quiera crear un sitio web con Astro, necesite seleccionar un tema apropiado de la colección de temas gratuitos de Astro, requiera acceso a la documentación de Astro o desee desarrollar componentes y páginas de Astro. Esta habilidad maneja la selección de temas, el acceso a la documentación, la configuración del proyecto y los patrones de desarrollo específicos de Astro.

¿Qué es relay?

Esta habilidad, diseñada para asistentes de IA como Claude Code, Cursor o Codex, proporciona una guía completa para construir sitios web con Astro.build. Es particularmente útil para desarrolladores que buscan crear blogs, sitios de documentación, portafolios, páginas de aterrizaje o sitios de comercio electrónico, facilitando la selección de temas gratuitos desde el repositorio oficial de Astro, el acceso a documentación actualizada y la implementación de patrones de desarrollo eficientes. La habilidad sigue un flujo de trabajo estructurado: comprender requisitos, seleccionar un tema apropiado, acceder a la documentación de Astro (tanto el resumen local como la documentación completa mediante web_fetch), inicializar el proyecto con el CLI de Astro, desarrollar componentes y páginas siguiendo la arquitectura de islas, y optimizar para rendimiento. Incluye ejemplos prácticos para blogs con React, portafolios y sitios de documentación con Starlight, y enfatiza buenas prácticas como mantener componentes estáticos por defecto, usar TypeScript para seguridad de tipos y optimizar imágenes con el componente Image de Astro. La habilidad también ofrece soluciones a problemas comunes y recursos adicionales como scripts de análisis de temas.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GanderBite/relay/tree/HEAD/.claude/skills/astro-builder

Preguntar en tu IA favorita

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

Documentación

Constructor de Sitios Web con Astro

Esta habilidad te ayuda a construir sitios web con Astro.build guiándote en la selección de temas, el acceso a la documentación y las mejores prácticas de desarrollo. Utiliza esta habilidad siempre que un usuario mencione construir con Astro, quiera crear un sitio web o necesite ayuda con funcionalidades específicas de Astro.

Cuándo Usar Esta Habilidad

Activa esta habilidad cuando:

  • El usuario mencione "Astro" o "astro.build" en su solicitud
  • El usuario quiera construir un sitio web y Astro sea apropiado (blogs, documentación, portafolios, sitios de marketing, etc.)
  • El usuario necesite seleccionar un tema para su proyecto Astro
  • El usuario necesite ayuda con componentes, enrutamiento o configuración de Astro
  • El usuario quiera integrar React, Vue u otros frameworks con Astro
  • El usuario necesite acceder a la documentación o mejores prácticas de Astro

Resumen del Flujo de Trabajo

Al construir un sitio web con Astro, sigue este proceso:

  1. Comprender los Requisitos - Determinar el tipo de sitio web y las funcionalidades necesarias
  2. Seleccionar el Tema Apropiado - Elegir de los temas gratuitos de Astro según los requisitos
  3. Acceder a la Documentación - Consultar la documentación de Astro para funcionalidades específicas
  4. Inicializar el Proyecto - Configurar la estructura del proyecto
  5. Desarrollar Componentes - Construir usando la arquitectura de componentes de Astro
  6. Optimizar e Implementar - Seguir las mejores prácticas de rendimiento

Paso 1: Comprender los Requisitos

Primero, identifica el tipo de sitio web y sus requisitos:

Tipos de Sitio Web:

  • Blog/Sitio de publicaciones
  • Portafolio/Vitrina
  • Sitio de documentación
  • Página de marketing/Landing page
  • Sitio de comercio electrónico
  • Sitio de empresa/negocio
  • Sitio personal

Preguntas Clave a Realizar:

  • ¿Cuál es el propósito principal del sitio?
  • ¿Qué tipos de contenido tendrá? (publicaciones de blog, proyectos, productos, etc.)
  • ¿Necesita interactividad? (formularios, búsqueda, contenido dinámico)
  • ¿Qué frameworks prefiere el usuario? (React, Vue, Svelte, etc.)
  • ¿Necesita funcionalidades específicas? (modo oscuro, i18n, integración con CMS)

Paso 2: Seleccionar el Tema Apropiado

Usa web_fetch para navegar por los temas gratuitos compatibles con React:

URL: https://astro.build/themes/1/?search=&technology%5B%5D=react&price%5B%5D=free

Criterios de Selección de Temas:

Para Blogs/Publicaciones:

  • Busca temas con tipografía sólida
  • Debe ser compatible con Markdown/MDX
  • Debe tener etiquetas/categorías
  • Compatibilidad con feed RSS
  • Considera: astro-paper, astro-blog-template

Para Portafolios:

  • Vitrina visual de proyectos
  • Secciones Acerca de/Contacto
  • Animaciones suaves
  • Considera: astro-portfolio, temas de portafolio personal

Para Documentación:

  • Usa Starlight (framework oficial de documentación de Astro)
  • Funcionalidades: Búsqueda, barra lateral de navegación, modo oscuro, i18n
  • Ideal para: Documentación técnica, referencias de API, guías

Para Páginas de Aterrizaje:

  • Sección Hero con llamado a la acción (CTA)
  • Secciones de funcionalidades/beneficios
  • Formularios de contacto
  • Optimizado para conversión

Para Comercio Electrónico:

  • Listados de productos y filtros
  • Funcionalidad de carrito de compras
  • Listo para integración de pagos
  • Páginas de detalle de producto

Acción: Obtén la página de temas, analiza los temas disponibles y recomienda 2-3 opciones que mejor se ajusten a los requisitos del usuario. Explica por qué cada tema es adecuado.

Paso 3: Acceder a la Documentación de Astro

Cuando necesites documentación específica de Astro, consulta:

  1. Referencia Incorporada: references/astro_docs.md - Contiene conceptos centrales de Astro, sintaxis y patrones comunes
  2. Documentación Completa: Obtén de https://docs.astro.build/llms-full.txt para información exhaustiva

Cuándo Consultar la Documentación:

  • Preguntas sobre sintaxis de componentes → Consulta astro_docs.md
  • Enrutamiento y páginas → Consulta astro_docs.md
  • Opciones de estilo → Consulta astro_docs.md
  • Funcionalidades avanzadas → Obtén de docs.astro.build
  • Configuración de integraciones → Obtén de docs.astro.build
  • Detalles de API → Obtén de docs.astro.build

Paso 4: Inicializar el Proyecto Astro

Usando el CLI Create Astro

# Crear nuevo proyecto
npm create astro@latest

# O con una plantilla específica
npm create astro@latest -- --template <theme-github-username>/<theme-repo>

Configuración de la Estructura del Proyecto

Después de la inicialización, asegura una estructura adecuada:

project/
├── src/
│   ├── components/     # Componentes reutilizables
│   ├── layouts/        # Diseños de página
│   ├── pages/          # Rutas (OBLIGATORIO)
│   │   └── index.astro # Página de inicio
│   ├── content/        # Colecciones de contenido (opcional)
│   └── assets/         # Imágenes optimizadas
├── public/             # Activos estáticos
├── astro.config.mjs    # Configuración
├── package.json
└── tsconfig.json

Importante: El directorio src/pages/ es OBLIGATORIO para que el enrutamiento funcione.

Paso 5: Desarrollar Componentes y Páginas

Patrón de Desarrollo de Componentes

  1. Crear archivo de componente en src/components/
  2. Definir interfaz de props (si usas TypeScript)
  3. Escribir script del componente (se ejecuta en tiempo de compilación)
  4. Crear plantilla (HTML con sintaxis de Astro)
  5. Agregar estilos con ámbito (opcional)

Ejemplo:

---
interface Props {
  title: string;
  description?: string;
}
const { title, description } = Astro.props;
---

<article>
  <h2>{title}</h2>
  {description && <p>{description}</p>}
</article>

<style>
  article {
    padding: 1rem;
    border: 1px solid #ccc;
  }
</style>

Patrón de Desarrollo de Páginas

  1. Crear archivo de página en src/pages/ (determina la ruta)
  2. Importar componentes y diseños necesarios
  3. Definir getStaticPaths() para rutas dinámicas
  4. Componer la página usando componentes

Ejemplo de página:

---
import Layout from '../layouts/Layout.astro';
import Hero from '../components/Hero.astro';

const title = "Mi Página";
---

<Layout title={title}>
  <Hero />
  <!-- Más contenido -->
</Layout>

Agregar Interactividad

Cuando necesites interactividad del lado del cliente:

  1. Instalar integración del framework: npx astro add react
  2. Crear componente del framework (.jsx, .vue, .svelte)
  3. Importar y usar con directiva cliente:
---
import ReactComponent from '../components/ReactComponent.jsx';
---

<!-- Estático (sin JS) -->
<ReactComponent />

<!-- Interactivo -->
<ReactComponent client:load />
<!-- Opciones: client:idle, client:visible, client:media -->

Paso 6: Consultar Documentación Según Sea Necesario

Antes de escribir código, lee las secciones relevantes de references/astro_docs.md:

  • Preguntas sobre componentes → Lee la sección "Sintaxis de Componentes"
  • Problemas de enrutamiento → Lee la sección "Enrutamiento"
  • Estilo → Lee la sección "Estilo"
  • Imágenes → Lee la sección "Imágenes y Activos"
  • Configuración → Lee la sección "Configuración"

Para temas avanzados, obtén la documentación completa:

web_fetch: https://docs.astro.build/llms-full.txt

Mejores Prácticas

Optimización del Rendimiento

  1. Mantén los componentes estáticos por defecto - Solo agrega client:* cuando sea realmente necesario
  2. Usa el componente Image de Astro - Optimización automática
  3. Aprovecha la arquitectura de islas - JavaScript mínimo por defecto
  4. División de código - Astro divide automáticamente por página

Flujo de Trabajo de Desarrollo

  1. Empieza con la estructura - Configura primero los diseños y las páginas básicas
  2. Impulsado por componentes - Construye componentes reutilizables
  3. Seguridad de tipos - Usa TypeScript para props y mejor experiencia de desarrollo
  4. Colecciones de contenido - Para gestión de contenido con verificación de tipos
  5. Prueba localmente - Ejecuta npm run dev con frecuencia

Patrones Comunes a Seguir

  • Usa diseños para una estructura de página consistente
  • Crea un componente SEO para metaetiquetas
  • Configura interfaces de TypeScript adecuadas
  • Implementa páginas de error apropiadas (404, 500)
  • Agrega texto alternativo adecuado a las imágenes
  • Usa HTML semántico

Solución de Problemas

Problemas Comunes

"Módulo no encontrado"

  • Asegúrate de que las rutas de importación sean correctas
  • Verifica que las integraciones estén instaladas
  • Revisa que astro.config.mjs tenga la configuración de integración correcta

"La página no se renderiza"

  • Verifica que el archivo esté en el directorio src/pages/
  • Revisa si hay errores de sintaxis en el frontmatter
  • Asegúrate de que la extensión del archivo sea correcta (.astro, .md, .mdx)

"Los estilos no se aplican"

  • Los estilos con ámbito solo se aplican al HTML propio del componente
  • Usa is:global para estilos globales
  • Revisa la configuración de Tailwind si usas Tailwind

"El componente no es interactivo"

  • Agrega la directiva client:* a los componentes del framework
  • Asegúrate de que la integración esté instalada (ej., @astrojs/react)
  • Revisa la consola del navegador en busca de errores de JavaScript

Recursos

Scripts

  • scripts/theme_analyzer.py - Ayuda a obtener y analizar temas de Astro desde la página oficial de temas. Úsalo para explorar opciones de temas de manera programática según filtros de tecnología y precio.

Referencias

  • references/astro_docs.md - LÉELO PRIMERO para conceptos centrales de Astro, sintaxis de componentes, enrutamiento, estilo y patrones comunes. Esta es tu referencia principal para el desarrollo con Astro.

Recursos Externos

Ejemplos de Flujos de Trabajo

Ejemplo 1: Construir un Blog

Usuario: "Quiero construir un blog con Astro y React"

Flujo de trabajo:

  1. Identificar requisitos: Sitio de blog, necesita compatibilidad con React, quiere un tema gratuito
  2. Obtener temas: web_fetch https://astro.build/themes/1/?technology%5B%5D=react&price%5B%5D=free
  3. Recomendar tema: Sugerir 2-3 temas orientados a blogs con explicaciones
  4. Leer references/astro_docs.md para consultar patrones de componentes
  5. Guiar la configuración: Proporcionar comandos de instalación y estructura
  6. Ayudar a construir: Crear diseño de entrada de blog, página de listado, páginas de entrada individual
  7. Agregar interactividad: Mostrar cómo agregar componentes de React con client:load para funcionalidades como comentarios

Ejemplo 2: Sitio de Portafolio

Usuario: "Crea un sitio de portafolio para mí usando https://astro.build/"

Flujo de trabajo:

  1. Aclarar requisitos: ¿Qué mostrar (proyectos, habilidades, experiencia)?
  2. Obtener temas de portafolio de la página de temas de Astro
  3. Recomendar la mejor opción según el campo del usuario (desarrollador, diseñador, etc.)
  4. Leer la sintaxis de componentes de references/astro_docs.md
  5. Configurar la estructura del proyecto con el tema seleccionado
  6. Crear/personalizar componentes (Hero, Cuadrícula de proyectos, Acerca de, Contacto)
  7. Agregar transiciones suaves si es necesario
  8. Optimizar imágenes usando el componente Image de Astro

Ejemplo 3: Sitio de Documentación

Usuario: "Necesito un sitio de documentación con búsqueda y modo oscuro"

Flujo de trabajo:

  1. Identificar: Sitio de documentación, necesita búsqueda y modo oscuro
  2. Recomendar Starlight (framework oficial de documentación de Astro)
  3. Mostrar configuración: npm create astro@latest -- --template starlight
  4. Consultar la documentación de Starlight desde la documentación completa de Astro
  5. Configurar la estructura de navegación de la barra lateral
  6. Configurar la estructura de contenido
  7. Habilitar modo oscuro (incorporado)
  8. Configurar búsqueda (incorporada con Pagefind)

Recordatorios Clave

  1. Lee SIEMPRE references/astro_docs.md PRIMERO antes de responder preguntas sobre componentes o sintaxis
  2. Obtén temas de la página de temas de Astro cuando el usuario necesite un punto de partida
  3. Usa web_fetch para la documentación completa cuando sea necesario
  4. Mantenlo simple - Astro está diseñado para ser directo; no compliques de más
  5. Arquitectura de islas - Recuerda que los componentes son estáticos por defecto
  6. Seguridad de tipos - Fomenta el uso de TypeScript para una mejor experiencia de desarrollo

Criterios de Éxito

Un proyecto Astro está configurado correctamente cuando:

  • ✅ La estructura del proyecto sigue las convenciones de Astro
  • ✅ El directorio src/pages/ existe con al menos un index.astro
  • ✅ Se seleccionó un tema apropiado según los requisitos
  • ✅ Los componentes siguen los patrones de sintaxis de Astro
  • ✅ La interactividad del lado del cliente solo se agrega donde es necesario
  • ✅ Se definieron interfaces de TypeScript para las props de los componentes
  • ✅ Las imágenes se optimizan usando el componente Image de Astro
  • ✅ El sitio se ejecuta correctamente con npm run dev

Skills relacionados