Dá para montar um agente de SEO no Claude Code? O que ele consegue fazer no seu projeto

Fala aí, beleza? "Agente de SEO" é uma daquelas promessas que chegam embaladas em ranqueamento automático, e não é bem isso que acontece quando o agente passa a morar dentro do seu repositório

O Claude Code enxerga o código do site: o arquivo que monta o <title>, o template que deveria ter meta description, a pasta de rotas, o sitemap versionado junto com o projeto

O que ele não enxerga por padrão é o painel: posição, clique, impressão, sessão

E é exatamente essa fronteira que separa um agente útil de um agente que inventa número…

O que é tarefa de código e o que exige ferramenta externa

Antes de criar qualquer arquivo, vale desenhar as duas colunas na cabeça

Uma coisa é auditar o que está escrito no repositório, outra é consultar o que só o Google sabe

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Tem um caso no meio do caminho que confunde bastante: o WebFetch

Ele é uma das ferramentas nativas do Claude Code (a lista tem Read, Write, Edit, Glob, Grep, Bash, WebFetch e Task, entre outras) e funciona recebendo uma URL e um prompt

Aí ele busca a página, converte o HTML em Markdown e roda o teu prompt em cima desse conteúdo usando um modelo pequeno e rápido

Se liga no detalhe que muda tudo: o Claude recebe a RESPOSTA desse modelo auxiliar, não a página crua

Ou seja, dá pra pedir uma leitura da página publicada, mas isso não é o mesmo que inspecionar o HTML byte a byte, e continua não sendo dado de busca

O que você precisa antes de criar o agente

Nada de PC da Nasa aqui, a lista é curta

• Claude Code instalado e rodando na pasta do projeto, porque o agente vai trabalhar em cima dos arquivos que estão ali
• A decisão de escopo: subagentes ficam em .claude/agents/ (escopo do projeto) ou em ~/.claude/agents/ (escopo do usuário, vale em todos os projetos)
• Saber onde o teu stack gera head, rotas e metadados, porque é pra lá que o agente vai olhar

Sobre o escopo, a regra prática é simples: auditoria com regra específica daquele site fica em .claude/agents/, dentro do repo, versionada com o time

Agente genérico que tu quer usar em qualquer projeto vai pra ~/.claude/agents/

E um aviso de estado atual, pra não perder tempo: o wizard interativo do comando /agents foi removido do Claude Code e não foi restaurado, existe até issue aberta pedindo o retorno

Então hoje o caminho é pedir pro próprio Claude criar o agente, ou editar o arquivo direto na pasta

O que, sinceramente, é mais simples do que parece: é um Markdown com frontmatter YAML, só isso

Como criar o subagente de SEO passo a passo

Bora ver na prática?

1. Crie o arquivo .md na pasta certa. Se a auditoria é desse projeto, o arquivo vai em .claude/agents/. Se tu quer o mesmo auditor em todo projeto que abrir, vai em ~/.claude/agents/. O erro comum deste passo é salvar em escopo de usuário um agente cheio de regra específica de um site só, aí ele dispara em projeto que não tem nada a ver

2. Escreva o frontmatter com name e description. Só esses dois são obrigatórios, tools e model são opcionais. E presta atenção na description, porque ela é o que o Claude usa pra decidir QUANDO delegar a tarefa pro subagente. O erro comum deste passo é description vaga tipo "ajuda com SEO": ela nunca dispara a delegação automática e tu fica achando que o agente não funciona

3. Use tools como allowlist, ou omita pra herdar tudo. Se tu declara o campo, o subagente só usa aquelas ferramentas. Se omite, ele herda todas. Pra uma auditoria de diagnóstico, Read, Glob e Grep já resolvem a maior parte. O erro comum deste passo é allowlist apertada demais: tu esquece o Glob, o agente não acha os templates e devolve um relatório vazio achando que está tudo certo

   ---
   name: auditor-seo
   description: Audita SEO no código do projeto (títulos, meta tags, hierarquia de headings, links internos e rotas). Use quando pedirem auditoria de SEO, revisão de meta tags, checagem de headings ou conferência de links internos do repositório.
   tools: Read, Glob, Grep
   ---

   Você é um auditor de SEO técnico e trabalha SÓ com o código deste repositório.

   Regras:
   - Nunca estime métrica de busca (posição, clique, impressão). Esse dado não está no código.
   - Sempre cite o caminho do arquivo e a linha de cada problema encontrado.
   - Verifique, nesta ordem: título, meta description, hierarquia de headings, links internos, rotas.
   - Se um padrão não existir no projeto, diga que não existe em vez de sugerir um genérico.

   Formato do relatório: problema, arquivo, evidência, correção sugerida.

4. Escreva o corpo do arquivo com carinho, porque ele vira o system prompt. Tudo que está abaixo do frontmatter é a instrução permanente daquele subagente. É aqui que entra o padrão do teu projeto: onde fica o head, qual componente monta o título, o que é exceção. Vale o mesmo cuidado de fazer o agente respeitar o padrão do projeto quando o código é antigo e tem convenção própria. E lembra que regra escrita não vira regra obedecida por mágica, quem já viu o Claude ignorar o CLAUDE.md sabe bem disso

5. Acione o agente e leia o resumo. Cada subagente roda em janela de contexto própria, com system prompt e permissões separadas, e devolve um resumo pra conversa principal. Isso é ótimo: a varredura pesada de arquivo não entope o teu contexto principal. O erro comum deste passo é pedir edição quando o objetivo era só diagnóstico. Pra auditoria, o plan mode encaixa melhor, porque nele as ferramentas de leitura (Read, Glob, Grep, WebSearch, WebFetch) ficam disponíveis e as de edição (Edit, Write, Bash) ficam bloqueadas

Resumindo o espírito da coisa: primeiro tu deixa ele OLHAR, depois tu deixa ele mexer

O que esse agente consegue fazer no seu projeto

Aqui vai a lista do que realmente dá pra fazer sem sair do repositório, com a ferramenta que sustenta cada tarefa

• Título duplicado ou ausente entre páginas. Grep varrendo o padrão de título em todos os arquivos, comparando página a página. Título repetido em três rotas diferentes aparece na hora
• Meta description faltando em template. Glob pra achar todos os templates que montam head, Read pra conferir quais deles não têm a tag
• Hierarquia de headings quebrada. Grep nas tags de heading pra pegar o clássico: página com dois H1, ou que pula de H2 pra H4
• Link interno apontando pra rota que não existe mais. Grep pra extrair os destinos dos links, Glob pra montar o mapa de rotas do projeto, e o agente cruza as duas listas. Não é crawler do site publicado, é conferência do que o teu código escreve
• Mapa de rotas comparado ao sitemap versionado. Read no sitemap do repositório, Glob nas rotas, e ele aponta o que está em um lado e falta no outro
• Checagem que o próprio projeto já tem. Bash pra rodar os scripts de verificação que já existem no repo, aproveitando o que o time montou

Repara que nenhum desses itens precisa de dado externo

É tudo evidência que está no arquivo, com caminho e linha pra tu conferir

E é justamente por isso que essa parte funciona bem: o agente não tem espaço pra chutar

Como plugar dados de busca e tráfego via MCP

Agora a parte que o repositório não sabe responder

Se tu quer posição, impressão, clique ou sessão dentro da mesma sessão de trabalho, o caminho é MCP

1. Adicione o servidor pelo terminal. O comando é claude mcp add, rodado no terminal, fora da sessão do Claude Code. O erro comum deste passo é tentar rodar isso dentro da conversa e achar que quebrou

2. Escolha o escopo na hora de adicionar. O padrão é local. Use --scope user pra valer em todos os teus projetos, ou --scope project pra compartilhar a configuração com o time

3. Gerencie de dentro com /mcp. Esse comando, sim, roda dentro da sessão, e serve pra cuidar dos servidores que já foram adicionados

4. Pra tráfego, tem o servidor de Google Analytics mantido pela organização googleanalytics. O google-analytics-mcp usa a Admin API e a Data API do Google Analytics, e expõe ferramentas como get_account_summaries, get_property_details, run_report e run_funnel_report

5. Pra dado de busca, existem servidores de Search Console de comunidade. Um deles é o mcp-gsc, mantido por Amin Foroutan, escrito em Python e exigindo Python 3.11+. Ele expõe coisas como get_search_analytics, get_site_details, get_sitemaps, inspect_url_enhanced, batch_url_inspection e manage_sitemaps. O batch_url_inspection inspeciona até 10 URLs de uma vez, o que já muda o jogo de quem conferia indexação no braço

6. Se tu não quer montar nada do zero, dá uma olhada no que a comunidade já empacotou. O claude-seo, do usuário AgricIDaniel, se descreve como skill de SEO pro Claude Code com 25 sub-skills e 18 sub-agents, cobrindo SEO técnico, schema, backlinks, SEO local e relatórios, com extensões opcionais de DataForSEO e Firecrawl

Um porém honesto sobre os projetos de comunidade: eles são de comunidade mesmo, não são produto oficial

Lê o repositório antes, confere o que cada ferramenta pede de credencial, e trata a conexão com os teus dados de Search Console e Analytics com o cuidado que ela merece

Por onde começar

A fronteira é essa e ela não muda: dentro do repositório o Claude Code audita CÓDIGO, e código é título, meta tag, heading, rota, link interno e sitemap versionado

Posição, clique, impressão e sessão são dado externo, e dado externo entra por MCP ou não entra

O próximo passo concreto que eu sugiro é deliciosamente pequeno: cria um subagente com UMA auditoria só, tipo meta description faltando nos templates

Roda em plan mode, com leitura liberada e edição bloqueada, e lê o relatório com calma

Se o resultado vier com caminho de arquivo e evidência, tu já tem um agente de SEO no Claude Code que vale a pena

Aí sim tu libera a edição, ou conecta um MCP pra puxar o dado que falta 🙂

até o próximo post!