diegosouzapw/awesome-omni-skills

Astro Web Framework

Resumen

Esta copia de entrada pública empaqueta plugins/antigravity-awesome-skills/skills/astro de https://github.com/sickn33/antigravity-awesome-skills en la forma editorial nativa de Omni Skills sin ocultar su origen.

Úsala cuando el operador necesite que el flujo de trabajo upstream, los archivos de soporte y el contexto del repositorio permanezcan intactos mientras el validador público y el mejorador privado continúan su flujo normal downstream.

Esta entrada mantiene intactos los archivos upstream copiados y utiliza el bloque external_source en metadata.json junto con ORIGIN.md como ancla de procedencia para la revisión.

Astro Web Framework

Las secciones fuente importadas que no se asignaron limpiamente a los encabezados públicos se conservan a continuación o en los archivos de soporte. Secciones importadas notables: Cómo Funciona, Notas de Seguridad y Protección, Errores Comunes, Limitaciones.

Cuándo Usar Esta Habilidad

Usa esta sección como filtro de activación. Debe hacer explícito el límite de activación antes de que el operador cargue archivos, ejecute comandos o abra una solicitud de extracción.

• Úsala al construir un blog, sitio de documentación, página de marketing o portafolio
• Úsala cuando el rendimiento y las Métricas Web Esenciales 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:
• Úsala cuando la solicitud coincida claramente con la intención de la fuente importada: Construir sitios web enfocados en contenido con Astro — cero JS por defecto, arquitectura de islas, componentes multi-framework y soporte Markdown/MDX.

Tabla de Operación

Situación	Comienza aquí	Por qué es importante
Primer uso	metadata.json	Confirma el repositorio, rama, commit y ruta importada a través del bloque external_source antes de tocar el flujo de trabajo copiado
Revisión de procedencia	ORIGIN.md	Proporciona a los revisores un rastro de auditoría en lenguaje sencillo para la fuente importada
Ejecución del flujo de trabajo	SKILL.md	Comienza con el archivo copiado más pequeño que cambia materialmente la ejecución
Contexto de soporte	SKILL.md	Agrega el siguiente archivo fuente copiado más relevante sin cargar todo el paquete
Decisión de entrega	## Habilidades Relacionadas	Ayuda al operador a cambiar a una habilidad nativa más sólida cuando la tarea se desvía

Flujo de Trabajo

Este flujo de trabajo es intencionalmente editorial y operativo al mismo tiempo. Mantiene la fuente importada útil para el operador mientras aún satisface los estándares de entrada pública que alimentan el flujo downstream del mejorador.

1. Confirma el objetivo del usuario, el alcance del flujo de trabajo importado y si esta habilidad sigue siendo el enrutador adecuado para la tarea.
2. Lee los archivos de resumen y procedencia antes de cargar cualquier archivo de soporte upstream copiado.
3. Carga solo las referencias, ejemplos, indicaciones o scripts que cambian materialmente el resultado para la solicitud actual.
4. Ejecuta el flujo de trabajo upstream manteniendo explícitos los límites de procedencia y fuente en las notas de trabajo.
5. Valida el resultado contra las expectativas upstream y la evidencia a la que puedas señalar en los archivos copiados.
6. Escala o entrega a una habilidad relacionada cuando el trabajo salga del centro de gravedad de este flujo de trabajo importado.
7. Antes de fusionar o cerrar, registra qué se usó, qué cambió y qué necesita verificar el revisor.

Notas del Flujo de Trabajo Importado

Importado: Resumen

Astro es un framework web diseñado para sitios web ricos en contenido: blogs, documentación, portafolios, sitios de marketing y comercio electrónico. Su innovación central es la Arquitectura de Islas: por defecto, Astro envía cero JavaScript al navegador. Los componentes interactivos se hidratan selectivamente 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 por componente.

Importado: Cómo Funciona

Paso 1: Configuración del Proyecto

npm create astro@latest my-site
cd my-site
npm install
npm run dev

Agrega integraciones según sea necesario:

npx astro add tailwind        # Tailwind CSS
npx astro add react           # Soporte para componentes React
npx astro add mdx             # Soporte MDX
npx astro add sitemap         # Auto sitemap.xml
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/           ← Activos estáticos (se copian tal cual)
astro.config.mjs  ← Configuración del framework

Paso 2: Sintaxis de Componentes Astro

Los archivos .astro tienen una valla de código en la parte superior (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>
  /* Se aplica automáticamente a este componente */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

Paso 3: Páginas y Enrutamiento Basados en Archivos

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dinámico)
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 JS. 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} />

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

<!-- Hidrata cuando el componente se desplaza a la vista -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hidrata solo cuando el navegador está inactivo -->
<Analytics client:idle />

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

Paso 6: Diseños

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

<html lang="en">
  <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="About Us">
  <h1>About Us</h1>
  <p>Welcome to our company...</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(),
});

Opta páginas individuales a SSR con export const prerender = false.

Ejemplos

Ejemplo 1: Solicitar el flujo de trabajo upstream directamente

Usa @astro-v2 para manejar <tarea>. Comienza desde el flujo de trabajo upstream copiado, carga solo los archivos que cambian el resultado y mantén visible la procedencia en la respuesta.

Explicación: Este es el punto de partida más seguro cuando el operador necesita el flujo de trabajo importado, pero no todo el repositorio.

Ejemplo 2: Solicitar una revisión basada en procedencia

Revisa @astro-v2 contra metadata.json y ORIGIN.md, luego explica qué archivos upstream copiados cargarías primero y por qué.

Explicación: Usa esto antes de revisar o solucionar problemas cuando necesites una explicación precisa y auditable del origen y la selección de archivos.

Ejemplo 3: Reducir los archivos de soporte copiados antes de la ejecución

Usa @astro-v2 para <tarea>. Carga solo las referencias, ejemplos o scripts copiados que cambian el resultado, y nombra los archivos explícitamente antes de continuar.

Explicación: Esto mantiene la habilidad alineada con la divulgación progresiva en lugar de cargar todo el paquete copiado por defecto.

Ejemplo 4: Crear un paquete para el revisor

Revisa @astro-v2 usando los archivos upstream copiados más la procedencia, luego resume cualquier brecha antes de fusionar.

Explicación: Esto es útil cuando la solicitud de extracción está esperando revisión humana y deseas un paquete de auditoría repetible.

Notas de Uso Importadas

Importado: 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: 'My Blog',
    description: 'Latest posts',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}

Ejemplo 2: Endpoint 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';
---
<!-- Hidratada inmediatamente — esta isla es interactiva -->
<SearchBox client:load />

Mejores Prácticas

Trata la habilidad pública generada como una capa de empaquetado revisable alrededor del repositorio upstream. El objetivo es mantener la procedencia explícita y cargar solo el material fuente copiado que mejora materialmente la ejecución.

• ✅ 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 debajo del pliegue para reducir JS inicial
• ✅ Usa import.meta.env para variables de entorno — prefija las vars públicas con PUBLIC_
• ✅ Agrega de astro:transitions para una navegación fluida entre páginas sin un SPA completo
• ❌ No uses client:load en cada componente — esto anula la ventaja de rendimiento de Astro
• ❌ No pongas secretos en el frontmatter de .astro que se use en plantillas orientadas al cliente

Notas de Operación Importadas

Importado: 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 debajo del pliegue para reducir JS inicial
• ✅ Usa import.meta.env para variables de entorno — prefija las vars públicas con PUBLIC_
• ✅ Agrega <ViewTransitions /> de astro:transitions para una navegación fluida entre páginas sin un SPA completo
• ❌ No uses client:load en cada componente — 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

Solución de Problemas

Problema: El operador omitió el contexto importado y respondió de manera demasiado genérica

Síntomas: El resultado ignora el flujo de trabajo upstream en plugins/antigravity-awesome-skills/skills/astro, no menciona la procedencia, o no usa ningún archivo fuente copiado. Solución: Vuelve a abrir metadata.json, ORIGIN.md, y los archivos upstream copiados más relevantes. Verifica primero el bloque external_source, luego reitera la procedencia antes de continuar.

Problema: El flujo de trabajo importado se siente incompleto durante la revisión

…

[truncado para traducción]