Claude Code SEO agent: que material você precisa entregar para o agente devolver algo útil?

Se o seu agente de SEO só devolve aquele checklist morno que serve pra qualquer site do mundo, o problema quase nunca é o agente: ele está mal abastecido

Input pobre gera saída genérica, sempre

Já existe bastante conteúdo por aí sobre o que um Claude Code SEO agent consegue fazer: auditoria técnica, schema, cluster de pauta, crítica de rascunho

Aqui a conversa é a de antes disso: qual material você deixa pronto dentro do projeto pra que o pedido tenha onde se apoiar

Bora montar? 🙂

O que já precisa estar montado no projeto

Antes de falar em material, o mínimo de estrutura

Um subagente no Claude Code é um arquivo Markdown com um bloco de frontmatter YAML entre --- e, abaixo dele, o prompt de sistema em markdown

Esse arquivo mora em .claude/agents/ (escopo do projeto) ou em ~/.claude/agents/ (escopo pessoal, vale em todos os projetos)

Os campos de frontmatter suportados incluem name, description, tools e model

---
name: seo-auditor
description: Audita conteúdo e SEO on-page deste blog. Use quando eu pedir revisão de SEO de um post ou de uma seção do site
tools: Read, Glob, Grep, WebFetch
---

Você audita o conteúdo deste projeto do ponto de vista de SEO

Leia o arquivo de estrutura do site antes de opinar sobre link interno
Siga os critérios de nicho descritos no CLAUDE.md do projeto
Nunca sugira mudança sem apontar o arquivo e a seção afetada

O Claude Code varre .claude/agents/ e ~/.claude/agents/ de forma recursiva, então dá pra organizar tudo em subpastas, tipo agents/review/ ou agents/research/

E se dois subagentes tiverem o mesmo nome? Aí vale o da localização de maior prioridade, então cuidado com cópia esquecida no escopo pessoal

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

O segundo item obrigatório é o CLAUDE.md do projeto: ele guarda as instruções persistentes e é lido no começo de cada sessão

A documentação indica manter ali os fatos que o Claude deve carregar sempre: comandos de build, convenções, layout do projeto e regras do tipo "sempre faça X"

Perdeu de vista onde estão esses arquivos? O comando /memory lista os locais dos CLAUDE.md, CLAUDE.local.md e demais arquivos de memória, nos escopos de usuário e de projeto

Um aviso de versão, porque isso muda a forma de criar: a partir da v2.1.198, o /agents não abre mais o painel interativo, ele imprime um aviso apontando os locais dos arquivos de subagente

Na prática, você cria pedindo pro próprio Claude escrever a definição ou editando o .md na mão

Em v2.1.197 ou anterior, o /agents ainda abria o assistente interativo, com aba Running e aba Library

Se os termos subagente, skill e memória ainda estão embolados na sua cabeça, vale passar antes pelos conceitos básicos do Claude Code e depois voltar aqui

Passo a passo: montando o material que o agente vai ler

A ordem aqui importa pouco, o que importa é: material em arquivo, não em papo de chat

1. Mapa da estrutura das páginas. Escreva um arquivo no repo (algo como seo/estrutura-do-site.md) listando seções, tipos de página, categorias e onde cada coisa vive. Entregue com @ na mensagem de invocação

@seo/estrutura-do-site.md revise o link interno sugerido para o rascunho em content/posts/claude-code-seo.md

Digitar @ seguido do nome do arquivo adiciona aquele arquivo ao contexto, e dá pra referenciar vários arquivos na mesma mensagem

Detalhe que pouca gente sabe: uma referência @ também traz pro contexto os CLAUDE.md do diretório daquele arquivo e dos diretórios pais, então convenção local viaja junto de graça

O erro comum deste passo: descrever a estrutura no chat ("tenho um monte de página, a maioria tutorial…") em vez de mandar o arquivo. A documentação de boas práticas indica justamente o contrário: referenciar com @ pro Claude ler o arquivo antes de responder

2. Amostra dos textos já publicados. Não cole conteúdo no chat, deixe o agente ir buscar. No Windows, as ferramentas Glob (acha arquivo por padrão) e Grep (busca conteúdo por regex) fazem parte do conjunto padrão; no macOS, Linux e WSL o Claude usa Bash com find e grep

O erro comum deste passo: despejar um monte de post inteiro na mensagem. Você gasta contexto com o que o agente acharia sozinho, e sobra menos espaço pro raciocínio que você realmente quer

3. Lista de pautas em aberto, versionada. Um arquivo no repo com as pautas, o estado de cada uma e a palavra alvo já resolve. Fica versionado, fica diffável, e você referencia com @ sempre que pedir priorização

Não existe formato oficialmente recomendado pra isso, então use o que seu time já usa e mantenha consistente

O erro comum deste passo: manter a pauta só numa planilha fora do projeto. O que não está alcançável pelo agente simplesmente não entra na análise

4. Critérios do seu nicho, dentro do CLAUDE.md. Aqui é o pulo do gato: o que conta como bom no SEU nicho, o que você nunca publica, tom, profundidade mínima, o que é prova aceitável

Mas segura a mão no tamanho: arquivos de memória com mais de 200 linhas consomem mais contexto e podem reduzir a aderência às instruções

E arquivo de memória acima de 4 MiB é ignorado pelo Claude Code, ou seja, colar o site inteiro ali é o mesmo que não escrever nada

O erro comum deste passo: transformar o CLAUDE.md em enciclopédia. Regra curta e específica vence parágrafo bonito

5. Fontes externas, quando o pedido precisa do que está fora do repo. São duas ferramentas com papéis diferentes: a WebSearch busca, e uma chamada dela pode disparar até oito buscas no backend, refinando internamente antes de devolver resultados

Quem lê a página é a WebFetch: ela recebe uma URL e um prompt do que extrair, converte o HTML em Markdown e roda esse prompt sobre o conteúdo com um modelo pequeno e rápido

O erro comum deste passo: esperar conteúdo de página vindo da busca. E tem outro: a WebFetch guarda cada resposta em cache por 15 minutos por padrão, então se você acabou de mexer numa página e pediu releitura, pode estar olhando a versão anterior

6. O prompt de invocação. Cada subagente começa com uma janela de contexto isolada e não enxerga o histórico da conversa, nem as skills já invocadas, nem os arquivos que o Claude já leu

O único conteúdo que passa do agente principal pro subagente é a string de prompt da ferramenta Agent

Tradução: caminho de arquivo, mensagem de erro, decisão tomada e restrição precisam estar escritos ali, na invocação

Precisa do histórico inteiro mesmo? Existe a opção de fork, um subagente que herda system prompt, ferramentas, modelo e o histórico da sessão principal, abrindo mão do isolamento de contexto

Quer o contrário, um agente de alcance curto que não sai editando o que não deve? A forma indicada é estreitar o campo tools da definição ou usar regras de deny nas settings

O erro comum deste passo: escrever "seguindo o que combinamos acima". O subagente não viu nada acima 😛

O que cada material destrava no pedido ao agente

Material não é burocracia, cada arquivo desbloqueia um tipo de pedido que antes só voltava conselho de manual

Repara que nada disso depende de ferramenta paga, depende de você ter escrito as coisas

E os pacotes prontos, resolvem? Ajudam bastante no esqueleto

O claude-seo, mantido no GitHub pelo usuário AgriciDaniel, é uma skill de SEO pra Claude Code que reúne 25 sub-skills e 18 sub-agentes cobrindo SEO técnico, E-E-A-T, schema, GEO/AEO, backlinks, SEO local, clusterização semântica, SEO para e-commerce e SEO internacional

A versão pública é open source sob licença MIT, o que significa que você consegue abrir os arquivos e ler o que cada agente faz antes de confiar

Só que nem esses 18 sub-agentes adivinham a estrutura do seu site nem a régua do seu nicho: o pacote traz o método, o material continua sendo seu dever de casa

E se a sua dúvida é pacote de fora do ecossistema, eu já escrevi sobre se o Oh My OpenAgent compensa pra quem já roda Claude Code

O que eu aprendi preparando material para agente na prática

Essa história de "material específico vale mais que prompt bonito" não é teoria minha de escritório, é o que apareceu quando fui montar um projeto do zero com agente no vídeo do curso gratuito de Codex

Quando criei o projeto, escrevi um prompt com itens bem definidos: tipo de página, tema, seções obrigatórias (hero, preço, depoimentos, FAQ), estilo visual desejado, cor principal, exigência de responsividade e a stack a ser usada

E olha, eu classifiquei aquele nível de detalhe como o MÍNIMO necessário pro agente devolver um projeto viável, não como capricho

O que mudou quando o material saiu do chat e virou arquivo: o arquivo de contexto na raiz do projeto passou a carregar as regras, a estrutura de banco e o padrão de código

Bônus que eu não esperava: esse arquivo serve pra mim também, quando volto num projeto depois de um tempo parado e preciso reentender o que eu mesmo fiz haha

Outra coisa que ficou clara ali: o agente lê e entende o codebase existente antes de mexer, ele não trabalha só com o que foi pedido na mensagem

Ou seja, o que está escrito nos seus arquivos pesa no resultado tanto quanto o pedido

Também uso imagem como entrada de duas formas no dia a dia: mandar um layout de referência pra guiar o visual e mandar print do erro que apareceu na tela

Sobre tarefas repetidas, eu trato skill como arquivo markdown com instruções pra uma coisa específica. As que uso: análise de saúde do projeto, revisão de código, planejamento de deploy, verificação de segurança, verificação de performance e criação de componente ou página

E onde o esforço de preparação NÃO compensou?

No excesso de skill

Durante a execução ao vivo, o agente acionou skills que eu não tinha pedido naquele prompt, e o motivo era simples: eu tenho skills instaladas em pasta genérica, acessível a qualquer agente

No Claude Code esse é o comportamento esperado do escopo pessoal: skill pessoal fica em ~/.claude/skills/<nome-da-skill>/SKILL.md, com frontmatter YAML indicando quando usar e o corpo markdown com as instruções, e vale pra todos os projetos, sendo que o nome do diretório vira o comando digitado

Muito material disponível vira material sendo usado sem pedido, e consumo subindo junto. Tome cuidado!

O outro lugar onde eu me queimei foi rodar vários agentes em paralelo: deu risco de choque de edição nos mesmos arquivos ou em tarefas muito parecidas

Hoje eu só libero paralelo pra frentes bem diferentes, tipo um agente programando e outro fazendo análise de segurança

Duas coisas que me deixaram mais tranquilo no processo: o agente expõe todo o raciocínio antes da versão final, então dá pra acompanhar o que está sendo decidido, e ele edita arquivo ou roda comando (de instalação, de build ou outros) apenas dentro do que recebe permissão

E se você está começando agora, um recado sincero: CLI via terminal não é o caminho mais amigável pra iniciante, por isso escolhi a versão desktop pra ensinar, que é a mais difundida

No vídeo abaixo eu mostro a montagem das skills e do projeto do começo ao fim, vale assistir a parte em que o agente sai usando skill sem eu pedir

Por onde começar hoje

O melhor de preparar material é que ele é ativo reaproveitável: você escreve uma vez e usa em toda invocação daquele agente, em toda sessão, em todo mês seguinte

Começa pequeno, nesta ordem:

• cria um arquivo de estrutura do site no repo, mesmo tosco, listando tipos de página e onde o conteúdo mora
• escreve um bloco de critérios do seu nicho no CLAUDE.md, curto, lembrando das 200 linhas
• define o subagente como .md com frontmatter em .claude/agents/, com tools só do que ele precisa
• invoca já referenciando os arquivos com @, e escreve caminho e restrição dentro do prompt, porque o subagente não vê seu histórico

Depois é loop: olha o que voltou fraco e transforma essa fraqueza em mais uma linha de critério ou mais uma seção no arquivo de estrutura

Seu próximo passo concreto pra hoje: abre o projeto, roda /memory pra ver onde seus arquivos de memória estão e escreve cinco regras do seu nicho ali dentro

Cinco regras, não cinquenta 😀

Na próxima sessão você chama o agente apontando @ pro arquivo de estrutura e compara a resposta com a de antes, a diferença aparece rápido

até o próximo post!