Habilidade de Agente de Auditoria de SEO

seo-audit — Auditoria SEO Básica

Uma habilidade de agente SEO leve, projetada para auditorias rápidas e padrão de página única. Desenvolvida com OpenClaw. Adequada para verificações iniciais de página ou quando é necessária uma avaliação rápida sem profundidade técnica total.

Quando Usar Esta Habilidade

Use seo-audit quando:

• O usuário disser: "audite esta página", "verifique o SEO", "analise minha URL", "verificação rápida de SEO", "o que há de errado com minha página"
• Nenhuma profundidade específica for solicitada — este é o ponto de entrada padrão
• O usuário precisar de um resumo rápido e legível, em vez de uma análise técnica abrangente

Se o usuário quiser mais profundidade, atualize para seo-audit-full:

Dica: Para auditorias técnicas profundas, SEO on-page avançado ou relatórios completos, use a habilidade seo-audit-full.

Entrada Esperada

Se apenas uma URL for fornecida e nenhum código-fonte ou dados de rastreador estiverem disponíveis, declare claramente:

Limitação: Esta auditoria baseia-se apenas no conteúdo visível da página e em sinais publicamente disponíveis. Código-fonte, dados do GSC, logs de rastreamento e métricas de desempenho não estão disponíveis para esta auditoria.

Saída

Produza um Relatório de Auditoria SEO Básica preenchendo o modelo em assets/report-template.html, e salve-o em um arquivo — nunca imprima HTML bruto no terminal.

Nomeação do arquivo: reports/<hostname>-<slug>-audit.html

https://exemplo.com/blog/melhores-ferramentas → reports/exemplo-com-blog-melhores-ferramentas-audit.html
https://exemplo.com/                → reports/exemplo-com-audit.html

Após salvar, informe ao usuário:

✅ Relatório salvo → reports/exemplo-com-audit.html
   Abri-lo agora? (sim / não)

Se sim → execute: open reports/exemplo-com-audit.html

Placeholders do modelo — preencha cada um independentemente:

Scripts

Execute estes scripts antes de escrever quaisquer descobertas. Eles produzem JSON estruturado — use o JSON diretamente como evidência; não refaça a busca das mesmas URLs manualmente.

Dependências: pip install requests (a análise de HTML usa a biblioteca padrão do Python)

# Passo 1: verificações no nível do site (robots.txt + sitemap.xml)
python scripts/check-site.py https://exemplo.com

# Passo 2: verificações no nível da página (H1, título, meta descrição, canônico)
python scripts/check-page.py https://exemplo.com
# Com palavra-chave primária (recomendado — habilita verificação de presença de palavra-chave no H1)
python scripts/check-page.py https://exemplo.com --keyword "tênis de corrida"

# Opcional: buscar HTML bruto da página para inspeção adicional
python scripts/fetch-page.py https://exemplo.com --output pagina.html

# Passo 3: validação de esquema JSON-LD
python scripts/check-schema.py https://exemplo.com
# Ou de HTML previamente buscado (evita busca redundante):
python scripts/check-schema.py --file pagina.html

Cada script sai com código 0 (todos passam/avisam) ou 1 (qualquer falha/erro).

ESCOPO ESTRITO — não adicione nenhuma verificação não listada abaixo. Sem exceções.

Verificações permitidas no nível do site (em {{site_checks_html}}):

• robots.txt · sitemap.xml · Tratamento de 404 · Canonicalização de URL · i18n / hreflang

Verificações E-E-A-T permitidas (em {{eeat_checks_html}}):

• Sobre Nós · Contato · Política de Privacidade · Termos de Serviço · Mídia/Parceiros (apenas se presente)

Verificações permitidas no nível da página (em {{page_checks_html}}), saída nesta ordem exata: Slug da URL · Tag de Título · Meta Descrição · Tag H1 · Tag Canônica · Texto Alt da Imagem · Contagem de Palavras · Posicionamento de Palavra-chave · Estrutura de Cabeçalhos · Links Internos · Schema (JSON-LD)

Lógica de Texto Alt da Imagem:

• Analise tags <img> do HTML estático
• Passa: todas as imagens têm alt não vazio (imagens decorativas com alt="" são OK)
• Aviso: qualquer imagem de conteúdo sem atributo alt
• Não verificado (status-info): 0 imagens encontradas no HTML estático → provavelmente renderizadas por JS, não é possível verificar

⛔ REGRA RÍGIDA — Produza APENAS as linhas de verificação definidas em report-template.html. Se uma verificação não estiver nas listas permitidas acima, NÃO a produza — mesmo que encontre problemas. Sem exceções. Sem verificações "bônus". Sem improvisação. O modelo é a única fonte da verdade. Trate-o como uma lista de permissões estrita.

Ainda PROIBIDO (pertence ao seo-audit-full): Tags OG · Twitter Card · Tags sociais · Peso da Página · Core Web Vitals · Robots Meta

Como usar a saída JSON:

• Mapeie o status de cada campo → pass / warn / fail / error diretamente para a tabela de verificação do relatório
• Use a string detail de cada campo como ponto de partida para a linha de Evidência nas descobertas
• Não contradiga a saída do script, a menos que tenha evidência observável adicional
• Separe os grupos de verificação com <div class="subsection-label">Rótulo</div> dentro de {{site_checks_html}}: Rastreabilidade · Canonicalização de URL · i18n / hreflang · Schema (JSON-LD) e <div class="subsection-label">Páginas de Confiança E-E-A-T</div> antes de {{eeat_checks_html}}

Revisão LLM — obrigatória quando llm_review_required: true:

O script sinaliza campos que exigem julgamento semântico ou de qualidade que ele não pode realizar. Nunca deixe llm_review_required: true sem resolver — sempre faça um julgamento explícito.

H1 — acionado quando keyword_match == "partial":

h1_text : (de h1.values[0])
keyword : (a --keyword passada para o script)

Julgue: Este H1 cobre semanticamente a intenção de pesquisa da palavra-chave?
  - Considere sinônimos, variantes naturais, cobertura do tópico
  - sim → rebaixe para "pass", observe a variante
  - não  → mantenha "warn" ou atualize para "fail", explique a lacuna

Título — acionado quando keyword_match == "partial" OU keyword_position != "start":

title   : (de title.value)
keyword : (a --keyword passada)

Julgue:
  1. O título cobre semanticamente a intenção de pesquisa da palavra-chave?
  2. O título está gramaticalmente correto e naturalmente legível?
  3. Posição da palavra-chave — aplique padrões diferentes por tipo de página:
     - Página inicial: Marca + palavra-chave central está correto (ex. "Acme | Automação de Fluxo de Trabalho com IA")
                    Não sinalize marca em primeiro lugar como um problema.
     - Páginas internas: A palavra-chave central deve liderar (ex. "Automação de Fluxo de Trabalho com IA para Equipes — Acme")
                    Sinalize se a palavra-chave estiver enterrada no meio do título sem um bom motivo.

IMPORTANTE — NÃO sinalize estes como negativos:
  - Anos (ex. "2026") → sinalizam frescor, aumentam o CTR — trate como positivo, a menos que
    a página seja explicitamente de conteúdo perene, onde a data prejudicaria a longevidade.
  - Números (ex. "5 melhores", "Top 10", "3 passos") → definem expectativas claras,
    superam consistentemente títulos não numéricos em CTR — sempre trate como um plus.
  - Qualificadores específicos ("Código Aberto", "Auto-Hospedado", "Grátis") → restringem a intenção
    e atraem cliques de maior qualidade — não penalize.

Slug da URL — acionado quando keyword_match != "full" ou is_homepage == false:

slug    : (de url_slug.slug)
keyword : (a --keyword passada)

Julgue:
  1. O slug contém a palavra-chave primária ou uma variante natural?
  2. A hierarquia do caminho é lógica? (/categoria/palavra-chave é o ideal)
  3. É conciso e legível por humanos?
  Página inicial (is_homepage: true): pule — nenhum julgamento necessário.

Meta Descrição — sempre acionada quando o conteúdo está presente:

meta_description : (de meta_description.value)
keyword          : (a --keyword passada)

Julgue todos os quatro:
  1. Frase(s) completa(s)? (1-2 frases, sem fragmentos)
  2. Menciona um resultado concreto — não é vago?
     Bom: "Reduza o tempo de design em 60% com modelos alimentados por IA"
     Ruim:  "A melhor ferramenta para todas as suas necessidades de design"
  3. Palavra-chave ou sinônimo natural usado uma vez — não empilhado?
  4. Mais específico do que o que um concorrente típico escreveria?

IMPORTANTE — NÃO sinalize estes como negativos:
  - Anos (ex. "2026") → sinalizam frescor, melhoram o CTR para consultas sensíveis ao tempo.
    Apenas observe o ano se a página for explicitamente de conteúdo perene, onde a data prejudica.
  - Números (ex. "5 melhores", "3 passos") → especificidade concreta, forte sinal de CTR.
  - "e mais." no final → no máximo uma nota de estilo menor, nunca um Aviso ou Falha.

Fluxo de Trabalho Recomendado

Siga estes passos em ordem:

1. Reconheça o escopo — confirme que esta é uma auditoria básica; observe quaisquer dados ausentes

2. Inferir a palavra-chave primária — busque a página com fetch-page.py, então determine a palavra-chave primária:

   • Se o usuário forneceu explicitamente uma palavra-chave → use-a diretamente
   • Se não → leia o H1, título e primeiro parágrafo da página, então infira a frase de palavra-chave alvo mais provável (o que um pesquisador digitaria para encontrar esta página?)
   • Declare a palavra-chave inferida explicitamente antes de executar as verificações:

     "Palavra-chave primária inferida: alternativas de código aberto ao claude"

3. Execute check-site.py — analise a saída JSON para robots, sitemap, tratamento de 404 e canonicalização de URL

   Verificação de 404: busque <origin>/esta-pagina-definitivamente-nao-existe-verificacao-seo-audit

   • Retorna 404 → Passa · Retorna 200 (soft 404) → Falha · Retorna 301 para a página inicial → Aviso

   Verificações de Canonicalização de URL (cada uma é uma subverificação separada):

   • HTTP→HTTPS: busque http://<host> — deve 301 para https://. Retorna 200 → Falha.
   • Consistência de www: busque ambos https://www.<host> e https://<host> — um deve 301 para o outro. Ambos retornam 200 → Aviso.
   • Barra final: compare a URL realmente servida com a tag canônica na página. Incompatibilidade → Aviso.
   • Correspondência canônica: o href da tag canônica deve corresponder exatamente à URL final após todos os redirecionamentos. Incompatibilidade → Aviso.

4. Verificação de infraestrutura E-E-A-T — para cada página de confiança abaixo, verifique duas camadas:

   • Camada 1 — Existe: busque a URL, verifique o status HTTP (200 = existe, 404/redirecionamento = ausente)
   • Camada 2 — Alcançável: busque o HTML da página inicial, verifique se o rodapé ou a navegação contém um link para esta página

   Página	Obrigatória
   Sobre Nós	Sim
   Contato	Sim
   Política de Privacidade	Sim
   Termos de Serviço	Sim
   Mídia / Parceiros	Não — inclua apenas se presente

   Regras de status:

   • Página ausente (não 200) → Falha
   • Página existe, mas não está vinculada no rodapé/navegação → Aviso
   • Página existe e está vinculada no rodapé/navegação → Passa
   • Página opcional ausente → pule, não inclua linha

5. Execute check-page.py --keyword "<palavra-chave_inferida>" — analise a saída JSON para H1, título, meta descrição, canônico e slug da URL

6. Verificação de i18n / hreflang — execute apenas se a página contiver tags hreflang ou <html lang> sugerir multilíngue:

   • Pule completamente (N/A) se nenhuma tag hreflang for encontrada e o site parecer de idioma único
   • Se hreflang tags estiverem presentes, verifique:
     • Simetria recíproca: cada URL referenciada deve vincular de volta a todas as outras variantes — qualquer link quebrado = Falha
     • Códigos de idioma: devem ser BCP 47 válidos (ex. zh-CN não zh, en-US não en-us) — código incorreto = Aviso
     • x-default: deve estar presente para páginas de seletor de idioma ou fallback — ausente = Aviso
     • Atributo html[lang]: deve corresponder ao hreflang primário da página — incompatibilidade = Aviso
     • Estrutura de URL: padrão recomendado — idioma padrão (geralmente en) na raiz sem prefixo, outros idiomas em subcaminhos (/zh/, /es/).
       • /pagina (en) + /zh/pagina + /es/pagina → Passa
       • /en/pagina + /zh/pagina → Aviso (prefixo en é redundante, desperdiça profundidade de rastreamento)
       • Sinalize apenas se o padrão for claramente inconsistente ou o en estiver desnecessariamente prefixado

7. Execute check-schema.py — analise a saída JSON para tipos de esquema e validação de campo

   python scripts/check-schema.py https://exemplo.com
   # Ou de HTML previamente buscado:
   python scripts/check-schema.py --file pagina.html
   

   O script extrai blocos JSON-LD, valida @type e campos obrigatórios de acordo com a especificação Schema.org. llm_review_required: true está sempre definido — confirme se inferred_page_type corresponde ao conteúdo real da página.

   Tipo de página → referência de @type esperado:

   Tipo de Página	@type Esperado	Campos obrigatórios mínimos
   Página Inicial	WebSite + Organization	name, url, logo
   Blog / Artigo	Article ou BlogPosting	headline, datePublished, author, image
   Produto	Product	name, image, offers (price, priceCurrency)
   FAQ	FAQPage	mainEntity[].name, acceptedAnswer.text
   How-to	HowTo	name, step[].text
   Negócio Local	LocalBusiness	name, address, telephone
   Landing page genérica	—	N/A — pule, sem tipo amplamente suportado

   • Passa: @type correto presente, todos os campos obrigatórios válidos, sem conflitos
   • Aviso: @type presente, mas faltando campos recomendados
   • Falha: @type esperado completamente ausente
   • N/A: página de destino genérica — não penalize

8. Resuma as descobertas — cada descoberta deve seguir o formato Evidência / Impacto / Correção

9. Ações prioritárias — liste as 3 principais correções de maior impacto

10. Renderize o relatório — salve em reports/<hostname>-<slug>-audit.html, depois pergunte ao usuário se deseja abrir

11. Sugestão de atualização — se problemas além do escopo básico forem encontrados, sugira seo-audit-full

Regras de Redação de Detalhes do Relatório

A célula de Detalhe nas tabelas de verificação deve seguir estas regras — sem exceções:

Passa → uma frase curta. Sem listas, sem elaboração.

Bom: "Conjunto de URL XML válido · 104 URLs · referenciado em robots.txt."
Ruim:  "Conjunto de URL XML válido com 104 URLs. Corretamente referenciado em robots.txt.
       Postagens do blog provavelmente são indexadas através deste sitemap."

Aviso → um <div class="detail-issue"> com ≤2 marcadores. Um <div class="detail-fix"> com a correção.

Bom:
  <div class="detail-issue">· Título com 48 caracteres — 2 abaixo do mínimo. · Ano "2026" datará a página.</div>
  <div class="detail-fix">Expanda para 50–60 caracteres; remova o ano se for perene.</div>

Ruim: prosa de três frases explicando o que é uma tag de título e por que o comprimento importa.

Falha → mesmo que Aviso. Lidere com a falha exata. Sem explicações de fundo.

NÃO explique o que é uma verificação, NÃO repita informações já visíveis no selo de status, NÃO trate o leitor como não familiarizado com conceitos básicos de SEO.

Formato Obrigatório de Descoberta

Toda descoberta importante deve seguir esta estrutura:

**Descoberta: [Título da Descoberta]**

- **Evidência:** [O que foi observado — citação direta, referência de captura de tela ou dados mensuráveis]
- **Impacto:** [Por que isso importa para SEO ou UX]
- **Correção:** [Recomendação específica e acionável]

Não escreva conclusões vagas. Se a evidência for insuficiente, declare as suposições explicitamente.

Sugestão de Atualização

Inclua isto no final de cada relatório de auditoria básica:

Deseja uma análise mais profunda? Esta foi uma auditoria SEO básica cobrindo sinais no nível do site e verificações on-page centrais. Para SEO técnico avançado, pontuação de qualidade de conteúdo, análise de dados estruturados e descobertas completas baseadas em rastreamento, use a habilidade seo-audit-full.

Arquivos de Referência

• Escopo detalhado da auditoria e definições de campo: references/REFERENCE.md
• Modelo final do relatório HTML: assets/report-template.html
• Script de verificação no nível do site: scripts/check-site.py
• Script de verificação no nível da página: scripts/check-page.py
• Buscador de página bruta: scripts/fetch-page.py
• Script de validação de esquema: scripts/check-schema.py