jdevalk/skills - SEO para Astro

SEO para Astro

Audita e melhora a configuração de SEO de um site Astro em relação à pilha completa descrita em Astro SEO: o guia definitivo. A skill cobre nove áreas — base técnica, dados estruturados, conteúdo, estrutura do site, desempenho, sitemaps e indexação, descoberta de agentes, redirecionamentos e análises — e produz código pronto para uso para qualquer item ausente ou fraco.

A espinha dorsal opinativa desta skill é o @jdevalk/astro-seo-graph. A maioria das correções passa por ele. Se o projeto ainda não o utiliza, instalá-lo é a primeira recomendação.

As receitas de código estão em AGENTS.md — leia-o quando precisar implementar uma correção específica. Este arquivo contém o fluxo de trabalho e a lista de verificação de auditoria.

Fluxo de trabalho

1. Detectar o projeto — confirme que é um site Astro e entenda sua estrutura.
2. Auditar — pontue nove categorias e produza descobertas acionáveis.
3. Melhorar — gere ou modifique arquivos para preencher as lacunas. As receitas estão em AGENTS.md.
4. Passagem de metadados — invoque metadata-check em cada string curta que a skill gerou (títulos, descrições, campos description de schema, respostas de FAQ, excertos de frontmatter).
5. Verificar — execute a compilação, verifique se as validações passam, lembre o usuário sobre tarefas que não são de arquivo (Search Console, Bing Webmaster Tools, verificação de chave IndexNow).

---

Fase 0: Detectar o projeto

Confirme o básico antes de auditar:

• astro.config.mjs / astro.config.ts existe.
• package.json tem astro como dependência.
• site: está definido em astro.config — canônicos, sitemaps e URLs de imagem OG derivam disso. Se estiver ausente, vazio ou como http://localhost, sinalize como um problema bloqueante antes de qualquer outra coisa. Esta é a configuração incorreta mais comum.
• Coleções de conteúdo em src/content/ (ou src/pages/ markdown legado).
• Destino de implantação — leia package.json, vercel.json, netlify.toml, wrangler.toml ou public/_headers para determinar o host. Isso orienta a sintaxe de redirecionamento e cabeçalhos na Fase 2.
• O @jdevalk/astro-seo-graph já está instalado? Se sim, registre a versão e quais recursos estão conectados (pesquise por <Seo, seoGraph(, createSchemaEndpoint, createSchemaMap, FuzzyRedirect, createIndexNowKeyRoute, createMarkdownEndpoint, createApiCatalog, gitLastmod). Verifique a versão instalada em relação à mais recente no npm com npm view @jdevalk/astro-seo-graph version. Se o projeto estiver desatualizado, recomende uma atualização na Fase 2 antes de auditar lacunas de recursos — o pacote lança novos padrões e correções regularmente, e uma versão desatualizada é uma causa plausível para qualquer descoberta de auditoria. A Fase 2 ramifica a partir disso.
• O site é multilíngue? Verifique se há i18n em astro.config ou vários diretórios de locale em src/content/. Se sim, hreflang é importante; se não, pule.

Pergunte apenas o que você não consegue detectar. Não pergunte ao usuário sobre o que é o site — leia astro.config.mjs e o conteúdo da página inicial.

---

Fase 1: Auditoria

Pontue cada categoria de 0 a 10. Para cada uma, dê de 2 a 4 descobertas específicas que citem o código ou configuração real. Dentro de cada categoria, as verificações são em níveis:

• Obrigatório — bloqueadores de lançamento. Uma falha aqui causa regressão visível de SEO.
• Recomendado — prática padrão. Pular custa alcance.
• Bônus — voltado para o futuro ou situacional. Útil, mas não é linha de base para todo site.

Pule verificações Bônus para pequenos blogs pessoais, a menos que o usuário peça o tratamento completo.

1. Componente <Seo> e metadados head (/10)

• Obrigatório — componente único para todos os metadados head (não espalhado por layouts).
• Obrigatório — site: em astro.config está definido para a origem de produção.
• Obrigatório — URLs canônicas derivadas da configuração site com parâmetros de rastreamento removidos.
• Obrigatório — canônico omitido quando noindex é verdadeiro (por recomendação do Google).
• Obrigatório — cadeia de fallback para campos de SEO ausentes: seo.title → title → siteName; seo.description → excerpt → primeiro parágrafo. Páginas com títulos ou descrições em branco são o sintoma mais comum de uma cadeia de fallback quebrada.
• Recomendado — meta robots inclui max-snippet:-1, max-image-preview:large, max-video-preview:-1.
• Recomendado — tags do Twitter suprimidas quando duplicam o Open Graph (o Twitter faz fallback automaticamente).
• Recomendado — alternativas hreflang presentes em sites multilíngues. Pule se for monolíngue.
• Bônus — usa o componente <Seo> do @jdevalk/astro-seo-graph em vez de um feito à mão. (Feito à mão que cobre tudo acima está ok; esta skill incentiva o uso do pacote porque ele lida com a cadeia de fallback e regras de robots por padrão.)

2. Dados estruturados / grafo JSON-LD (/10)

• Objeto Article único e plano, ou um @graph vinculado com múltiplas entidades?
• Entidades conectadas com referências @id?
• WebSite, Blog/WebPage, Person/Organization, BlogPosting/Article, BreadcrumbList, ImageObject todos presentes onde relevante?
• Sinais de confiança: publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction?
• Valida no Rich Results Test e no ClassySchema?

3. Coleções de conteúdo e schema de SEO (/10)

• Coleções de conteúdo definidas com schemas Zod?
• seoSchema do @jdevalk/astro-seo-graph aplicando comprimentos de título (5–120) e descrição (15–160)?
• Campos obrigatórios (publishDate, title, excerpt) aplicados em tempo de compilação?
• articleBody com markdown removido exposto em endpoints de schema (até 10K caracteres)?

4. Imagens Open Graph (/10)

• Toda página tem uma imagem OG, ou muitas estão ausentes?
• 1200×675 (Google Discover mínimo 1200px de largura, proporção 16:9)?
• Gerada em tempo de compilação via satori + sharp, ou manual?
• JPEG (plataformas sociais não suportam WebP/AVIF de forma confiável)?
• Rota deriva a URL OG do slug automaticamente?
• Cada <img> no HTML renderizado tem um atributo alt (ou alt="" / role="presentation" para imagens decorativas)? validateImageAlt no seoGraph() detecta isso em tempo de compilação na versão ≥ 1.1.0.

5. Sitemaps e indexação (/10)

• Obrigatório — @astrojs/sitemap instalado, índice de sitemap acessível.
• Obrigatório — robots.txt referencia o índice de sitemap.
• Obrigatório — Feed RSS existe (@astrojs/rss), anunciado via <link rel="alternate" type="application/rss+xml">, contém conteúdo completo da postagem (não excertos truncados).
• Recomendado — dividido por coleção via opção chunks (sitemap-posts-0.xml, etc.) — muito mais fácil depurar a indexação no GSC.
• Recomendado — lastmod populado a partir de timestamps de commits git, não de datas de frontmatter ou timestamps de arquivos de CI. @jdevalk/astro-seo-graph ≥ 1.4.0 exporta gitLastmod(filePath, { excludeCommits, depth }) para isso — ele retorna a data do committer do commit não excluído mais recente que tocou o arquivo, ou null se o git não estiver disponível. Conecte-o ao callback serialize do sitemap. Se o código tiver um helper execSync('git log ...') feito à mão, substitua-o pela exportação do pacote — a exportação lida com a exclusão de commits em massa (importações, reformatações) que uma busca ingênua com -1 não consegue.
• Recomendado — IndexNow integrado e enviando em cada compilação, com rota de verificação de chave em /[key].txt. ≥ 1.0.1 exclui /404 dos envios por padrão. Condicione o envio ao host de produção (por exemplo, process.env.CF_PAGES === '1' && CF_PAGES_BRANCH === 'main', VERCEL_ENV === 'production', CONTEXT === 'production'). O envio incondicional pinga o endpoint em cada npm run build local e implantação de pré-visualização com URLs que o host de produção ainda não atendeu, o que marca a chave como inválida (403) e força a rotação.

6. Descoberta de agentes (/10)

• Recomendado — endpoints de schema (/schema/*.json) expondo JSON-LD de todo o corpus.
• Recomendado — mapa de schema (/schemamap.xml) listando todos os endpoints, com diretiva Schemamap: em robots.txt.
• Recomendado — llms.txt na raiz do site listando páginas (título + descrição) para consumidores LLM. @jdevalk/astro-seo-graph ≥ 0.9.0 gera isso através da opção de integração llmsTxt.
• Recomendado — URLs alternativas em markdown (/blog/post.md ao lado de /blog/post/) servindo markdown limpo com frontmatter YAML para agentes de IA consumirem sem análise de HTML. @jdevalk/astro-seo-graph ≥ 1.2.0 fornece createMarkdownEndpoint para a rota e uma opção de integração markdownAlternate: true que emite <link rel="alternate" type="text/markdown"> em cada página. ≥ 1.3.0 adiciona verificação pós-compilação: a integração percorre a saída da compilação e remove qualquer link cujo destino .md não esteja no disco (com um warn por ocorrência) — então um endpoint mal configurado aparece como um aviso de compilação em vez de um 404 enviado. Combine com uma Cloudflare Transform Rule (reescrita de URL via wildcard_replace, sem cabeçalho Vary: Accept — o CF remove valores Vary personalizados) para negociação de conteúdo em Accept: text/markdown sem precisar de SSR.
• Recomendado — catálogo de API em /.well-known/api-catalog conforme RFC 9727. @jdevalk/astro-seo-graph ≥ 1.4.0 fornece createApiCatalog, que tipa automaticamente os endpoints de schema para suas URLs https://schema.org/<Type> e absolutiza caminhos em relação a siteUrl. Liste os endpoints de schema, schemamap e quaisquer APIs específicas do site (/ask, /feed.xml, etc.). O RFC é finalizado, então o formato é estável; a adoção é inicial, mas o custo é um arquivo de rota.
• Recomendado — Diretiva Content Signals em robots.txt (por exemplo, Content-Signal: ai-train=yes, search=yes, ai-input=yes). Declara preferências para treinamento de IA, fundamentação de pesquisa e uso de entrada de IA independentemente do acesso de rastreamento. A especificação é um rascunho do IETF e a adoção é inicial, mas é uma linha em um arquivo que todo site já possui.
• Recomendado — Cabeçalho Link em /* apontando para arquivos de descoberta (sitemap, llms.txt, api-catalog, schemamap e quaisquer cartões MCP / A2A que o site publica). Agentes que leem cabeçalhos de resposta os encontram sem analisar HTML. No Cloudflare Pages / Netlify isso é public/_headers; no Vercel é vercel.json.
• Bônus — Cartão de servidor MCP em /.well-known/mcp/server-card.json (SEP-1649) e/ou cartão de agente A2A em /.well-known/agent-card.json (protocolo A2A). Relevante apenas quando o site realmente expõe um servidor MCP ou agente A2A. Ambos são arquivos JSON estáticos declarando o endpoint, capacidades e habilidades. Pule caso contrário.
• Bônus — <link rel="nlweb"> apontando para um endpoint conversacional. NLWeb é inicial; a tag é uma linha e vale a pena ter, mas não é um bloqueador de pontuação em 2026.
• Bônus — Catálogo ARD (Agentic Resource Discovery) em /.well-known/ai-catalog.json, listando o que o domínio oferece (servidor MCP, agente A2A, pacote OKF, APIs específicas do site). Rascunho v0.9, portanto opcional — mas é a camada de descoberta que os cartões MCP / A2A e o pacote OKF compensam. Duas armadilhas: a especificação base (Agent-Card/ai-catalog) nomeia o campo de tipo de mídia como mediaType enquanto a camada ARD (ards-project/ard-spec) o nomeia type — emita ambas as chaves com o mesmo valor para que a entrada seja válida sob qualquer leitura (ambas as especificações exigem que os consumidores ignorem chaves desconhecidas). ARD também adiciona um array opcional representativeQueries de prompts de amostra por entrada.
• Bônus — Pacote OKF (Open Knowledge Format): uma árvore de arquivos Markdown de conceito tipados (um por página, caminhos espelhando URLs canônicas) empacotados como um único .tar.gz, com arquivos de índice entre eles. Servir e descobrir são não-objetivos explícitos do OKF — para isso serve a entrada do catálogo ARD. Rascunho v0.9, opcional. Ainda não há um tipo de mídia registrado, então a string provisória é application/okf-bundle+gzip (rastreada em knowledge-catalog#111 e ard-spec#27); marque-a como provisória, pode mudar. Melhor gerada como mais uma saída de um pipeline de conteúdo existente em vez de uma cópia mantida manualmente.

7. Desempenho (/10)

• Saída estática por padrão (sem SSR em páginas que não precisam)?
• Zero JS no lado do cliente, a menos que uma ilha o exija?
• Componente <Image> do Astro usado para todas as imagens de conteúdo (srcset responsivo, WebP, lazy, async)?
• Fonte web primária pré-carregada em woff2?
• <ClientRouter /> com defaultStrategy: 'viewport' para pré-busca?
• Ativos com hash em /_astro/ servem Cache-Control: public, max-age=31536000, immutable?
• Cabeçalho de resposta No-Vary-Search removendo parâmetros UTM da chave de cache?

8. Redirecionamentos e tratamento de erros (/10)

• public/_redirects (ou equivalente) mantido para cada URL que já existiu e foi movida?
• 301 e não 302 para movimentos permanentes?
• Componente FuzzyRedirect do @jdevalk/astro-seo-graph conectado à página 404?
• A própria página 404 retorna um status 404, não 200?

9. Validação em tempo de compilação e qualidade de conteúdo (/10)

• Obrigatório — Integração seoGraph() executando em cada compilação com validateH1 e validateUniqueMetadata habilitados. Para validação JSON-LD, passe warnOnDanglingReferences: true para assembleGraph() em seo-graph-core — essa é a verificação em tempo de montagem, não uma opção de integração.
• Recomendado — validateImageAlt, validateMetadataLength e validateInternalLinks habilitados no seoGraph() (todos padrão true na versão ≥ 1.1.0). Eles detectam texto alt ausente, títulos ou descrições fora dos limites SERP (padrões: título 30–65, descrição 70–200) e links internos que resultam em 404 ou encontram incompatibilidade de barra final. Atualize para ≥ 1.1.1 se o projeto estiver na 1.1.0 — essa versão de patch corrige dois bugs do validador: validateInternalLinks agora reconhece ativos de public/ como destinos válidos (sem mais falsos positivos em /images/* ou /fonts/*), e validateMetadataLength não trunca mais descrições que contêm