Communitygithub.com

ASoudy/AGS

Construye sitios web centrados en contenido con Astro — cero JS por defecto, arquitectura de islas, componentes multi-framework y soporte para Markdown/MDX.

¿Qué es AGS?

Esta habilidad te permite construir sitios web ricos en contenido (blogs, documentación, portafolios, sitios de marketing y e-commerce) utilizando Astro, un framework moderno para la web. La innovación central de Astro es su **Arquitectura de Islas**: por defecto, no se envía nada de JavaScript al navegador; los componentes interactivos se hidratan de forma selectiva como "islas" aisladas. Soporta múltiples frameworks de UI (React, Vue, Svelte, Solid, etc.) en el mismo proyecto, permitiéndote elegir la herramienta adecuada para cada componente. La habilidad cubre desde la configuración inicial del proyecto, la sintaxis de componentes `.astro`, el enrutamiento basado en archivos, las colecciones de contenido tipadas (Markdown/MDX), la hidratación selectiva con directivas `client:`, layouts reutilizables, y el modo SSR opcional. Es ideal para proyectos donde el rendimiento y las Core Web Vitals son la máxima prioridad, y donde gran parte del contenido se gestiona en archivos Markdown o MDX.

Compatible con✓Claude Code~Codex CLI✓Cursor✓Gemini CLI
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/AGAS/plugins/antigravity-awesome-skills-claude/skills/astro

Preguntar en tu IA favorita

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

Documentación

Framework Web Astro

Resumen General

Astro es un framework web diseñado para sitios web con mucho contenido — blogs, documentación, portafolios, sitios de marketing y comercio electrónico. Su innovación principal es la Arquitectura de Islas: por defecto, Astro envía cero JavaScript al navegador. Los componentes interactivos se hidratan de forma selectiva como "islas" aisladas. Astro admite React, Vue, Svelte, Solid y otros frameworks de UI simultáneamente en el mismo proyecto, permitiéndote elegir la herramienta adecuada para cada componente.

Cuándo Usar Esta Habilidad

  • Úsala al construir un blog, sitio de documentación, página de marketing o portafolio
  • Úsala cuando el rendimiento y las Core Web Vitals sean la máxima prioridad
  • Úsala cuando el proyecto tenga mucho contenido con archivos Markdown o MDX
  • Úsala cuando quieras salida SSG (estática) con SSR opcional para rutas dinámicas
  • Úsala cuando el usuario pregunte sobre archivos .astro, Astro.props, colecciones de contenido o directivas client:

Cómo Funciona

Paso 1: Configuración del Proyecto

npm create astro@latest mi-sitio
cd mi-sitio
npm install
npm run dev

Agrega integraciones según sea necesario:

npx astro add tailwind        # Tailwind CSS
npx astro add react           # Soporte de componentes React
npx astro add mdx             # Soporte MDX
npx astro add sitemap         # sitemap.xml automático
npx astro add vercel          # Adaptador SSR para Vercel

Estructura del proyecto:

src/
  pages/          ← Enrutamiento basado en archivos (.astro, .md, .mdx)
  layouts/        ← Plantillas de página reutilizables
  components/     ← Componentes de UI (.astro, .tsx, .vue, etc.)
  content/        ← Colecciones de contenido con tipado seguro (Markdown/MDX)
  styles/         ← CSS global
public/           ← Archivos estáticos (se copian tal cual)
astro.config.mjs ← Configuración del framework

Paso 2: Sintaxis de Componentes Astro

Los archivos .astro tienen un bloque de código al inicio (solo servidor) y una plantilla debajo:

---
// src/components/Card.astro
// Este bloque se ejecuta SOLO en el servidor — nunca en el navegador
interface Props {
  title: string;
  href: string;
  description: string;
}

const { title, href, description } = Astro.props;
---

<article class="card">
  <h2><a href={href}>{title}</a></h2>
  <p>{description}</p>
</article>

<style>
  /* Con ámbito automático para este componente */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

Paso 3: Páginas y Enrutamiento Basado en Archivos

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dinámica)
src/pages/blog/[...path].astro → /blog/* (comodín)

Ruta dinámica con getStaticPaths:

---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<h1>{post.data.title}</h1>
<Content />

Paso 4: Colecciones de Contenido

Las colecciones de contenido te dan acceso con tipado seguro a archivos Markdown y MDX:

// src/content/config.ts
import { z, defineCollection } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content';

const posts = (await getCollection('blog'))
  .filter(p => !p.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---

<ul>
  {posts.map(post => (
    <li>
      <a href={`/blog/${post.slug}`}>{post.data.title}</a>
      <time>{post.data.date.toLocaleDateString()}</time>
    </li>
  ))}
</ul>

Paso 5: Islas — Hidratación Selectiva

Por defecto, los componentes de frameworks de UI se renderizan como HTML estático sin JavaScript. Usa directivas client: para hidratar:

---
import Counter from '../components/Counter.tsx';  // Componente React
import VideoPlayer from '../components/VideoPlayer.svelte';
---

<!-- HTML estático — no se envía JavaScript al navegador -->
<Counter initialCount={0} />

<!-- Hidratar inmediatamente al cargar la página -->
<Counter initialCount={0} client:load />

<!-- Hidratar cuando el componente aparezca en la pantalla -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hidratar solo cuando el navegador esté inactivo -->
<Analytics client:idle />

<!-- Hidratar solo en una consulta de medios específica -->
<MobileMenu client:media="(max-width: 768px)" />

Paso 6: Layouts (Plantillas)

---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}
const { title, description = 'Mi Sitio Astro' } = Astro.props;
---

<html lang="es">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <nav>...</nav>
    <main>
      <slot />  <!-- el contenido de la página se renderiza aquí -->
    </main>
    <footer>...</footer>
  </body>
</html>
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="Acerca de Nosotros">
  <h1>Acerca de Nosotros</h1>
  <p>Bienvenido a nuestra empresa...</p>
</BaseLayout>

Paso 7: Modo SSR (Renderizado Bajo Demanda)

Habilita SSR para páginas dinámicas configurando un adaptador:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',  // 'static' | 'server' | 'hybrid'
  adapter: vercel(),
});

Incluye páginas individuales en SSR con export const prerender = false.

Ejemplos

Ejemplo 1: Blog con Feed RSS

// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'Mi Blog',
    description: 'Últimos artículos',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}

Ejemplo 2: Endpoint de API (SSR)

// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const { email } = await request.json();

  if (!email) {
    return new Response(JSON.stringify({ error: 'Email requerido' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  await addToNewsletter(email);
  return new Response(JSON.stringify({ success: true }), { status: 200 });
};

Ejemplo 3: Componente React como Isla

// src/components/SearchBox.tsx
import { useState } from 'react';

export default function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  async function search(e: React.FormEvent) {
    e.preventDefault();
    const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
    setResults(data);
  }

  return (
    <form onSubmit={search}>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <button type="submit">Buscar</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- Hidratado inmediatamente — esta isla es interactiva -->
<SearchBox client:load />

Mejores Prácticas

  • ✅ Mantén la mayoría de los componentes como archivos .astro estáticos — solo hidrata lo que debe ser interactivo
  • ✅ Usa colecciones de contenido para todo el contenido Markdown/MDX — obtienes tipado seguro y validación automática
  • ✅ Prefiere client:visible sobre client:load para componentes que están debajo del pliegue, para reducir el JS inicial
  • ✅ Usa import.meta.env para variables de entorno — antepone PUBLIC_ a las variables públicas
  • ✅ Agrega <ViewTransitions /> desde astro:transitions para una navegación suave entre páginas sin una SPA completa
  • ❌ No uses client:load en todos los componentes — esto anula la ventaja de rendimiento de Astro
  • ❌ No pongas secretos en el frontmatter de .astro que se use en plantillas orientadas al cliente
  • ❌ No omitas getStaticPaths para rutas dinámicas en modo estático — las compilaciones fallarán

Notas de Seguridad

  • El código en el frontmatter de los archivos .astro se ejecuta solo en el lado del servidor y nunca se expone al navegador.
  • Usa import.meta.env.PUBLIC_* solo para valores no sensibles. Las variables de entorno privadas (sin el prefijo PUBLIC_) nunca se envían al cliente.
  • Al usar el modo SSR, valida todas las entradas de Astro.request antes de las consultas a la base de datos o llamadas a la API.
  • Desinfecta cualquier contenido proporcionado por el usuario antes de renderizar con set:html — esto evita el escape automático.

Errores Comunes

  • Problema: El JavaScript de un componente React/Vue no se ejecuta en el navegador Solución: Agrega una directiva client: (client:load, client:visible, etc.) — sin ella, los componentes se renderizan solo como HTML estático.

  • Problema: Los datos de getStaticPaths quedan obsoletos después de actualizar contenido durante el desarrollo Solución: El servidor de desarrollo de Astro observa los archivos de contenido — reinicia si los cambios en content/config.ts no se reflejan.

  • Problema: El tipo de Astro.props es any — sin autocompletado Solución: Define una interfaz Props o tipo en el frontmatter y Astro lo inferirá automáticamente.

  • Problema: El CSS de un componente .astro se filtra a otros componentes Solución: Los estilos en las etiquetas <style> de .astro tienen ámbito automático. Usa :global() solo cuando tengas la intención de apuntar a los hijos.

Habilidades Relacionadas

  • @sveltekit — Cuando necesitas un framework full-stack con UI reactiva (en lugar del enfoque de contenido de Astro)
  • @nextjs-app-router-patterns — Cuando necesitas un framework full-stack centrado en React
  • @tailwind-patterns — Dar estilo a sitios Astro con Tailwind CSS
  • @progressive-web-app — Agregar capacidades PWA a un sitio Astro

Limitaciones

  • Usa esta habilidad solo cuando la tarea coincida claramente con el alcance descrito anteriormente.
  • No trates la salida como un sustituto de la validación específica del entorno, pruebas o revisión de expertos.
  • Detente y pide aclaración si faltan entradas requeridas, permisos, límites de seguridad o criterios de éxito.

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Three.js animation - keyframe animation, skeletal animation, morph targets, animation mixing. Use when animating objects, playing GLTF animations, creating procedural motion, or blending animations.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Skills relacionados