Heraud SEO
O heraut (arauto) é aquele que torna um domínio conhecido no mundo. Quando ninguém o ouve, esta skill investiga o porquê, com provas para cada afirmação, e retorna um plano que o proprietário pode atacar em ordem.
Ela surgiu de um caso real: um site com 58 000 URLs e 1 000 artigos gerados, um piloto de conteúdo gastando dinheiro todos os dias, zero impressões no blog. A resposta não estava onde o piloto procurava (reescrever páginas), mas na qualidade geral do site, autoridade e demanda. O método abaixo é construído para encontrar esse tipo de resposta, em vez de confirmar a primeira hipótese.
As regras
- Apenas leitura, em todos os lugares. Nenhuma alteração de produção, nenhuma escrita no banco de dados, nenhuma reinicialização, nada submetido ao Google (nenhuma solicitação de indexação, nenhum sitemap adicionado ou removido). A investigação descreve; o plano é aplicado depois, uma alteração decidida de cada vez.
- Prova para cada afirmação. Comando, número, data, arquivo. Marque o que é MEDIDO e o que é SUPOSTO. Uma amostra não é uma contagem: forneça
n. - Seja gentil com o site. Uma requisição de cada vez, uma pausa de pelo menos 1,5 s (
politesse.delai_s). Servidores pequenos sofrem durante auditorias. - APIs pagas com limite.
budgets.dataforseo_usdebudgets.perplexity_usdsão respeitados pelos scripts antes de cada chamada; cada custo é registrado. Relate o total gasto. - Nenhum segredo em nenhuma saída. Nomeie onde uma chave reside, nunca seu valor. Scripts leem chaves do ambiente ou de arquivos env nomeados na configuração.
Onde as coisas estão
Scripts em scripts/ (normalmente ~/.claude/skills/heraut-seo/scripts), apenas biblioteca padrão Python, openssl para tokens do Google. Cada script aceita --config <site.json> --dossier <pasta da investigação> e escreve CSV e JSON lá, além de um resume.json para ler primeiro.
| Script | Trilha | O que faz |
|---|---|---|
sitemap.py | código | árvore completa do sitemap, cada URL com tipo e idioma, honestidade lastmod, duplicatas |
gsc.py performance | 16 meses por mês e tipo de página, 28 dias vs anterior, consultas, países, seções | |
gsc.py sitemaps | sitemaps submetidos, erros, pendentes, última leitura pelo Google | |
gsc.py echantillon / inspecter / analyser | Inspeção de URL estratificada (cota de 2.000/dia, retomável), cobertura por tipo, movimento desde execução anterior | |
ga4.py | canais ao longo de um ano, Google orgânico antes e agora, assistentes de IA, parcela robótica | |
pages.py | código | leitura na página de uma amostra: lang, canonical, hreflang, robots, palavras, JSON-LD, links para o blog, Googlebot vs navegador |
logs.py | servidor | Googlebot real (verificado por DNS) por dia, por tipo, desperdício, tempos de resposta, primeira visita de URLs seguidas |
ttfb.py | servidor | tempo até o primeiro byte por tipo, quente, frio e origem |
dataforseo.py | externo | SERPs reais, palavras-chave ranqueadas, backlinks do site e concorrentes, volumes, bilan |
perplexity.py | externo | pesquisa aprofundada datada e com fontes (Agent API, effort) |
A investigação, passo a passo
0. Enquadramento (10 minutos, com o proprietário se necessário)
- Escreva a pergunta do proprietário em suas próprias palavras e os sintomas com números (impressões, cliques, artigos publicados, dinheiro gasto).
- Descubra o que já é conhecido: auditorias anteriores, anotações, o pipeline de conteúdo e seu banco de dados. Trate como hipóteses a verificar, não como fatos a copiar.
- Construa o arquivo do site a partir de
config.example.json: domínio, sitemap, idiomas, tipos de página como regex de caminho (a parte mais importante: cada contagem é por tipo), seções a seguir (o blog), propriedade do Search Console, ID do GA4, caminho da chave da conta de serviço, mercados (códigos de localização DataForSEO), 3 a 6 concorrentes, 15 a 30 consultas reais que as pessoas digitariam, orçamentos. - Verifique o acesso antes de começar:
gsc.py sitemapsresponde, GA4 responde, os logs são legíveis (geralmente apenas por root e pelo grupoadm: peça ao proprietário, nunca contorne uma recusa).
1. Quatro trilhas em paralelo
Crie a pasta enquete-YYYY-MM-DD/ ao lado dos outros arquivos de auditoria do site, escreva BRIEF.md lá a partir de references/brief.md, então lance quatro investigadores (subagentes) de uma vez, cada um com o resumo e seu arquivo de trilha. Cada um escreve volet-<trilha>.md com um resumo de 10 linhas no topo e seus dados brutos ao lado.
| Trilha | Arquivo | Pergunta chave |
|---|---|---|
| references/track-google.md | O Google conhece as páginas, as rastreia, as mantém? Está melhorando ou piorando? | |
| Servidor | references/track-server.md | O Googlebot real vem, o que ele lê, algo está desacelerando ou bloqueando? |
| Código e conteúdo | references/track-code-content.md | O que o Google encontra quando lê o site: quantas páginas, quão finas, quão ligadas, quão honestas? |
| Externo | references/track-outside.md | Quem vence as pesquisas reais, com que autoridade, e há demanda para o que o site escreve? |
Execute sitemap.py primeiro (os outros amostram a partir dele), depois as trilhas. gsc.py inspecter pode levar horas em uma amostra completa: execute em segundo plano.
2. Síntese
Leia os quatro relatórios, então construa a resposta com references/cause-tree.md: ele lista as causas vistas na prática, a medida que confirma ou descarta cada uma, e as armadilhas (uma auditoria técnica que volta limpa não significa que o site está bem).
Escreva o relatório seguindo references/report.md: resposta curta primeiro, situação, complicação, questão, árvore de causas com as evidências em cada ramo, por que o programa atual não funciona, o plano em fases com um "pronto quando" para cada etapa, KPIs em 30, 60, 90 dias, decisões para o proprietário, limites da investigação, fontes. Publique como uma página quando a sessão permitir (privada por padrão), caso contrário como um arquivo HTML.
3. Entrega
- Forneça ao proprietário o link, o diagnóstico central em cinco linhas, o custo da investigação, o que não pôde ser medido.
- Então as decisões, uma de cada vez, cada uma com o fato por trás e uma recomendação. Aplique cada etapa decidida antes de perguntar a próxima.
- Salve o veredito e a regra operacional que ele implica (por exemplo "nenhum novo conteúdo até que as páginas principais sejam indexadas") onde o projeto mantém sua memória.
Executando em outro servidor ou site
Instale a skill na máquina que tem o acesso (chave do Search Console, logs), copie config.example.json para a pasta do site, preencha-o, execute os passos 0 a 3. Mantenha uma pasta por data de investigação para que a próxima execução possa comparar: gsc.py analyser --avant <old inspection.jsonl> mostra URL por URL o que entrou ou saiu do índice.
Reexecute a investigação 60 a 90 dias após o início do plano. Entre as execuções, uma inspeção rotativa diária de 50 a 100 URLs é a maneira mais barata de ver o índice se mover.
O que esta skill não faz
Ela não altera o site, escreve conteúdo, solicita indexação ou compra links. Ela não julga o produto ou o modelo de negócio, apenas se a pesquisa pode trazer pessoas para ele. Pontuações de ferramentas de SEO (rank, spam score, tráfego estimado) são modelos, não medidas: diga isso ao citá-las.