seo-aeo-audit — Auditoria de SEO + AEO com Plano de Ação

seo-aeo-audit — audite a visibilidade em mecanismos de busca + resposta e entregue um plano

Um único objetivo: examinar um site real, provar o que está errado com evidências e devolver um plano priorizado de mudanças que cubra busca clássica (Google, Yandex, Bing) e mecanismos de resposta (AI Overviews / AI Mode, ChatGPT, Perplexity, Claude, Copilot, Gemini, Alice AI).

Não é função desta skill: escrever o conteúdo, construir as páginas, comprar links. Ela termina em um diagnóstico verificado e um plano executável.

Inegociáveis

1. Evidência ou silêncio. Cada achado carrega: o que foi observado, onde (URL, arquivo:linha, nome do relatório), o valor observado e a data. Nunca relate um achado que você não verificou neste site. "Melhores práticas dizem" não é evidência.
2. Rotule o nível de evidência de cada recomendação (veja references/evidence-tiers.md): CONFIRMED (documentado pelo mecanismo ou reproduzido neste site) · STUDY (dados publicados de vários sites) · FIELD (relato de caso único) · HYPOTHESIS. Nunca deixe uma HYPOTHESIS superar um bloqueador CONFIRMED.
3. Diagnostique antes de prescrever. Nenhuma correção entra no plano até que sua causa seja localizada. "Adicionar schema" não é um diagnóstico.
4. Recuse a lista de mitos. Veja "Proteção contra mitos" abaixo — recomendar esses itens desperdiça o orçamento do cliente e é um defeito, não um diferencial.
5. Nunca recomende táticas enganosas. Cloaking, redes de consenso fabricadas, manipulação de avaliações, abuso de remoção de concorrentes e falsificação de sinais de clique ficam fora do plano. Eles aparecem nesta skill apenas em references/threats-and-defense.md, como coisas a detectar e se defender.
6. Declare o que você não pôde verificar. Uma falta de login no GSC é uma lacuna no relatório, não uma omissão silenciosa.
7. Nunca misture medido com assumido. Quando um entregável carrega ambos — um CSV de link building sempre carrega — uma coluna source os separa e as células de volume de uma linha não medida permanecem em branco, não zero. Um 0 é lido como "medido, sem demanda"; em branco é lido como "ninguém verificou". A distinção importa mais em trabalhos que outros executam com um orçamento.
8. Conheça o ponto cego de cada instrumento e diga-o na saída. As regras 1 e 7 governam o que você escreve; elas não veem uma ferramenta que combina ou omite antes de você olhar. Duas chegam constantemente. Uma busca estática não pode ver JSON-LD que o CMS injeta com JavaScript, então "nenhum schema encontrado" é um falso achado em qualquer site Yoast/RankMath/AIOSEO — scripts/page_audit.py imprime a ressalva ao lado de cada inventário de schema, e a ausência só é relatável após uma verificação de renderização. GA4 com modelagem de consentimento retorna comportamento observado e estimado dentro de um número — veja references/measurement.md J1 para as três condições de ativação, o indicador visível e o fallback apenas observado. A regra generaliza: antes que o silêncio de um instrumento se torne um achado, estabeleça que o instrumento poderia ter visto a coisa.

Etapa 0 — Detectar modo, nunca pergunte duas vezes

Inspecione primeiro, depois aja. Nesta ordem:

1. Leia docs/seo/ (ou o caminho que o usuário nomear). Se uma auditoria anterior existir, esta execução é uma re-auditoria: compare-a e lidere com o que mudou.
2. Estabeleça o que você pode alcançar: o site ativo, uma URL de staging, robots.txt, sitemap.xml, acesso ao Search Console / Bing Webmaster / analytics, um export de rastreamento (Screaming Frog, Sitebulb), logs de servidor, quaisquer ferramentas MCP conectadas (Ahrefs, GSC, analytics, um crawler MCP, ou o Prowl MCP para dados competitivos e de demanda em massa sem uma licença por fornecedor). Teste o acesso, não presuma. Um servidor conectado não é um servidor funcional: tiers de API limitam endpoints, e tokens carregam escopos mais restritos do que o painel sugere. Teste a chamada que cada fonte está lá para fazer antes de planejar em torno dela, e registre o que voltou — "conectado, mas retorna Plano insuficiente" é um achado que a próxima auditoria precisa.
3. Escolha o escopo com o usuário apenas se a resposta mudar o trabalho: site inteiro, um modelo/seção, uma pergunta ("por que o tráfego caiu em maio"), ou uma extração de link building — alvos, palavras-chave e âncoras para um contratante. Esse é um entregável em vez de um diagnóstico: leia references/linkbuilding.md quando for a solicitação. Funciona com ou sem Search Console.
4. Relate o status em três linhas — entradas disponíveis, entradas faltando, escopo — depois comece. Sugira exatamente uma próxima ação no final de cada execução.

scripts/preflight.py executa a metade automatizável do passo 2 em vez de scripts/preflight.py executa a metade automatizável deste passo e relata em qual portão independente uma falha atingiu — Search Console, a API GSC e PageSpeed todos respondem 403 por razões diferentes. Leia references/preflight.md para exatamente o que ela testa e o que deixa para você (Bing/Yandex, analytics, logs de servidor, exports de rastreamento e cada ferramenta MCP). Um preflight verde não é um passo coberto.

# Plugin Claude Code: ${CLAUDE_PLUGIN_ROOT} expande dentro do conteúdo da skill.
SKILL_DIR="${CLAUDE_PLUGIN_ROOT}/skills/seo-aeo-audit"
# Qualquer outro canal: o diretório base que o harness nomeia quando carrega esta
# skill — o diretório onde este SKILL.md está. Confirme antes de confiar nele:
ls "$SKILL_DIR/scripts/preflight.py"

No such file or directory aqui não é uma funcionalidade faltando e não é uma razão para prosseguir silenciosamente. Significa que os seis instrumentos estão inacessíveis, então cada verificação que eles teriam feito cai para o degrau mais baixo da escada de evidência — e o degrau de um achado limita seu nível. Diga isso no status de três linhas; uma auditoria que silenciosamente se torna manual mudou o que suas conclusões valem (inegociável #6).

python3 "$SKILL_DIR/scripts/preflight.py" --site sc-domain:example.com --origin https://example.com

Regras de acesso: somente leitura por padrão. Nunca envie formulários, solicite indexação, desautorize links ou altere uma propriedade ativa sem aprovação explícita nesta sessão; essas são ações voltadas para o exterior.

Etapa 1 — Linha de base antes de opiniões

Registre, com datas, para que cada alegação posterior possa ser medida contra ela:

• cliques orgânicos / impressões / posição média por país e dispositivo, 12 meses (GSC + Bing), e a janela de queda ou platô, se houver;
• contagens de URLs indexadas vs publicadas por template (site: é um teste de cheiro, o relatório de Páginas do GSC é o número);
• as 20 principais páginas de receita ou conversão e suas posições atuais;
• linha de base de superfície de IA: execute o conjunto de prompts de marca e categoria de references/aeo-geo.md contra cada mecanismo que você puder alcançar e registre as respostas na íntegra;
• quais rastreadores de IA realmente buscam o site (logs de servidor; DNS reverso confirmado para filtrar falsificadores) e quais referenciadores de IA aparecem no analytics;
• a linha do tempo de atualizações: alinhe por data cada mudança na curva com references/algorithm-updates.md antes de formar qualquer hipótese sobre uma causa.

Quando não houver acesso primário algum, diga isso no status de três linhas e recorra ao que um índice de terceiros pode estabelecer: para o que o domínio classifica hoje, quão grande é seu perfil de links em relação a um conjunto competitivo dimensionado e se suas frases-alvo carregam demanda mensurável (references/prowl-mcp.md). Essa linha de base é limitada a STUDY e não pode responder "por que esta página não está indexada" — mas é suficiente para diferenciar um início frio de um declínio, e esses precisam de planos opostos.

Se o site alegar uma queda de tráfego, primeiro separe falha de relatório de falha de classificação: um relatório GSC congelado fixa cliques em uma data enquanto um hit real continua produzindo novos pontos de declínio. Verifique sessões do GA4, logs de servidor e um rastreador de classificação independente antes de diagnosticar uma causa algorítmica.

Etapa 2 — As dez trilhas

Execute cada trilha que estiver no escopo. Cada uma tem seu próprio arquivo de referência com as verificações concretas, os problemas atuais de 2026 e as evidências a capturar.

#	Trilha	Responde	Referência
A	Acesso e economia de indexação	Os bots podem buscar, renderizar e pagar por isso? Onde o orçamento de rastreamento é queimado?	technical-checks.md
B	Canonicalização e duplicação	Qual URL é canônica, e o mecanismo concorda — incluindo hreflang?	technical-checks.md
C	Arquitetura e capital de links	As páginas de dinheiro recebem autoridade, profundidade e frequência de rastreamento?	architecture-and-equity.md
D	Intenção e ajuste ao SERP	Cada página corresponde ao SERP, e as páginas canibalizam?	intent-and-content.md + onpage-checks.md
E	Valor do conteúdo	Uma razão para classificar que a IA não pode replicar?	intent-and-content.md + ranking-model.md
F	Extraibilidade e AEO/GEO	Um mecanismo de resposta pode recuperar, ler e citar?	aeo-geo.md
G	Entidade e consenso de marca	Os modelos conhecem a marca, consistentemente, e a nomeiam?	entity-and-brand.md
H	Experiência, conversão e atribuição	Tarefa concluída aqui ou rejeitada? Convertido e medido?	experience-signals.md + demand-and-conversion.md
I	Risco e ameaças	Penalidades, sequestros, injeções, remoções.	threats-and-defense.md
J	Medição	Alguém será capaz de dizer se o plano funcionou?	measurement.md

Discover não é uma das dez trilhas e não faz parte da trilha A. Ele tem sua própria passagem de classificação, seu próprio portão (duas metatags, sem as quais nenhum cartão é renderizado de forma alguma) e sua própria curva de atualização, então um site onde Discover é uma fonte de tráfego material precisa que references/discover.md seja executado como uma décima primeira passagem — e um site onde não é pode ignorá-lo completamente. Verifique o relatório Discover do GSC antes de decidir: a referência foi enviada acessível apenas a partir da lista na parte inferior deste arquivo, o que significava que um agente trabalhando as trilhas em ordem nunca a abriu.

Antes de qualquer diagnóstico de declínio, execute o protocolo de alinhamento de data e resposta de atualização em references/algorithm-updates.md — "uma atualização principal nos atingiu" não é um achado, e metade das interrupções documentadas do GSC coincidiram com lançamentos.

Cada trilha tem duas metades: o trabalho diagnóstico (o que está errado e por que) e uma varredura mecânica para completude — technical-checks.md §A3 para trilhas A/B e onpage-checks.md para D/E. Execute o diagnóstico primeiro; a varredura depois captura as falhas chatas, e apenas itens da varredura com um impacto observável são promovidos para a tabela de achados.

A ordem importa. Um bloqueador da trilha A (site não buscável, noindex na fonte pré-renderização, ação manual) torna todos os outros achados irrelevantes — uma ação manual é um multiplicador binário: nada que você melhora conta até que seja removido. Trabalhe A → B → C antes de gastar tempo em F/G.

Escada de evidência — o roteamento completo está em references/tooling.md; é ordenado por força da evidência, não conveniência: logs de servidor → Search Console / Bing / Yandex → rastreamento completo → dados de desempenho de campo → índices de terceiros → busca manual e DevTools. Use o degrau mais alto que você pode realmente alcançar para cada verificação e diga no relatório em qual degrau um achado se baseia. Uma auditoria apenas pública sem acesso à propriedade é um trabalho válido, mas seus achados de indexação e consulta são inferências, não observações, e são classificados de acordo.

Os seis scripts agrupados — preflight.py, gsc_pull.py, page_audit.py, url_inspection.py, sitemap_audit.py, psi_pull.py — coletam a metade mecânica de cada trilha. Leia references/scripts.md para invocação, flags, cotas e os limites por script.

Quatro armadilhas que decidem se um achado é real:

• O inventário de schema de page_audit.py lê apenas HTML renderizado pelo servidor. Onde um CMS injeta JSON-LD com JavaScript, um inventário vazio não é evidência de marcação ausente (inegociável #8).
• --format json emite um array, um objeto por página, mesmo para uma URL: indexe data[0].
• Uma resposta cortada por --max-bytes descarta todos os achados baseados em contagem em vez de publicar um fragmento como uma medição.
• Cada achado emitido carrega um nível de evidência e também uma gravidade, e apenas o nível entra na fórmula de triagem. Gravidade é o quão alto um achado é; o nível é o que o suporta. url_inspection.py pergunta ao índice em vez de inferir de uma busca, que é a única maneira de um achado atingir CONFIRMED — a uma cota de 2000/dia e 600/minuto por propriedade, então amostre uma URL por template mais as páginas sobre as quais um achado é realmente.

Etapa 3 — Triagem

Pontue cada achado, depois classifique. Não apresente uma lista não classificada.

prioridade = (impacto × confiança) / esforço

• impacto 1–5: páginas de receita bloqueadas = 5; um vazamento em todo o template = 4; uma única página informacional = 1. Estime em termos de tráfego ou receita onde a linha de base permitir.
• confiança: CONFIRMED 1.0 · STUDY 0.7 · FIELD 0.4 · HYPOTHESIS 0.2.
• esforço 1–5 em dias de engenharia, contando o processo de lançamento, não apenas a edição.

Agrupe a saída em quatro buckets, nesta ordem:

1. Bloqueadores — indexação, penalidades, sequestros, páginas de receita inacessíveis.
2. Vazamentos — orçamento de rastreamento, capital, canibalização, desperdício de orçamento de leitura.
3. Ganhos — ajuste de intenção, ganho de informação, extraibilidade, consenso de entidade.
4. Experimentos — qualquer coisa abaixo de CONFIRMED que mereça um teste A/B em vez de uma implantação. Projete-os de acordo com references/experiments.md; nunca implemente uma HYPOTHESIS