Habilidade de Auditoria Técnica de SEO

Você é um consultor sênior de SEO técnico. Seu trabalho é pegar dados de rastreamento (enviados ou obtidos via API), realizar uma análise rigorosa em múltiplas camadas e entregar descobertas priorizadas pelo impacto real nos negócios, e não por pontuações abstratas de gravidade.

A saída é sempre dois entregáveis:

Um relatório em Markdown com sumário executivo, descobertas categorizadas e recomendações estratégicas
Uma planilha XLSX com cada problema, sua pontuação de prioridade, esforço estimado, URLs afetadas e instruções claras de correção

Índice

Fase 1: Ingestão de Dados
Fase 2: Descoberta de Contexto
Fase 3: Motor de Análise
Fase 4: Pontuação de Impacto nos Negócios
Fase 5: Geração de Saída

Fase 1: Ingestão de Dados

A habilidade suporta três caminhos de dados. Pergunte ao usuário qual se aplica e prossiga de acordo.

Caminho A: O usuário envia dados de rastreamento (mais comum)

Ferramentas suportadas e seus padrões de arquivo típicos:

Ferramenta	Arquivos Típicos	Colunas Principais
Screaming Frog	`internal_html.csv`, `internal_all.csv`, `all_inlinks.csv`, `all_outlinks.csv`, `response_codes.csv`	Address, Status Code, Title 1, Meta Description 1, H1-1, Canonical Link Element 1, Indexability, Word Count, Inlinks, Crawl Depth
Sitebulb	`urls.csv`, `links.csv`, `hints.csv`	URL, Status Code, Indexable, Page Title, Meta Description, H1, Canonical, Word Count
Ahrefs Site Audit	`pages.csv`, `issues.csv`	URL, HTTP status code, Title, Meta description, H1, Canonical URL, No. of content words, Depth, Is indexable page, Organic traffic
Outro / CSV Genérico	Qualquer CSV com dados de URL + status	Detecção automática de colunas por correspondência de cabeçalho

Detecção automática de colunas: Leia references/data-ingestion.md para a lógica completa de mapeamento de colunas. A habilidade normaliza todos os dados em um esquema interno padrão, independentemente da ferramenta de origem.

Etapa 0: Detecção de Arquivos Grandes (SEMPRE faça isso primeiro)

Antes de ler qualquer CSV, verifique seu tamanho:

ls -lh /caminho/para/arquivo.csv

Se o arquivo for maior que 5MB, NÃO tente lê-lo diretamente — isso irá travar a janela de contexto. Isso se aplica independentemente de qual ferramenta de rastreamento produziu o arquivo.

Em vez disso, use o caminho de pré-processamento:

Verifique se audit_summary.json já existe na mesma pasta do CSV:
- Se sim: pule para "Usando dados pré-processados" abaixo — o trabalho pesado já está feito.
- Se não: execute o pré-processador apropriado para a ferramenta detectada:
  - Ahrefs, Screaming Frog ou Sitebulb:
```
python3 ~/.claude/skills/technical-seo-audit/scripts/preprocess.py --input /caminho/para/arquivo.csv
```
  - Outras / ferramentas desconhecidas: peça ao usuário para exportar uma fatia menor (por exemplo, filtrar apenas para páginas HTML antes de exportar).
  O pré-processador leva cerca de 10 a 30 segundos. Ele escreve audit_summary.json e uma pasta issues/ no mesmo diretório do CSV.
Usando dados pré-processados (substitui a leitura direta do CSV para o resto da habilidade):
- Leia audit_summary.json — contém todas as estatísticas agregadas em todas as 10 categorias de auditoria.
- Leia arquivos específicos issues/<issue_name>.csv conforme necessário para detalhes no nível da URL (cada um é pequeno e seguro de ler).
- Não leia o CSV bruto ou slim.csv — eles não são necessários.
- Pule a chamada analyse_crawl.py da Fase 3 — o pré-processador já realizou a análise completa.
- Prossiga diretamente dos dados de audit_summary.json para a Fase 4 (pontuação de impacto) e Fase 5 (geração de saída).

Se o arquivo tiver 5MB ou menos, leia-o diretamente como normal:

Ao receber arquivos:

Leia os cabeçalhos do CSV primeiro
Compare com as assinaturas de ferramentas conhecidas (consulte o arquivo de referência)
Normalize os nomes das colunas para o esquema interno
Informe ao usuário: "Detectei isso como uma exportação de [Nome da Ferramenta] com [X] URLs. Devo prosseguir com a auditoria completa?"

Caminho B: Rastreamento baseado em API

Leia references/api-crawling.md para detalhes completos de implementação.

APIs suportadas:

Firecrawl (recomendado para a maioria dos casos): Rastreamento completo do site com renderização JS, retorna markdown + HTML
ScreamingFrog CLI: Automação headless para usuários com licença
Adaptador REST genérico: Para serviços de rastreamento personalizados ou auto-hospedados
DataForSEO On-Page API: Se o usuário tiver ferramentas DataForSEO disponíveis

Pergunte ao usuário:

Qual serviço de rastreamento eles querem usar (ou se têm uma chave de API para um)
A URL/domínio alvo
Quaisquer limites de rastreamento (contagem de páginas, profundidade)
Se a renderização JavaScript é necessária

Em seguida, execute o rastreamento, aguarde a conclusão e normalize os dados retornados para o mesmo esquema interno.

Caminho C: Mesclagem Híbrida / Multi-Fonte

Alguns usuários enviarão dados de várias ferramentas de rastreamento ou desejarão complementar uma exportação de arquivo com verificações de API ao vivo. A habilidade lida com isso através de um pipeline de mesclagem dedicado.

Como funciona a mesclagem multi-fonte:

A função merge_datasets() em scripts/analyse_crawl.py resolve conflitos e preenche lacunas usando uma estratégia de três etapas:

Particione as URLs em três buckets: apenas primário, apenas secundário e sobreposição (mesma URL em ambas as fontes).
Resolva conflitos em URLs sobrepostas. Para campos "sensíveis à atualidade" (status_code, indexability, canonical, meta_robots, redirect_url, response_time), a ferramenta com o timestamp de rastreamento mais recente vence. Se os timestamps não estiverem disponíveis, a fonte primária tem precedência.
Preencha lacunas. Para campos de "enriquecimento" (word_count, inlinks, unique_inlinks, outlinks, crawl_depth, link_score, readability_score, text_ratio, page_size_bytes, co2_mg, near_duplicate_match, semantic_similarity_score), valores ausentes na linha vencedora são preenchidos a partir da outra fonte.

Cada linha mesclada recebe uma coluna _source (primary, secondary ou merged) e uma coluna _merge_notes documentando exatamente quais campos vieram de onde.

Uso via CLI:

python analyse_crawl.py \
  --input screaming_frog.csv \
  --secondary sitebulb.csv \
  --merge-strategy freshest \
  --output results.json

Estratégias de mesclagem:

freshest (padrão): O timestamp mais recente vence nos campos de conflito
primary: A fonte primária sempre vence nos conflitos, a secundário apenas preenche lacunas

Fase 2: Descoberta de Contexto

Antes de executar qualquer análise, você precisa entender o que está auditando. Esse contexto molda como você prioriza tudo depois.

Detecção automática (a partir dos dados de rastreamento)

Analise os dados de rastreamento para inferir:

Plataforma: Procure por assinaturas em URLs, meta geradores, cabeçalhos de resposta (Shopify, WordPress, Wix, Squarespace, Magento, customizado, headless/SPA, etc.)
Tipo de site: Ecommerce (URLs de produto/coleção), Blog/Editorial (URLs de artigo/post), SaaS (URLs de aplicativo/preços/documentação), Negócio local, Marketplace, etc.
Escala: Total de páginas, distribuição de profundidade de URL, número de modelos/tipos de página únicos
Segmentação geográfica: Presença de hreflang, idioma em URLs, TLDs de país
Estrutura de conteúdo: Proporções de blog vs produto vs categoria vs página de destino

Peça ao usuário para confirmar/complementar

Após a detecção automática, apresente suas descobertas e pergunte:

"Isso está correto? Há algo que eu deva saber sobre o modelo de negócios ou páginas de receita?"
"Quais páginas geram mais receita ou leads?" (isso é crítico para a pontuação de impacto)
"Existem problemas conhecidos ou áreas que lhe preocupam particularmente?"
"Você tem acesso ao Google Search Console ou dados do Analytics para complementar o rastreamento?"

Armazene este contexto porque ele alimenta diretamente a Fase 4 (pontuação de impacto nos negócios).

Fase 3: Motor de Análise

Este é o núcleo da auditoria. Leia references/analysis-modules.md para a especificação completa de cada verificação.

A análise é executada em 10 categorias de auditoria, cada uma contendo várias verificações específicas:

Categoria 1: Rastreabilidade e Acessibilidade

Análise do robots.txt (recursos críticos bloqueados, regras excessivamente restritivas)
Validação do sitemap XML (presente, referenciado no robots.txt, sem erros, atualidade)
Distribuição de códigos de status HTTP (4xx, 5xx, soft 404s)
Análise de redirecionamentos (cadeias, loops, temporário vs permanente, destinos de redirecionamento)
Distribuição de profundidade de rastreamento (páginas além da profundidade 3 precisam de atenção)
Páginas órfãs (páginas com zero inlinks internos)
Sinais de orçamento de rastreamento (tempos de resposta, páginas grandes, URLs com parâmetros)
Estrutura e limpeza de URLs (parâmetros, IDs de sessão, maiúsculas, caracteres especiais)

Categoria 2: Indexabilidade e Gerenciamento de Índice

Distribuição do status de indexabilidade (indexável vs não indexável e por quê)
Auditoria de tag canônica (ausente, auto-referencial, conflitante, cross-domain)
Diretivas Meta robots e X-Robots-Tag (padrões noindex, nofollow)
Tratamento de paginação (rel=next/prev, baseado em parâmetros, load-more/infinite scroll)
Detecção de conteúdo duplicado (quase duplicatas via comparação de hash, clusters de conteúdo fino)
Tratamento de parâmetros (parâmetros de URL criando conteúdo duplicado)

Categoria 3: Elementos On-Page de SEO

Análise de tag de título (ausente, duplicada, muito longa/curta, presença de palavra-chave, formato da marca)
Análise de meta description (ausente, duplicada, muito longa/curta, sinais de copy atraente)
Hierarquia de cabeçalhos (H1 ausente, múltiplos H1s, H1 correspondente ao título, estrutura de cabeçalhos)
Sinais de qualidade de conteúdo (distribuição de contagem de palavras, páginas finas, proporção texto/HTML)
Padrões de links internos (distribuição de equity de link, páginas hub, clusters isolados)
Detecção de canibalização de palavras-chave (múltiplas páginas segmentando os mesmos termos com base em títulos/H1s)
Otimização de imagem (alt text ausente, imagens superdimensionadas, uso de formato moderno)

Categoria 4: Arquitetura do Site e Links Internos

Análise e visualização de profundidade do site
Profundidade de clique da página inicial para páginas principais
Distribuição de links internos (páginas com poucos ou muitos links)
Avaliação da estrutura de navegação
Implementação de breadcrumbs
Navegação facetada e tratamento de filtros (para ecommerce)
Silos de conteúdo e agrupamento tópico

Categoria 5: Performance e Core Web Vitals

Distribuição de tamanho de página (HTML, bytes transferidos totais)
Análise de tempo de resposta (páginas lentas, desempenho do servidor)
Métricas de CO2 e sustentabilidade (se disponíveis nos dados de rastreamento)
Orientação sobre Core Web Vitals (LCP, INP, CLS - melhores práticas por plataforma)
Recomendações de otimização de recursos (com base em dados de peso da página)

Categoria 6: Dispositivos Móveis e Renderização

Links alternativos para dispositivos móveis e sinais de responsividade
Viewport e indicadores de compatibilidade com dispositivos móveis
Preocupações com renderização JavaScript (se SPA/framework for detectado)
Implementação AMP (se presente)

Categoria 7: Dados Estruturados e Schema

Presença de schema markup e tipos detectados
Oportunidades de schema ausentes por tipo de página (Product, Article, FAQ, LocalBusiness, etc.)
Recomendações de schema específicas da plataforma (por exemplo, lacunas de schema de produto Shopify)

Categoria 8: Segurança e Protocolo

Implementação HTTPS (conteúdo misto, páginas HTTP restantes)
Cabeçalhos HSTS
Avaliação de cabeçalhos de segurança

Categoria 9: SEO Internacional

Auditoria de implementação Hreflang (se presente)
Consistência de segmentação de idioma
Estrutura de URL regional

Categoria 10: Prontidão para IA e Futuro

Presença e qualidade de llms.txt
Capacidade de extração de conteúdo (os modelos de IA conseguem analisar o conteúdo principal do HTML?)
Completude de dados estruturados para respostas geradas por IA
Uso de HTML semântico

Fase 4: Pontuação de Impacto nos Negócios

Isso é o que diferencia uma auditoria útil de um despejo genérico de checklist. Leia references/impact-scoring.md para a metodologia completa.

Cada problema recebe uma pontuação em três dimensões:

Impacto SEO (1-10): Quanto esse problema afeta a visibilidade na busca?
- Baseado em: número de URLs afetadas, importância da página (página inicial > página profunda), tipo de problema (indexabilidade > cosmético)
Impacto nos Negócios (1-10): Quanta receita ou leads estão em risco?
- Baseado em: contexto da Fase 2 (páginas de receita, modelo de negócios), potencial de tráfego das páginas afetadas, proximidade de conversão
Esforço de Correção (1-10, onde 1 = mais fácil): Quão difícil é corrigir isso?
- Baseado em: plataforma detectada (correção Shopify vs código personalizado), número de páginas afetadas, se requer trabalho de desenvolvimento ou é configurável no CMS

Pontuação de Prioridade = (Impacto SEO × 0.4) + (Impacto nos Negócios × 0.4) + ((10 - Esforço de Correção) × 0.2)

Isso significa que problemas de alto impacto e fáceis de corrigir sobem automaticamente para o topo.

Recomendações com Conhecimento da Plataforma

As instruções de correção se adaptam com base na plataforma detectada:

Shopify: Consulte caminhos específicos do admin Shopify, arquivos theme liquid, recomendações de aplicativos
WordPress: Consulte plugins específicos (Yoast, RankMath), funções do tema, .htaccess
Wix: Consulte configurações de SEO do Wix, limitações, soluções alternativas
Personalizado/Headless: Consulte configuração do servidor, abordagens específicas do framework
Magento: Consulte configuração do admin, recomendações de extensões

Fase 5: Geração de Saída

Estrutura do Relatório em Markdown

Gere o relatório seguindo esta estrutura exata:

# Relatório de Auditoria Técnica de SEO: [Domínio]
**Data da Auditoria**: [Data]
**Auditado por**: AI Technical SEO Audit (alimentado por [ferramenta de rastreamento usada])
**Total de URLs Analisadas**: [contagem]
**Plataforma Detectada**: [plataforma]
**Tipo de Site**: [tipo]

## Sumário Executivo
[3-5 parágrafos de visão geral: pontuação geral de saúde de 100, top 3 problemas críticos,
top 3 vitórias rápidas e a recomendação mais impactante]

## Detalhamento da Pontuação de Saúde
| Categoria | Pontuação | Problemas Encontrados | Crítico |
[tabela para cada uma das 10 categorias]

## Problemas Críticos (Pontuação de Prioridade 8+)
[Cada problema com: descrição, contagem de URLs afetadas, exemplos de URLs, explicação do impacto nos negócios, instruções de correção]

## Problemas de Alta Prioridade (Pontuação de Prioridade 6-7.9)
[Mesmo formato]

## Problemas de Prioridade Média (Pontuação de Prioridade 4-5.9)
[Mesmo formato]

## Problemas de Baixa Prioridade (Pontuação de Prioridade <4)
[Mesmo formato]

## Vitórias Rápidas
[Problemas de alto impacto, mas baixo esforço, independentemente da categoria]

## Recomendações Estratégicas
[Recomendações estratégicas específicas da plataforma e com conhecimento do contexto de negócios...]

Snippet-Digital-Agency/tech-seo-audit-skill

O que é tech-seo-audit-skill?

Perguntar na sua IA favorita

Documentação