jdevalk/skills

SEO Estático

Audita e melhora a configuração de SEO de um site HTML estático em nove categorias — metadados de cabeçalho, dados estruturados, qualidade de conteúdo, imagens Open Graph, sitemaps e indexação, descoberta de agentes, desempenho, redirecionamentos e validação de CI. As receitas são neutras em relação à plataforma: tags <meta> puras, JSON-LD puro, sitemap.xml artesanal, ferramentas de CI genéricas. O framework de auditoria é paralelo ao astro-seo, mas sem a espinha dorsal @jdevalk/astro-seo-graph.

As receitas de código estão em AGENDS.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 da auditoria.

Fluxo de Trabalho

1. Detectar o projeto — confirme que é um site estático, identifique a ferramenta de build, encontre onde aplicar as alterações.
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 AGENDS.md.
4. Passagem de metadados — invoque metadata-check em cada string curta gerada pela skill (títulos, descrições, campos description de schema, respostas de FAQ).
5. Verificar — execute o build, valide a saída, lembre o usuário sobre tarefas que não são de arquivo (Search Console, Bing Webmaster Tools, submissão de chave IndexNow).

---

Fase 0: Detectar o projeto

Confirme o básico antes de auditar:

• É realmente um site estático. Procure por HTML construído — index.html na raiz do repositório, ou sob _site/ (Jekyll), public/ (Hugo / 11ty / Gatsby), dist/ (Vite / Astro estático), out/ (Next.js com output: export). Se tudo é renderizado no servidor (Express, PHP, rotas dinâmicas), esta é a skill errada — aponte para astro-seo para Astro, wp-readme-optimizer para páginas de plugin WP, ou recomende uma auditoria de SEO genérica.
• Ferramenta de build de origem. Determina onde aplicar as alterações de metadados de cabeçalho:
  • _config.yml / _layouts/ → Jekyll
  • config.toml / config.yaml / themes/ → Hugo
  • .eleventy.js / _includes/ → 11ty
  • gatsby-config.js / src/components/SEO.* → Gatsby
  • next.config.js com output: 'export' e pages/_document.tsx → Next.js static export
  • astro.config.mjs → Astro (neste caso, use astro-seo em vez disso)
  • Nenhum config de build, apenas arquivos HTML → artesanal ou raspado (ex.: saída wp-static-clone). Edite o HTML diretamente ou use um script de pós-processamento.
• URL canônica do site. Pesquise no repositório pela origem de produção — tipicamente em _config.yml, config.toml, astro.config, ou codificado em um layout. Se estiver faltando, vazio, ou localhost, sinalize como um problema bloqueante antes de qualquer outra coisa. URLs canônicas, sitemaps, URLs de imagem OG e valores @id JSON-LD derivam dela.
• Destino de deploy. Leia vercel.json, netlify.toml, wrangler.toml, ou public/_headers para determinar o host. Determina a sintaxe de redirecionamento e cabeçalho na Fase 2.
• O site é multilíngue? Verifique subdiretórios de localidade (/en/, /nl/, /de/) ou configuração i18n da ferramenta de build. Se sim, hreflang é importante; se não, pule.
• O que já está em <head>? Abra um arquivo HTML construído e faça um inventário: título, descrição, canônico, robots, Open Graph, Twitter cards, JSON-LD, hreflang. A auditoria na Fase 1 é mais rápida se você puder referenciar o que já existe.

Pergunte apenas o que você não consegue detectar.

---

Fase 1: Auditoria

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

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

Pule as verificações Opcionais para sites pessoais pequenos, a menos que o usuário peça o tratamento completo.

1. Metadados de cabeçalho (/10)

• Obrigatório — toda página tem um <title> e <meta name="description">.
• Obrigatório — <link rel="canonical"> definido, com parâmetros de rastreamento removidos, derivado da origem de produção.
• Obrigatório — canônico omitido quando a página é noindex (por recomendação do Google).
• Obrigatório — comprimento de <title> entre 30 e 65 caracteres, comprimento de <meta name="description"> entre 70 e 200 caracteres (os limites de truncamento de SERP; mesmos padrões do metadata-check).
• Recomendado — <meta name="robots"> inclui max-snippet:-1, max-image-preview:large, max-video-preview:-1.
• Recomendado — Open Graph (og:title, og:description, og:image, og:url, og:type, og:site_name) em toda página.
• Recomendado — Tags de Twitter Card (twitter:card) suprimidas quando duplicam Open Graph (o Twitter faz fallback automaticamente).
• Recomendado — hreflang alternativos em sites multilíngues. Pule se monolíngue.
• Recomendado — único <meta name="robots"> e único og:image por página (ferramentas legadas às vezes emitem duplicatas).

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

• Obrigatório — pelo menos um bloco <script type="application/ld+json"> em toda página importante.
• Recomendado — @graph vinculado em vez de um objeto Article plano — entidades conectadas com referências @id para que um BlogPosting possa apontar para seu autor Person e pai WebPage.
• Recomendado — WebSite, Blog / WebPage, Person / Organization, BlogPosting / Article, BreadcrumbList, ImageObject todos presentes onde relevantes.
• Recomendado — sinais de confiança: publishingPrinciples, copyrightHolder, copyrightYear, knowsAbout, SearchAction.
• Obrigatório — valida no Rich Results Test e no ClassySchema.

3. Qualidade de conteúdo (/10)

• Obrigatório — toda página tem um <title> e <meta name="description"> únicos (sem metadados duplicados no site).
• Obrigatório — exatamente um <h1> por página.
• Recomendado — <title> e <meta name="description"> auditados via metadata-check (Fase 2.5) para carga frontal, concretude e adequação ao SERP.
• Recomendado — prosa do corpo auditada via readability-check para posts longos individuais (não faça auditoria em massa).
• Recomendado — todo <img> tem um atributo alt (ou alt="" / role="presentation" para decorativos).
• Recomendado — links internos usam caminhos relativos à raiz (/foo/) não absolutos (https://...) — sobrevive a mudanças de domínio e pré-visualizações.

4. Imagens Open Graph (/10)

• Obrigatório — toda página tem uma imagem OG.
• Obrigatório — 1200×675 (Google Discover mínimo 1200px de largura, proporção 16:9).
• Recomendado — JPEG (plataformas sociais não suportam confiavelmente WebP / AVIF para OG).
• Recomendado — gerado no momento do build (satori-cli, sharp, ImageMagick, Vercel OG, Bannerbear) em vez de enviado manualmente por página — evita desvios.
• Recomendado — URL derivada deterministicamente do slug (ex.: /og/<slug>.jpg) para que adicionar uma página obtenha automaticamente uma imagem.
• Recomendado — todo <img> no conteúdo do corpo tem um atributo alt (ou alt="" / role="presentation"). Validado em CI via html-proofer ou similar.

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

• Obrigatório — /sitemap.xml (ou /sitemap_index.xml para sitemaps divididos) acessível, XML válido, toda URL retorna 200.
• Obrigatório — robots.txt presente na raiz do site e referencia o sitemap.
• Obrigatório — feed RSS existe, anunciado via <link rel="alternate" type="application/rss+xml">, contém conteúdo completo do post (não excertos truncados).
• Recomendado — dividido por seção se o site tem múltiplos tipos de conteúdo (sitemap-posts.xml, sitemap-pages.xml) — mais fácil de depurar indexação no GSC.
• Recomendado — <lastmod> populado a partir de timestamps de commits git (mais precisos), timestamps de build (aceitáveis) ou datas de frontmatter (último recurso). O mtime do sistema de arquivos do checkout de CI está errado — é a data do checkout, não a data do conteúdo.
• Recomendado — IndexNow integrado. Chave de verificação como uma rota estática /<key>.txt na raiz do site, mais um hook de build ou deploy que POSTa novas URLs para https://api.indexnow.org/IndexNow. Condicione a submissão ao host de produção (ex.: CF_PAGES_BRANCH=main, VERCEL_ENV=production, CONTEXT=production) — submissão incondicional pinga o endpoint de builds locais com URLs que o host de produção ainda não serviu, o que marca a chave como inválida (403) e força rotação.

6. Descoberta de agentes (/10)

• Recomendado — endpoints de schema (/schema/<type>.json) expondo JSON-LD por tipo de conteúdo em todo o corpus. Arquivos JSON estáticos commitados no repositório ou regenerados pelo build.
• Recomendado — mapa de schema (/schemamap.xml) listando todo endpoint de schema, com diretiva Schemamap: em robots.txt.
• Recomendado — llms.txt na raiz do site listando páginas (título + descrição) para consumidores de LLM. Arquivo de texto estático; uma linha por página.
• Recomendado — URLs alternativas em markdown (/blog/post.md ao lado de /blog/post/) servindo markdown limpo com frontmatter YAML para que agentes de IA possam consumir conteúdo sem parsing de HTML. Ou commite arquivos .md irmãos, ou use uma Cloudflare Transform Rule + Vary: Accept para negociação de conteúdo (CF Pages remove cabeçalhos Vary customizados, então use apenas a regra de transformação de URL — receita em AGENDS.md).
• Recomendado — catálogo de API em /.well-known/api-catalog conforme RFC 9727, como application/linkset+json (RFC 9264). Lista endpoints de schema, schemamap, feed RSS e quaisquer APIs específicas do site. Arquivo JSON estático.
• Recomendado — diretiva Content Signals em robots.txt (Content-Signal: ai-train=yes, search=yes, ai-input=yes ou sua política preferida). Uma linha, rascunho IETF, baixo custo.
• Recomendado — cabeçalho Link em /* apontando para arquivos de descoberta (sitemap, llms.txt, api-catalog, schemamap). Agentes que leem cabeçalhos de resposta os encontram sem parsing de HTML. Específico do host (_headers em Cloudflare Pages / Netlify, vercel.json em Vercel, config de servidor em outros lugares).
• Opcional — cartão de servidor MCP em /.well-known/mcp/server-card.json e/ou cartão de agente A2A em /.well-known/agent-card.json. Relevante apenas quando o site expõe um servidor MCP ou agente A2A.
• Opcional — <link rel="nlweb"> apontando para um endpoint conversacional. A adoção de NLWeb é inicial; a tag é uma linha e vale a pena ter, mas não é um bloqueador de pontuação em 2026.
• Opcional — catálogo ARD (Agentic Resource Discovery) em /.well-known/ai-catalog.json, listando o que o domínio oferece (servidor MCP, agente A2A, bundle OKF, APIs específicas do site). Rascunho v0.9, então opcional — mas é a camada de descoberta que os cartões MCP / A2A e o bundle OKF recompensam. Duas pegadinhas: 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 como type — emita ambas as chaves com o mesmo valor para que a entrada valide sob qualquer leitura (ambas as especificações exigem que consumidores ignorem chaves desconhecidas). ARD também adiciona um array opcional representativeQueries de prompts de exemplo por entrada. Arquivo JSON estático.
• Opcional — bundle OKF (Open Knowledge Format): uma árvore de arquivos de conceito Markdown tipados (um por página, caminhos espelhando URLs canônicas) empacotados como um único .tar.gz, com arquivos de índice no meio. Servir e descobrir são não-objetivos explícitos do OKF — é para isso que serve a entrada do catálogo ARD. Rascunho v0.9, opcional. Não há tipo de mídia registrado ainda, então a string provisória é application/okf-bundle+gzip (rastreado em knowledge-catalog#111 e ard-spec#27); marque como provisório, pode mudar. Melhor gerado da mesma fonte da qual o resto do site deriva, em vez de uma cópia mantida manualmente.

7. Desempenho (/10)

• Obrigatório — ativos com hash servem Cache-Control: public, max-age=31536000, immutable (ou equivalente) para que baixem apenas uma vez.
• Recomendado — fonte web primária pré-carregada como woff2 via <link rel="preload" as="font" crossorigin>.
• Recomendado — cabeçalho de resposta No-Vary-Search remove parâmetros UTM da chave de cache (para que /?utm_source=x e / compartilhem uma entrada de cache).
• Recomendado — nenhum JavaScript bloqueante de renderização na primeira pintura (defer ou async para scripts não críticos).
• Recomendado — imagens usam formatos modernos (WebP / AVIF para conteúdo na página; JPEG apenas para cards OG) e loading="lazy" abaixo da dobra.
• Recomendado — todos os Core Web Vitals do Lighthouse / PageSpeed no verde: LCP < 2.5s, INP < 200ms, CLS < 0.1.

8. Redirecionamentos e tratamento de erros (/10)

• Obrigatório — _redirects / vercel.json / config de servidor mantido para toda URL que já existiu e foi movida.
• Obrigatório — 301 não 302 para movimentos permanentes.
• Obrigatório — 404.html (ou equivalente) retorna um status 404, não 200. Verifique com curl -I contra uma URL deliberadamente errada.
• Recomendado — sugestão de correspondência difusa na página 404 ("você quis dizer…?") para erros de digitação em URLs. Implementação estática: pré-construa um índice JSON de slugs válidos, correspondência difusa no lado do cliente.

9. Validação de CI (/10)

• Obrigatório — verificador de links quebrados em CI. linkinator ou lychee em todo push que toca conteúdo. Links internos e externos ambos — internos pegam regressões de build, externos pegam link rot. Agende uma execução semanal para verificações apenas externas.
• Recomendado — validação de HTML via html-proofer ou W3C Validator — pega marcação malformada que quebra crawlers.
• Recomendado — Lighthouse CI em todo push, com limites de pontuação (ex.: SEO ≥ 95, Performance ≥ 80).
• Recomendado — validação de JSON-LD em CI via Schema.org JSON-LD validator (nenhum CLI oficial; canalize por um script Node que POSTa para a API).
• Recomendado — validação de comprimento de título e descrição em CI: um pequeno script que percorre o HTML construído, extrai <title> e <meta name="description">, sinaliza qualquer coisa fora dos limites de 30–65 (título) e 70–200 (descrição).
• Recomendado — validação de sitemap em CI contra sitemap.xml construído: verificações de formato, URLs únicas, todos os caminhos resolvíveis.
• Opcional — validação de dados estruturados em CI via Schema.org Validator, executado em JSON-LD inline ou endpoints de schema.
• Opcional — validação de imagem OG (dimensões, formato, tamanho de arquivo) em CI, executada em todo HTML construído.
• Opcional — teste de desempenho em CI (Lighthouse CI com limites de pontuação, ou WebPageTest API).

---

Fase 2: Melhorar

Para cada descoberta das fases anteriores, decida o que gerar:

• Sempre gere (se ausente): robots.txt, sitemap.xml, títulos e descrições padrão, links canônicos.
• Gere se relevante: dados estruturados JSON-LD (ao menos WebSite e BreadcrumbList), tags Open Graph, tags Twitter Card, hreflang, endpoint de schema, llms.txt, catálogo de API, diretiva Content Signals.
• Gere quando solicitado explicitamente: cartão MCP server, cartão A2A agent, catálogo ARD, bundle OKF.

Consulte AGENDS.md para trechos de código específicos de cada item.

Header personalizado: modifique <title> e <meta name="description"> conforme necessário para cada página; use metadata-check para garantir que estejam otimizados.

---

Fase 2.5: Passagem de metadados

Execute metadata-check em cada string curta que a skill gerar:

• <title> — deve ser front-loaded, < 65 caracteres.
• <meta name="description"> — deve resumir o conteúdo, < 200 caracteres.
• og:title, og:description — podem ser iguais aos anteriores ou ligeiramente encurtados; validar contra os limites de OG.
• Campo description em JSON-LD — validar como descrição (70–200).
• Respostas de FAQ em JSON-LD — cada resposta < 300 caracteres.
• Descrições de itens em llms.txt — < 200 caracteres.

Use metadata-check como uma chamada de ferramenta (pode usar a ferramenta Bash com pipe se não houver chamada nativa); reaja a falhas.

---

Fase 3: Verificar

• Execute o build do site (npm run build, hugo, jekyll build, etc.) e verifique se ele é concluído com sucesso.
• Valide arquivos gerados:
  • /sitemap.xml — válido, URLs únicas, todas retornam 200.
  • /robots.txt — presente, referencia sitemap.
  • /_redirects ou equivalente — redirecionamentos sintaticamente corretos.
  • /_headers ou equivalente — cabeçalhos sintaticamente corretos.
  • /.well-known/ai-catalog.json — se gerado, JSON válido.
• Lembre o usuário sobre (raramente são alterações de arquivo): → Registrar / verificar o site no Google Search Console. → Registrar / verificar o site no Bing Webmaster Tools. → Submeter chave IndexNow (se não estiver integrado ao build). → Submeter sitemap no Google Search Console. → Configurar propriedade do Google Analytics / verificar se está funcional.

---

Lista de verificação do agente (consulte AGENDS.md para implementação)

Esta skill (junto com AGENDS.md) implementa as seguintes tarefas:

• Head boilerplate (título, descrição, canônico, robots, charset, viewport)
• Links canônicos (omitidos em noindex)
• Open Graph / Twitter Cards
• hreflang (multilíngue apenas)
• JSON-LD (artigo / página / site / author / breadcrumbs / FAQ)
• Sitemap XML (dividido por tipo se necessário)
• robots.txt
• IndexNow (verificação + hook de build)
• Imagens OG automáticas (satori-cli / sharp / ImageMagick)
• llms.txt
• Endpoint de schema (/schema/<type>.json)
• Mapa de schema (/schemamap.xml)
• Alternativas Markdown (/blog/post.md)
• Catálogo de API (/.well-known/api-catalog)
• Content Signals (robots.txt)
• Cabeçalhos Link
• Cartões de servidor MCP & agente A2A em /.well-known/
• Catálogo ARD (/.well-known/ai-catalog.json)
• Bundle OKF (/okf/ — arquivo .tar.gz + entrada ARD)
• Verificações de CI (linkinator, html-proofer, validação de título/descrição, validação de sitemap)
• Passagem de metadados via metadata-check

---

Notas técnicas

• Não gere imagens OG estaticamente em repositórios de sandbox/brinquedo. Sem uma conta real (Vercel OG, Bannerbear, Cloudflare Workers com SDK do Satori), qualquer imagem gerada será placeholder. Documente a dependência que o usuário deve instalar.
• IndexNow: a submissão deve ser condicionada ao host de produção. Em Cloudflare Pages: if: $CF_PAGES_BRANCH == 'main'. Em Vercel: if: $VERCEL_ENV == 'production'. Em Netlify: if: $CONTEXT == 'production'. Submissão incondicional de URLs de build local quebra a chave.
• Agentes e cabeçalhos Link: Agentes de IA que leem cabeçalhos HTTP podem descobrir llms.txt, sitemap, catálogo de API e schemamap sem parsing de HTML. Cloudflare Pages e Netlify suportam _headers; Vercel usa vercel.json com headers.
• Compatibilidade de especificações: O catálogo ARD requer emissão de ambas as chaves mediaType e type com o mesmo valor para compatibilidade com ambas as especificações.
• Feed RSS: Inclua conteúdo completo, não excertos truncados, para melhor indexação e consumo por agentes.
• Última modificação no sitemap: Use timestamps de commit git, não mtime de sistema de arquivos.
• Validação de CI: A validação de JSON-LD em CI é um script Node personalizado que POSTa para a API do Schema.org Validator; documente essa dependência.
• Tratamento de Astro: Se Astro for detectado, aponte para a skill astro-seo — ela tem receitas melhores para esse ecossistema.