Skip to content

About

SEO, pesquisa web e conteúdo para o mercado brasileiro no Claude Code. Avalia, corrige e verifica: auditoria ao vivo, Core Web Vitals, Search Console, JSON-LD validado, copy pt-BR.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

9 Commits

Folders and files

Repository files navigation

web-search — agência de SEO, pesquisa e conteúdo para o Brasil (Claude Code)

Skill + agentes para Claude Code que pesquisam, avaliam, corrigem, revisam e verificam SEO com foco no mercado brasileiro — Google Brasil, pt-BR, WhatsApp, LGPD, dado oficial (IBGE/gov.br) e AI Overviews.

Não é um agente que faz tudo: é um atendimento que mede o esforço da tarefa e aciona o squad certo. Cada tópico tem especialista, revisor e finalizador — produz, audita contra um gate objetivo, corrige em até duas rodadas e entrega com prova.

Não é só doutrina: acompanha 11 scripts Python (stdlib apenas, zero dependência) que medem site ao vivo, leem Core Web Vitals reais, transformam export do Search Console em fila de trabalho, medem prontidão para citação por IA, aplicam correções on-page determinísticas e registram a proveniência da entrega.

Junto vão duas skills vendorizadas que fecham a peça antes de publicar: humanizer revisa a naturalidade contra 35 padrões de escrita de IA, e clean-user-facing-text remove marca d'água em Unicode invisível.


Instalação

Como plugin (recomendado)

Dentro do Claude Code:

/plugin marketplace add pedrenrick/web-search
/plugin install web-search@claude-web-search

O sufixo @claude-web-search é o nome do marketplace, não do repositório. Ele continua o mesmo depois da renomeação do repo: mudá-lo quebraria quem já adicionou o marketplace com esse nome.

Manual

git clone https://github.com/pedrenrick/web-search.git
cd web-search
./install.sh          # copia para ~/.claude/skills e ~/.claude/agents

Requisito: Python 3.9+ (só biblioteca padrão).


Uso

/web-search audita https://cliente.com.br e corrige o que der
/web-search pesquisa quantos MEIs existem no Brasil, com fonte oficial
/web-search escreve artigo para "como abrir MEI em 2026"
/web-search reescreve a copy da landing de contabilidade para clínicas
/web-search reescreve este artigo: SEO, copy e revisão de naturalidade

Para trabalho longo (sitemap inteiro, centenas de URLs) ou entregável que sai para o cliente, delegar ao atendimento — ele decide o esforço e monta o squad:

usa o agente web-search para auditar o sitemap inteiro de cliente.com.br
usa o agente web-search para reescrever /blog/como-abrir-mei e entregar revisado

Como agência

A primeira decisão de toda tarefa é quanto esforço ela merece. Subir nível sem necessidade queima contexto; descer demais entrega trabalho que não passa no gate.

Nível Aciona Gatilho Exemplo
T0 resposta inline um fato, uma busca "quantos MEIs existem hoje?"
T1 referência + script tarefa mecânica, reversível "roda auditoria em cliente.com.br"
T2 seo-especialista entregável fechado, uso interno brief de pauta, lista de keyword
T3 squad completo entregável que sai para leitor artigo, landing, auditoria entregue
T4 vários squads em sequência escopo que atravessa tópicos site inteiro, calendário trimestral

Texto que vai para leitor nunca é T0 nem T1: a etapa de naturalidade e a camada A de Unicode são obrigatórias, e as duas moram em T3.

Os doze squads

Squad Tópico
Pesquisa achar e validar fato, fonte primária brasileira
SERP & Keyword intenção, keyword, SERP features, canibalização, GEO/AEO
Técnico rastreio, indexação, CWV, schema, mobile, segurança
On-page title, meta, heading, imagem, link interno, pilar-cluster
Conteúdo artigo, case, listicle, e-mail, roteiro, refresh
Copy headline, estrutura de página, CTA, objeção, prova
Naturalidade 35 padrões de escrita de IA, camada A de Unicode
GEO & AEO ser a resposta e ser citado por IA, acesso de rastreador de IA
Distribuição redes, WhatsApp, horário BRT, calendário, repurposing
Escala lote, sitemap inteiro, programático, CI, multi-site
Migração troca de domínio ou CMS, mapa de 301, monitoramento pós-subida
Proveniência trilha de fonte, revisão, aprovação e publicação

A especialidade não está num agente por squad: está na referência de cada tópico. Três papéis genéricos recebem o squad e a referência no briefing.

O ciclo

briefing → ESPECIALISTA (produz em arquivo) → REVISOR (audita contra o gate)
    APROVADO  → FINALIZADOR (verifica, prova, entrega, registra)
    CORRIGIR  → volta ao especialista — no máximo 2 rodadas
    BLOQUEADO → para e escala ao humano

O revisor não tem permissão de edição. Aponta, não conserta — revisor que conserta deixa de revisar. Postura adversarial: na dúvida entre aprovado e corrigir, corrige. Terceira reprovação pelo mesmo motivo é problema de briefing, não de execução: escala em vez de insistir.

Cada squad aprova contra critério objetivo, verificável por comando: seo_audit_live.py sem CRÍTICO, seo_optimizer.py ≥ 75, inspect_text.py com suspicious_total: 0, SERP real registrada com data, amostra de 10% revisada à mão em lote.

Aprendizado

O que o usuário corrige uma vez não se corrige de novo na semana seguinte. O estado mora no projeto, não na sessão:

.web-search/
├── contexto.md       cliente, público, voz, restrição, stack
├── aprendizado.md    regra aprendida, com data e origem
├── baselines/        JSON de auditoria e CWV, por data
└── entregas/         arquivos produzidos, por data

Entra no aprendizado.md só o que o usuário corrigiu (uma vez basta) ou o que o revisor reprovou pelo mesmo motivo em duas entregas. Nunca segredo: senha, token e chave de API não vão para arquivo de contexto.

Caveman interno, zero impacto no resultado

A conversa entre os papéis é comprimida. O entregável não é — e a garantia é estrutural, não é promessa: o especialista grava o resultado em arquivo e o handoff carrega só o caminho e os achados. Compressão não tem como encostar no que está no arquivo.

briefing → sq:on-page | arq: artigo-mei.md | kw: "como abrir mei" | gate: §10 + optimizer>=75
achado   → artigo-mei.md:12 CORRIGE title 71 chars > 60. cortar " o guia definitivo".
veredicto→ CORRIGIR 3 itens (2 CORRIGE, 1 NOTA). 0 BLOQUEIA.

Teste da garantia: o arquivo entregue sai byte a byte igual com o modo caveman ligado ou desligado. Se a compressão mudou uma vírgula do entregável, é defeito, não estilo.


O que faz

Avaliar

Script O que mede
seo_audit_live.py URL ao vivo ou site inteiro (--sitemap, --crawl, --file): status, redirect, title/meta, canonical, robots, hierarquia de heading, imagem (alt/dimensão/formato/lazy), Open Graph, JSON-LD com os campos obrigatórios do Google, links internos e quebrados, peso, compressão, hreflang. Nível de site: robots.txt, sitemap, soft 404, HTTP→HTTPS, title duplicado, página órfã. Sai com código 1 quando há problema crítico — encaixa em CI.
cwv_check.py Core Web Vitals reais via PageSpeed Insights: campo (CrUX, usuário real) + laboratório, elemento de LCP identificado e oportunidades ordenadas por ms economizado, cada uma com ação concreta.
gsc_analyze.py Export CSV do Search Console → plano priorizado: ganhos rápidos (posição 5-20), CTR abaixo do esperado para a posição, canibalização, impressão sem clique, decaimento vs. período anterior. Lê CSV pt-BR (; e 0,35%).
seo_checker.py Repo local (HTML/JSX/TSX/Vue) antes do deploy.
geo_check.py Prontidão para ser citado por IA. Nível de site: quais rastreadores de IA o robots.txt libera, bloqueia ou nem declara, e token morto (Claude-Web não existe mais). Nível de página: resposta extraível abaixo de H2-pergunta, data visível, autor, schema, entidade por extenso, dado com atribuição, fonte vaga. Sai com código 1 quando um rastreador de busca de IA está bloqueado.
serp_fetch.py SERP determinística do Google Brasil (gl=br, hl=pt-BR) via Bright Data ou SerpApi: posição exata, features da página, onde o domínio alvo aparece, domínio com mais de um resultado. Provedor pago; sem chave, diz o que falta e não inventa resultado.
proveniencia.py Trilha append-only com cadeia de hash: fonte usada, revisão, aprovação e sha256 do que foi publicado. verify detecta adulteração e arquivo editado fora do fluxo; report gera extrato para cliente ou conselho. Recusa registrar credencial, por nome e por forma.

Corrigir

Script O que corrige
fix_onpage.py Correções determinísticas, dry-run por padrão: lang, viewport, charset, canonical autorreferente, Open Graph derivado do title/description existentes, twitter:card, defer em script, loading=lazy/decoding=async fora da dobra, remoção de lazy no provável LCP + fetchpriority="high", rel=noopener. Idempotente, com --backup e --only.
schema_gen.py Gera JSON-LD de 14 tipos (Article, LocalBusiness, Product, BreadcrumbList, Event, VideoObject, Person, Service…) validado contra os campos obrigatórios do Google. Avisa quando o tipo já não rende rich result (FAQPage, HowTo). --validate-url audita o schema que está no ar.
seo_optimizer.py Score SEO 0-100 de um texto, densidade, estrutura e meta sugerida — com stopwords PT-BR.
brand_voice_analyzer.py Perfil de voz, legibilidade e consistência, com léxico PT-BR.

Fronteira de automação (explícita)

  • Script corrige o que é derivável com segurança do que já existe.
  • Agente escreve e o humano revisa: title, meta description, H1, alt, conteúdo, FAQ, copy.
  • Nunca fabricado: alt de imagem, estatística, depoimento, avaliação, credencial.
  • Time de infra: CDN, cache, build de imagem, remoção de script de terceiro — a skill recomenda e verifica.

Loop operacional

BASELINE (medir e salvar JSON) → DIAGNOSTICAR (impacto × esforço)
   → CORRIGIR (script → editorial → infra) → VERIFICAR (re-medir e comparar)
   → MONITORAR (7 / 30 / 90 dias)
S="$(dirname "$(find ~/.claude -path '*/web-search/scripts/seo_audit_live.py' | head -1)")"

# baseline
python3 $S/seo_audit_live.py --sitemap https://site.com.br/sitemap.xml --limit 200 --json base.json
python3 $S/cwv_check.py --file urls.txt --strategy mobile --json cwv.json
python3 $S/gsc_analyze.py gsc.csv --anterior gsc-90d.csv --json fila.json

# corrigir (branch antes; dry-run primeiro)
python3 $S/fix_onpage.py ./src
python3 $S/fix_onpage.py ./src --apply --backup --base-url https://site.com.br
python3 $S/schema_gen.py article --title "..." --url ... --image ... --author "..." --published 2026-08-01

# verificar
python3 $S/seo_audit_live.py --file urls.txt --json depois.json

Gate de CI (falha o build quando há crítico):

- run: python3 skills/web-search/scripts/seo_checker.py ./src
- run: python3 skills/web-search/scripts/seo_audit_live.py --file urls-criticas.txt --no-site

Foco Brasil

  • Protocolo de 3 fontes independentes, fonte primária e data de acesso obrigatórias
  • Fontes oficiais: IBGE, gov.br, Banco Central, Receita, Sebrae, conselhos de classe
  • Busca sem acento e com erro de grafia (como o brasileiro realmente digita)
  • Sazonalidade: Black Friday, Dia das Mães, IR, 13º, volta às aulas
  • WhatsApp como canal nº 1 — Open Graph tratado como item crítico
  • Baseline de performance: Android intermediário em 4G · CDN com PoP em São Paulo (GRU)
  • LGPD, CDC, CONAR e restrição de publicidade de CFM/CRP/OAB/CREA
  • GEO/AEO: como ser citado em AI Overview, ChatGPT, Perplexity e Gemini
  • Fórmulas de headline, CTA e templates de conteúdo em pt-BR

Aparecer em IA — e deixar o robô entrar

Metade do trabalho de GEO é conteúdo. A outra metade é uma linha de robots.txt que ninguém leu.

python3 $S/geo_check.py --robots https://cliente.com.br

Ele separa o que a maioria mistura: rastreador de busca de IA (bloquear tira o site da citação) e rastreador de treino (bloquear é decisão de negócio, sem efeito em ranqueamento).

Token Empresa Papel
OAI-SearchBot · Claude-SearchBot · PerplexityBot OpenAI · Anthropic · Perplexity busca — bloquear tira a citação
GPTBot · ClaudeBot · Google-Extended OpenAI · Anthropic · Google treino — decisão de negócio
ChatGPT-User · Claude-User · Perplexity-User — disparado por pessoa; robots.txt não garante

Nomes conferidos na documentação de cada empresa em 26/08/2026 — fontes em references/geo-aeo-brasil.md. Duas coisas que se veem em auditoria e estão erradas: Claude-Web não existe mais (regra com esse nome é linha morta), e bloquear Google-Extended não afeta posição no Google Search.

Rodado no nytimes.com, o script acha os três rastreadores de busca bloqueados e três tokens mortos no robots.txt — inclusive Claude-Web.


Etapa de naturalidade

Artigo otimizado não é artigo pronto. Antes de publicar entra uma etapa de revisão que a maioria dos fluxos de SEO pula: tirar do texto o que faz ele soar a modelo de linguagem.

O motor é a skill humanizer, que cataloga 35 padrões derivados de Wikipedia: Signs of AI writing. O catálogo é em inglês; skills/web-search/references/naturalidade-ptbr.md traduz cada padrão para como ele aparece em português — "desempenha um papel fundamental", "…, garantindo mais eficiência", "estudos apontam", "Vale destacar que", Title Case em heading, regra de três em série.

Use a skill humanizer no arquivo artigo.md, em modo arquivo.
Contexto: pt-BR, artigo de SEO, keyword principal "como abrir MEI".
Não alterar: title, meta description, URL, âncora de link interno, entidade
nomeada, número, data, valor em real, citação, fonte, JSON-LD, bloco de código.
Manter a keyword no H1, no primeiro parágrafo e em ao menos 2 H2.

Onde a etapa entra:

SERP → escrita/reescrita → on-page → NATURALIDADE → camada A (Unicode) → QA → publicação

Naturalidade antes da camada A por um motivo prático: a reescrita passa por um modelo, e modelo pode introduzir carrier Unicode novo. Limpar antes desperdiça o passo.

A etapa só fecha com três provas, e as três vão na entrega:

Prova Como
SEO intacto seo_optimizer.py antes e depois; queda acima de 5 pontos ou heading sumido pede revisão
Nenhum fato mexido lista de número, data, valor, nome, citação e link antes × depois
Unicode limpo inspect_text.py --json do arquivo final

Falso positivo tem peso igual: citação, nome de órgão, termo técnico, aviso de conselho de classe e disclaimer de LGPD não são reescritos. Um travessão não é sinal de IA — travessão em toda seção é.


Sem marca d'água de IA

Texto gerado por LLM carrega dois tipos de marca. O plugin trata os dois, e o gate bloqueia a publicação enquanto o primeiro existir.

Camada A — Unicode invisível. Zero-width, word joiner, tag chars, variation selector, bidi. Sobrevivem a copy-paste e viajam do modelo direto para o CMS. Detecção e remoção são determinísticas:

C="$(dirname "$(find ~/.claude -path '*/clean-user-facing-text/scripts/inspect_text.py' | head -1)")"
python3 $C/inspect_text.py --json artigo.md                                           # código 1 = sujo
python3 $C/clean_text.py artigo.md -o artigo.clean.md --stats --no-normalize-spaces 2> stats.json
python3 $C/inspect_text.py --json artigo.clean.md > prova.json

--stats sai na saída de erro, não na padrão. NBSP e espaço fino são preservados: têm função tipográfica, não são carrier.

Camada B — assinatura estilística. Não sai com script: é a etapa de naturalidade acima. O checklist está em skills/web-search/references/checklists.md, os padrões em pt-BR em skills/web-search/references/naturalidade-ptbr.md, e o roteiro de reescrita do upstream em skills/clean-user-facing-text/references/writing-in-your-voice.md.

Limite. Isso é higiene de publicação, não burla de disclosure. Trabalho acadêmico, peça jurídica, conteúdo médico regulado e plataforma que exige declaração de IA mantêm a declaração. Camada A é verificável; camada B é melhor esforço — ninguém aqui promete texto "indetectável".

Skills vendorizadas e sincronização

skills/humanizer/ e skills/clean-user-facing-text/ são cópias de terceiro, sob MIT, com o commit de cada uma fixado em vendor/vendors.lock.json (URL, SHA, data e hash de cada arquivo). Não editar essas pastas: a próxima sincronização desfaz. O que é nosso e adapta as duas ao pt-BR mora em skills/web-search/references/naturalidade-ptbr.md.

Skill Origem Papel
humanizer blader/humanizer 35 padrões de escrita de IA — etapa de naturalidade
clean-user-facing-text watermarks-remover camada A — carriers Unicode invisíveis
scripts/sync-vendors.sh --check            # código 1 = algum upstream andou
scripts/sync-vendors.sh                    # sincroniza os dois
scripts/sync-vendors.sh humanizer          # sincroniza um
scripts/sync-vendors.sh --ref SHA humanizer  # fixa em commit ou tag
scripts/test-vendored-skills.sh            # prova que as duas continuam funcionando

A sincronização só troca os arquivos depois de passar pelos portões de auditoria: a licença do upstream continua a que está em vendor/vendors.json, nenhum script Python importa rede, subprocesso ou execução dinâmica, e todos fazem parse. Falhou um, aborta.

O workflow .github/workflows/sync-vendors.yml roda essa verificação toda segunda e abre PR em vez de commitar em main — código de terceiro passa por revisão humana.

Do watermarks-remover vem só a skill clean-user-facing-text, que é autossuficiente (biblioteca padrão do Python). A irmã remove-ai-marks fica de fora de propósito: depende de um serviço HTTP em Docker. Do humanizer vem só o SKILL.md, que é a skill inteira.


Estrutura

skills/web-search/
├── SKILL.md                            roteamento, método, comandos
├── references/
│   ├── pesquisa-web-brasil.md           protocolo de busca, operadores, fontes BR
│   ├── serp-e-ranqueamento-br.md        keyword, SERP features, E-E-A-T, GEO/AEO, backlink
│   ├── seo-tecnico.md                   auditoria, CWV, schema, formato de relatório
│   ├── seo-onpage.md                    title/meta/heading/imagem/link, pilar-cluster, refresh
│   ├── copywriting-conversao.md         headlines pt-BR, estrutura de página, CTA, objeção
│   ├── conteudo-frameworks.md           templates de artigo, case, listicle, vídeo, e-mail
│   ├── distribuicao-brasil.md           WhatsApp, Instagram, YouTube, TikTok/Kwai, LGPD
│   ├── checklists.md                    QA e formato dos entregáveis
│   ├── naturalidade-ptbr.md             35 padrões de IA em pt-BR, falso positivo, guardrail de SEO
│   ├── agencia-squads.md                roteador de esforço, squads, papéis, gates, aprendizado
│   ├── geo-aeo-brasil.md                rastreadores de IA, robots.txt, llms.txt, o que é citado
│   ├── migracao-e-redirect.md           baseline, mapa de 301, homologação, monitoramento
│   └── auditoria-e-proveniencia.md      trilha de fonte, revisão, aprovação, hash do publicado
│   ├── fluxo-avaliacao-correcao.md      loop medir → corrigir → verificar, guardrails
│   └── escala-operacoes.md              lote, sitemap inteiro, SEO programático, CI, multi-site
├── scripts/                            11 scripts Python (stdlib)
└── assets/                             calendário mensal, modelo de contexto do projeto

skills/humanizer/                       vendorizada de blader/humanizer (MIT)
└── SKILL.md · LICENSE · VENDOR.md       35 padrões de escrita de IA

skills/clean-user-facing-text/          vendorizada de guillaumemeyer/watermarks-remover (MIT)
├── SKILL.md · LICENSE · VENDOR.md
├── references/                          watermark-notes, writing-in-your-voice, responsible-use
└── scripts/                             inspect_text.py, clean_text.py, text_unicode.py, common.py

agents/
├── web-search.md                       atendimento: decide o esforço e aciona o squad
├── seo-especialista.md                 produz, sempre em arquivo, com fonte e data
├── seo-revisor.md                      audita contra o gate — sem Write nem Edit, de propósito
└── seo-finalizador.md                  verifica, prova, entrega e registra o aprendizado

scripts/sync-vendors.sh                 sincroniza as skills de terceiro, com auditoria
scripts/test-vendored-skills.sh         teste das skills vendorizadas
vendor/vendors.json                     origem, subdiretório e destino de cada vendor
vendor/vendors.lock.json                commit e hash de cada arquivo vendorizado
CREDITOS.md                             o que vem de fora, de onde e sob qual licença

Agentes e skill não duplicam conteúdo: os agentes são cascas que leem o SKILL.md e a referência do squad. Mudou a referência, mudou o comportamento de todos.


Notas

  • cwv_check.py usa a API pública do PageSpeed Insights. Sem chave funciona, mas a cota anônima é compartilhada e estoura rápido — para lote, defina PSI_API_KEY (chave gratuita).
  • gsc_analyze.py lê export CSV do Search Console (Desempenho → Exportar). Não há integração OAuth.
  • Nada aqui garante posição no Google. Correção técnica se verifica na hora; ganho de ranqueamento leva 2-12 semanas e se comprova com dado do Search Console.
  • Antes de rodar crawler em site de terceiro, tenha autorização e use --delay.
  • serp_fetch.py exige provedor pago (Bright Data ou SerpApi). A chave vai por variável de ambiente, nunca inline no comando. Sem provedor, o WebSearch do agente resolve — declarando na entrega que a posição não foi medida de forma determinística.
  • .web-search/ guarda contexto de cliente e está no .gitignore.
  • Origens e adaptações de terceiro: CREDITOS.md.
  • skills/humanizer/ e skills/clean-user-facing-text/ são código de terceiro sob MIT, de blader/humanizer e guillaumemeyer/watermarks-remover. Copyright e licença acompanham cada cópia.
  • Nenhum detector de IA é confiável em nenhuma direção. A etapa de naturalidade é edição, não promessa de "passar em detector".

Licença

MIT.

skills/humanizer/ é vendorizada de blader/humanizer e skills/clean-user-facing-text/ de guillaumemeyer/watermarks-remover — as duas MIT, com o copyright dos autores originais preservado no LICENSE de cada pasta.

About

SEO, pesquisa web e conteúdo para o mercado brasileiro no Claude Code. Avalia, corrige e verifica: auditoria ao vivo, Core Web Vitals, Search Console, JSON-LD validado, copy pt-BR.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages