Communitygithub.com

GanderBite/relay

Habilidade abrangente para construir sites com Astro.build. Use quando o usuário quiser criar um site usando Astro, precisar selecionar um tema apropriado da coleção de temas gratuitos do Astro, precisar de acesso à documentação do Astro ou quiser desenvolver componentes e páginas Astro. Esta habilidade gerencia seleção de temas, acesso à documentação, configuração de projeto e padrões de desenvolvimento específicos do Astro.

O que é relay?

Esta habilidade capacita agentes de IA a construir sites completos com o framework Astro, guiando desde a seleção de temas até a implantação. Ela automatiza a escolha de temas gratuitos no site oficial do Astro, fornece acesso à documentação (tanto um resumo local quanto a documentação completa via web_fetch), e orienta a criação de componentes e páginas seguindo as melhores práticas. Suporta plataformas como Claude Code, Cursor e Codex, e é ativada sempre que o usuário menciona 'Astro' ou deseja criar um site compatível com Astro. O fluxo de trabalho inclui entender requisitos, selecionar temas (blog, portfólio, documentação, e-commerce, etc.), inicializar projetos com `npm create astro@latest`, desenvolver componentes com TypeScript e adicionar interatividade com diretivas `client:*`. A habilidade enfatiza a arquitetura de ilhas (islands architecture), otimização de performance e uso de TypeScript.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Construtor de Sites Astro

Esta habilidade ajuda você a construir sites com Astro.build, guiando-o pela seleção de temas, acesso à documentação e melhores práticas de desenvolvimento. Use esta habilidade sempre que um usuário mencionar construir com Astro, quiser criar um site ou precisar de ajuda com recursos específicos do Astro.

Quando Usar Esta Habilidade

Ative esta habilidade quando:

  • O usuário mencionar "Astro" ou "astro.build" em sua solicitação
  • O usuário quiser construir um site e Astro for apropriado (blogs, documentação, portfólios, sites de marketing, etc.)
  • O usuário precisar selecionar um tema para seu projeto Astro
  • O usuário precisar de ajuda com componentes Astro, roteamento ou configuração
  • O usuário quiser integrar React, Vue ou outros frameworks com Astro
  • O usuário precisar de acesso à documentação ou às melhores práticas do Astro

Visão Geral do Fluxo de Trabalho

Ao construir um site Astro, siga este processo:

  1. Entender Requisitos - Determinar o tipo de site e os recursos necessários
  2. Selecionar Tema Apropriado - Escolher entre os temas gratuitos do Astro com base nos requisitos
  3. Acessar Documentação - Referenciar a documentação do Astro para recursos específicos
  4. Inicializar Projeto - Configurar a estrutura do projeto
  5. Desenvolver Componentes - Construir usando a arquitetura de componentes do Astro
  6. Otimizar e Implantar - Seguir as melhores práticas de performance

Etapa 1: Entender Requisitos

Primeiro, identifique o tipo de site e seus requisitos:

Tipos de Site:

  • Blog/Site de publicação
  • Portfólio/Vitrines
  • Site de documentação
  • Site de marketing/Landing page
  • Site de e-commerce
  • Site empresarial/Comercial
  • Site pessoal

Perguntas-chave a Fazer:

  • Qual é o propósito principal do site?
  • Que tipos de conteúdo ele terá? (postagens de blog, projetos, produtos, etc.)
  • Ele precisa de interatividade? (formulários, busca, conteúdo dinâmico)
  • Quais frameworks o usuário prefere? (React, Vue, Svelte, etc.)
  • Precisa de recursos específicos? (modo escuro, i18n, integração com CMS)

Etapa 2: Selecionar Tema Apropriado

Use web_fetch para navegar por temas gratuitos compatíveis com React:

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

Critérios de Seleção de Tema:

Para Blogs/Publicações:

  • Procure temas com tipografia forte
  • Deve suportar Markdown/MDX
  • Deve ter tags/categorias
  • Suporte a feed RSS
  • Considere: astro-paper, astro-blog-template

Para Portfólios:

  • Vitrine visual de projetos
  • Seções Sobre/Contato
  • Animações suaves
  • Considere: astro-portfolio, temas de portfólio pessoal

Para Documentação:

  • Use Starlight (framework oficial de documentação do Astro)
  • Recursos: Busca, navegação lateral, modo escuro, i18n
  • Melhor para: Documentação técnica, referências de API, guias

Para Landing Pages:

  • Seção de herói com CTA
  • Seções de Recursos/Benefícios
  • Formulários de contato
  • Otimizado para conversão

Para E-commerce:

  • Listagem de produtos e filtros
  • Funcionalidade de carrinho de compras
  • Pronto para integração de pagamento
  • Páginas de detalhes do produto

Ação: Busque a página de temas, analise os temas disponíveis e recomende 2-3 opções que melhor atendam aos requisitos do usuário. Explique por que cada tema é adequado.

Etapa 3: Acessar Documentação do Astro

Quando você precisar de documentação específica do Astro, consulte:

  1. Referência Interna: references/astro_docs.md - Contém conceitos principais do Astro, sintaxe e padrões comuns
  2. Documentação Completa: Buscar em https://docs.astro.build/llms-full.txt para informações abrangentes

Quando Consultar a Documentação:

  • Dúvidas sobre sintaxe de componentes → Consultar astro_docs.md
  • Roteamento e páginas → Consultar astro_docs.md
  • Opções de estilo → Consultar astro_docs.md
  • Recursos avançados → Buscar em docs.astro.build
  • Configuração de integrações → Buscar em docs.astro.build
  • Detalhes de API → Buscar em docs.astro.build

Etapa 4: Inicializar Projeto Astro

Usando o CLI Create Astro

# Criar novo projeto
npm create astro@latest

# Ou com um template específico
npm create astro@latest -- --template <tema-github-usuario>/<tema-repositorio>

Configuração da Estrutura do Projeto

Após a inicialização, garanta a estrutura adequada:

projeto/
├── src/
│   ├── components/     # Componentes reutilizáveis
│   ├── layouts/        # Layouts de página
│   ├── pages/          # Rotas (OBRIGATÓRIO)
│   │   └── index.astro # Página inicial
│   ├── content/        # Coleções de conteúdo (opcional)
│   └── assets/         # Imagens otimizadas
├── public/             # Ativos estáticos
├── astro.config.mjs    # Configuração
├── package.json
└── tsconfig.json

Crítico: O diretório src/pages/ é OBRIGATÓRIO para o funcionamento do roteamento.

Etapa 5: Desenvolver Componentes e Páginas

Padrão de Desenvolvimento de Componentes

  1. Criar arquivo de componente em src/components/
  2. Definir interface de props (se estiver usando TypeScript)
  3. Escrever script do componente (executa em tempo de build)
  4. Criar template (HTML com sintaxe Astro)
  5. Adicionar estilos com escopo (opcional)

Exemplo:

---
interface Props {
  titulo: string;
  descricao?: string;
}
const { titulo, descricao } = Astro.props;
---

<article>
  <h2>{titulo}</h2>
  {descricao && <p>{descricao}</p>}
</article>

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

Padrão de Desenvolvimento de Páginas

  1. Criar arquivo de página em src/pages/ (determina a rota)
  2. Importar componentes e layouts necessários
  3. Definir getStaticPaths() para rotas dinâmicas
  4. Compor página usando componentes

Exemplo de página:

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

const titulo = "Minha Página";
---

<Layout title={titulo}>
  <Hero />
  <!-- Mais conteúdo -->
</Layout>

Adicionando Interatividade

Quando você precisar de interatividade no lado do cliente:

  1. Instalar integração de framework: npx astro add react
  2. Criar componente de framework (.jsx, .vue, .svelte)
  3. Importar e usar com diretiva cliente:
---
import ReactComponent from '../components/ReactComponent.jsx';
---

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

<!-- Interativo -->
<ReactComponent client:load />
<!-- Opções: client:idle, client:visible, client:media -->

Etapa 6: Consultar Documentação Conforme Necessário

Antes de escrever código, leia as seções relevantes de references/astro_docs.md:

  • Dúvidas sobre componentes → Ler seção "Sintaxe de Componentes"
  • Problemas de roteamento → Ler seção "Roteamento"
  • Estilo → Ler seção "Estilo"
  • Imagens → Ler seção "Imagens e Ativos"
  • Configuração → Ler seção "Configuração"

Para tópicos avançados, busque a documentação completa:

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

Melhores Práticas

Otimização de Performance

  1. Mantenha componentes estáticos por padrão - Adicione client:* apenas quando realmente necessário
  2. Use o componente Image do Astro - Otimização automática
  3. Aproveite a arquitetura de ilhas - JavaScript mínimo por padrão
  4. Divisão de código - Astro divide automaticamente por página

Fluxo de Trabalho de Desenvolvimento

  1. Comece com a estrutura - Configure layouts e páginas básicas primeiro
  2. Orientado a componentes - Construa componentes reutilizáveis
  3. Segurança de tipos - Use TypeScript para props e melhor experiência de desenvolvimento
  4. Coleções de Conteúdo - Para gerenciamento de conteúdo com segurança de tipos
  5. Teste localmente - Execute npm run dev com frequência

Padrões Comuns a Seguir

  • Use layouts para estrutura de página consistente
  • Crie componente SEO para meta tags
  • Configure interfaces TypeScript adequadas
  • Implemente páginas de erro apropriadas (404, 500)
  • Adicione texto alternativo correto às imagens
  • Use HTML semântico

Solução de Problemas

Problemas Comuns

"Módulo não encontrado"

  • Verifique caminhos de importação corretos
  • Confirme que as integrações estão instaladas
  • Verifique se astro.config.mjs tem a configuração de integração correta

"Página não renderizando"

  • Verifique se o arquivo está no diretório src/pages/
  • Verifique erros de sintaxe no frontmatter
  • Garanta extensão de arquivo correta (.astro, .md, .mdx)

"Estilos não sendo aplicados"

  • Estilos com escopo se aplicam apenas ao HTML do próprio componente
  • Use is:global para estilos globais
  • Verifique a configuração do Tailwind se estiver usando Tailwind

"Componente não interativo"

  • Adicione diretiva client:* aos componentes de framework
  • Garanta que a integração esteja instalada (ex.: @astrojs/react)
  • Verifique o console do navegador para erros de JavaScript

Recursos

Scripts

  • scripts/theme_analyzer.py - Ajuda a buscar e analisar temas do Astro na página oficial de temas. Use para explorar opções de tema programaticamente com base em filtros de tecnologia e preço.

Referências

  • references/astro_docs.md - LEIA ISTO PRIMEIRO para conceitos principais do Astro, sintaxe de componentes, roteamento, estilo e padrões comuns. Esta é sua referência principal para desenvolvimento Astro.

Recursos Externos

Exemplos de Fluxo de Trabalho

Exemplo 1: Construindo um Blog

Usuário: "Quero construir um blog com Astro e React"

Fluxo de trabalho:

  1. Identificar requisitos: Site de blog, precisa de suporte React, quer tema gratuito
  2. Buscar 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 blog com explicações
  4. Ler references/astro_docs.md para consultar padrões de componentes
  5. Orientar configuração: Fornecer comandos de instalação e estrutura
  6. Ajudar na construção: Criar layout de postagem de blog, página de listagem, páginas de postagem individuais
  7. Adicionar interatividade: Mostrar como adicionar componentes React com client:load para recursos como comentários

Exemplo 2: Site de Portfólio

Usuário: "Crie um site de portfólio para mim usando https://astro.build/"

Fluxo de trabalho:

  1. Esclarecer requisitos: O que mostrar (projetos, habilidades, experiência?)
  2. Buscar temas de portfólio na página de temas do Astro
  3. Recomendar a melhor correspondência com base na área do usuário (desenvolvedor, designer, etc.)
  4. Ler sintaxe de componentes de references/astro_docs.md
  5. Configurar estrutura do projeto com o tema selecionado
  6. Criar/personalizar componentes (Hero, Grade de Projetos, Sobre, Contato)
  7. Adicionar transições suaves se necessário
  8. Otimizar imagens usando o componente Image do Astro

Exemplo 3: Site de Documentação

Usuário: "Preciso de um site de documentação com busca e modo escuro"

Fluxo de trabalho:

  1. Identificar: Site de documentação, precisa de busca e modo escuro
  2. Recomendar Starlight (framework oficial de documentação do Astro)
  3. Mostrar configuração: npm create astro@latest -- --template starlight
  4. Consultar documentação do Starlight na documentação completa do Astro
  5. Configurar estrutura de navegação lateral
  6. Configurar estrutura de conteúdo
  7. Ativar modo escuro (integrado)
  8. Configurar busca (integrada com Pagefind)

Lembretes Principais

  1. Sempre leia references/astro_docs.md PRIMEIRO antes de responder perguntas sobre componentes ou sintaxe
  2. Busque temas na página de temas do Astro quando o usuário precisar de um ponto de partida
  3. Use web_fetch para documentação completa quando necessário
  4. Mantenha simples - Astro foi projetado para ser direto; não complique demais
  5. Arquitetura de ilhas - Lembre-se de que os componentes são estáticos por padrão
  6. Segurança de tipos - Incentive o uso de TypeScript para melhor experiência de desenvolvimento

Critérios de Sucesso

Um projeto Astro está configurado corretamente quando:

  • ✅ A estrutura do projeto segue as convenções do Astro
  • ✅ O diretório src/pages/ existe com pelo menos index.astro
  • ✅ Tema apropriado selecionado com base nos requisitos
  • ✅ Componentes seguem os padrões de sintaxe do Astro
  • ✅ Interatividade no lado do cliente adicionada apenas onde necessário
  • ✅ Interfaces TypeScript definidas para props de componentes
  • ✅ Imagens otimizadas usando o componente Image do Astro
  • ✅ O site é executado com sucesso com npm run dev

Habilidades Relacionadas