diegosouzapw/awesome-omni-skills

Astro Web Framework

Visão Geral

Esta cópia de integração pública empacota plugins/antigravity-awesome-skills/skills/astro de https://github.com/sickn33/antigravity-awesome-skills no formato editorial nativo do Omni Skills sem ocultar sua origem.

Use-a quando o operador precisar que o fluxo de trabalho upstream, os arquivos de suporte e o contexto do repositório permaneçam intactos enquanto o validador público e o aprimorador privado continuam seu fluxo downstream normal.

Esta integração mantém os arquivos upstream copiados intactos e usa o bloco external_source em metadata.json mais ORIGIN.md como a âncora de proveniência para revisão.

Astro Web Framework

Seções da fonte importada que não foram mapeadas de forma limpa para os cabeçalhos públicos ainda são preservadas abaixo ou nos arquivos de suporte. Seções importadas notáveis: Como Funciona, Notas de Segurança e Segurança, Armadilhas Comuns, Limitações.

Quando Usar Esta Habilidade

Use esta seção como o filtro de ativação. Ela deve tornar o limite de ativação explícito antes do operador carregar arquivos, executar comandos ou abrir uma pull request.

• Use ao construir um blog, site de documentação, página de marketing ou portfólio
• Use quando o desempenho e as Core Web Vitals forem a prioridade máxima
• Use quando o projeto for pesado em conteúdo com arquivos Markdown ou MDX
• Use quando você quiser saída SSG (estática) com SSR opcional para rotas dinâmicas
• Use quando o usuário perguntar sobre arquivos .astro, Astro.props, coleções de conteúdo ou diretivas client:
• Use quando a solicitação corresponder claramente à intenção da fonte importada: Construir sites focados em conteúdo com Astro — zero JS por padrão, arquitetura de ilhas, componentes multi-framework e suporte a Markdown/MDX.

Tabela Operacional

Situação	Comece aqui	Por que é importante
Primeiro uso	metadata.json	Confirma repositório, branch, commit e caminho importado através do bloco external_source antes de tocar no fluxo de trabalho copiado
Revisão de proveniência	ORIGIN.md	Fornece aos revisores uma trilha de auditoria em linguagem simples para a fonte importada
Execução do fluxo de trabalho	SKILL.md	Começa com o menor arquivo copiado que altera materialmente a execução
Contexto de suporte	SKILL.md	Adiciona o próximo arquivo de origem copiado mais relevante sem carregar todo o pacote
Decisão de entrega	## Habilidades Relacionadas	Ajuda o operador a mudar para uma habilidade nativa mais forte quando a tarefa se desvia

Fluxo de Trabalho

Este fluxo de trabalho é intencionalmente editorial e operacional ao mesmo tempo. Ele mantém a fonte importada útil para o operador enquanto ainda atende aos padrões públicos de integração que alimentam o fluxo do aprimorador downstream.

1. Confirme o objetivo do usuário, o escopo do fluxo de trabalho importado e se esta habilidade ainda é o roteador certo para a tarefa.
2. Leia os arquivos de visão geral e proveniência antes de carregar qualquer arquivo de suporte upstream copiado.
3. Carregue apenas as referências, exemplos, prompts ou scripts que alteram materialmente o resultado para a solicitação atual.
4. Execute o fluxo de trabalho upstream mantendo a proveniência e os limites da fonte explícitos nas notas de trabalho.
5. Valide o resultado contra as expectativas upstream e a evidência que você pode apontar nos arquivos copiados.
6. Escalone ou entregue a uma habilidade relacionada quando o trabalho sair do centro de gravidade deste fluxo de trabalho importado.
7. Antes da mesclagem ou fechamento, registre o que foi usado, o que mudou e o que o revisor ainda precisa verificar.

Notas do Fluxo de Trabalho Importado

Importado: Visão Geral

Astro é um framework web projetado para sites ricos em conteúdo — blogs, documentações, portfólios, sites de marketing e e-commerce. Sua inovação central é a Arquitetura de Ilhas: por padrão, Astro envia zero JavaScript para o navegador. Componentes interativos são hidratados seletivamente como "ilhas" isoladas. Astro suporta React, Vue, Svelte, Solid e outros frameworks de UI simultaneamente no mesmo projeto, permitindo que você escolha a ferramenta certa para cada componente.

Importado: Como Funciona

Passo 1: Configuração do Projeto

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

Adicione integrações conforme necessário:

npx astro add tailwind        # Tailwind CSS
npx astro add react           # Suporte a componentes React
npx astro add mdx             # Suporte a MDX
npx astro add sitemap         # Auto sitemap.xml
npx astro add vercel          # Adaptador SSR Vercel

Estrutura do projeto:

src/
  pages/          ← Roteamento baseado em arquivos (.astro, .md, .mdx)
  layouts/        ← Estruturas de página reutilizáveis
  components/     ← Componentes de UI (.astro, .tsx, .vue, etc.)
  content/        ← Coleções de conteúdo type-safe (Markdown/MDX)
  styles/         ← CSS global
public/           ← Ativos estáticos (copiados como estão)
astro.config.mjs  ← Configuração do framework

Passo 2: Sintaxe de Componentes Astro

Arquivos .astro têm um fence de código no topo (apenas servidor) e um template abaixo:

---
// src/components/Card.astro
// Este bloco executa APENAS no servidor — nunca no 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>
  /* Escopado automaticamente para este componente */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>

Passo 3: Páginas e Roteamento Baseado em Arquivos

src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dinâmico)
src/pages/blog/[...path].astro → /blog/* (captura-tudo)

Rota dinâmica com 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 />

Passo 4: Coleções de Conteúdo

Coleções de conteúdo fornecem acesso type-safe a arquivos Markdown e 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>

Passo 5: Ilhas — Hidratação Seletiva

Por padrão, componentes de frameworks de UI renderizam para HTML estático sem JS. Use diretivas client: para hidratar:

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

<!-- HTML estático — nenhum JavaScript enviado ao navegador -->
<Counter initialCount={0} />

<!-- Hidrata imediatamente ao carregar a página -->
<Counter initialCount={0} client:load />

<!-- Hidrata quando o componente entra na viewport -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hidrata apenas quando o navegador está ocioso -->
<Analytics client:idle />

<!-- Hidrata apenas em uma media query específica -->
<MobileMenu client:media="(max-width: 768px)" />

Passo 6: Layouts

---
// 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 />  <!-- conteúdo da página renderiza aqui -->
    </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>

Passo 7: Modo SSR (Renderização Sob Demanda)

Ative SSR para páginas dinâmicas definindo um 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(),
});

Opte por páginas individuais no SSR com export const prerender = false.

Exemplos

Exemplo 1: Solicitar o fluxo de trabalho upstream diretamente

Use @astro-v2 para lidar com <tarefa>. Comece do fluxo de trabalho upstream copiado, carregue apenas os arquivos que alteram o resultado e mantenha a proveniência visível na resposta.

Explicação: Este é o ponto de partida mais seguro quando o operador precisa do fluxo de trabalho importado, mas não do repositório inteiro.

Exemplo 2: Solicitar uma revisão fundamentada em proveniência

Revise @astro-v2 em relação a metadata.json e ORIGIN.md, depois explique quais arquivos upstream copiados você carregaria primeiro e por quê.

Explicação: Use antes de revisão ou solução de problemas quando você precisar de uma explicação precisa e auditável da origem e seleção de arquivos.

Exemplo 3: Restringir os arquivos de suporte copiados antes da execução

Use @astro-v2 para <tarefa>. Carregue apenas as referências, exemplos ou scripts copiados que alteram o resultado e nomeie os arquivos explicitamente antes de prosseguir.

Explicação: Isso mantém a habilidade alinhada com a divulgação progressiva em vez de carregar todo o pacote copiado por padrão.

Exemplo 4: Construir um pacote para revisor

Revise @astro-v2 usando os arquivos upstream copiados mais a proveniência, depois resuma quaisquer lacunas antes da mesclagem.

Explicação: Isso é útil quando o PR está aguardando revisão humana e você deseja um pacote de auditoria repetível.

Notas de Uso Importadas

Importado: Exemplos

Exemplo 1: Blog com 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}/`,
    })),
  });
}

Exemplo 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 required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

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

Exemplo 3: Componente React como Ilha

// 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">Search</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}

---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- Hidratado imediatamente — esta ilha é interativa -->
<SearchBox client:load />

Melhores Práticas

Trate a habilidade pública gerada como uma camada de empacotamento revisável ao redor do repositório upstream. O objetivo é manter a proveniência explícita e carregar apenas o material de origem copiado que melhora materialmente a execução.

• ✅ Mantenha a maioria dos componentes como arquivos .astro estáticos — hidrate apenas o que deve ser interativo
• ✅ Use coleções de conteúdo para todo conteúdo Markdown/MDX — você obtém type safety e validação automática
• ✅ Prefira client:visible em vez de client:load para componentes abaixo da dobra para reduzir JS inicial
• ✅ Use import.meta.env para variáveis de ambiente — prefixe vars públicas com PUBLIC_
• ✅ Adicione de astro:transitions para navegação suave entre páginas sem um SPA completo
• ❌ Não use client:load em todos os componentes — isso anula a vantagem de desempenho do Astro
• ❌ Não coloque segredos no frontmatter .astro que são usados em templates voltados ao cliente

Notas Operacionais Importadas

Importado: Melhores Práticas

• ✅ Mantenha a maioria dos componentes como arquivos .astro estáticos — hidrate apenas o que deve ser interativo
• ✅ Use coleções de conteúdo para todo conteúdo Markdown/MDX — você obtém type safety e validação automática
• ✅ Prefira client:visible em vez de client:load para componentes abaixo da dobra para reduzir JS inicial
• ✅ Use import.meta.env para variáveis de ambiente — prefixe vars públicas com PUBLIC_
• ✅ Adicione <ViewTransitions /> de astro:transitions para navegação suave entre páginas sem um SPA completo
• ❌ Não use client:load em todos os componentes — isso anula a vantagem de desempenho do Astro
• ❌ Não coloque segredos no frontmatter .astro que são usados em templates voltados ao cliente
• ❌ Não pule getStaticPaths para rotas dinâmicas em modo estático — as builds falharão

Solução de Problemas

Problema: O operador pulou o contexto importado e respondeu de forma muito genérica

Sintomas: O resultado ignora o fluxo de trabalho upstream em plugins/antigravity-awesome-skills/skills/astro, falha em mencionar proveniência ou não usa nenhum arquivo de origem copiado. Solução: Reabra metadata.json, ORIGIN.md e os arquivos upstream copiados mais relevantes. Verifique o bloco external_source primeiro, depois reafirme a proveniência antes de continuar.

Problema: O fluxo de trabalho importado parece incompleto durante a revisão

…

[truncado para tradução]