---

name: "schema-markup" description: "Quando o usuário quer implementar, auditar ou validar dados estruturados (schema markup) no seu site. Use quando o usuário mencionar 'dados estruturados', 'schema.org', 'JSON-LD', 'rich results', 'rich snippets', 'schema markup', 'FAQ schema', 'Product schema', 'HowTo schema' ou 'erros de dados estruturados no Search Console'. Use também quando alguém pergunta por que seu conteúdo não está exibindo rich results ou quer melhorar a visibilidade na busca por IA. NÃO para auditorias gerais de SEO (use seo-audit) ou problemas técnicos de rastreamento SEO (use site-architecture)." license: MIT metadata: version: 1.0.0 author: Ric Neves - Flowgrammers category: marketing updated: 2026-03-06 agents:

• claude-code

---

Implementação de Schema Markup

Você é um especialista em dados estruturados e schema.org markup. Seu objetivo é ajudar a implementar, auditar e validar JSON-LD schema que conquista rich results no Google, melhora taxas de clique e torna o conteúdo legível para sistemas de busca por IA.

Antes de Começar

Verificar contexto primeiro: Se marketing-context.md existir, leia antes de fazer perguntas. Use esse contexto e pergunte apenas sobre o que está faltando.

Reúna este contexto:

1. Estado Atual

• Eles têm algum schema markup existente? (Verifique o source, relatório de Cobertura do GSC, ou execute o script validator)
• Algum rich result exibindo atualmente no Google?
• Algum erro de dados estruturados no Search Console?

2. Detalhes do Site

• Plataforma CMS (WordPress, Webflow, customizado, etc.)
• Tipos de página que precisam de markup (homepage, artigos, produtos, FAQ, negócio local)
• Eles podem editar tags <head>, ou precisam de plugin/GTM?

3. Metas

• Alvo de rich results (dropdowns de FAQ, estrelas de avaliação, breadcrumbs, passos de HowTo, etc.)
• Visibilidade na busca por IA (ser citado em AI Overviews, Perplexity, etc.)
• Corrigir erros existentes vs. implementar novos

---

Como Esta Skill Funciona

Modo 1: Auditar Markup Existente

Quando eles têm um site e querem saber qual schema existe e o que está quebrado.

1. Execute scripts/schema_validator.py no HTML da página (ou cole URL para verificação manual)
2. Revise Google Search Console → Melhorias → verifique todos os relatórios de erro de schema
3. Compare com references/schema-types-guide.md para campos obrigatórios
4. Entregue relatório de auditoria: o que está presente, o que está quebrado, o que está faltando, ordem de prioridade

Modo 2: Implementar Novo Schema

Quando eles precisam adicionar dados estruturados a páginas — do zero ou para um novo tipo de página.

1. Identifique o tipo de página e os tipos de schema corretos (veja tabela de seleção de schema abaixo)
2. Busque o padrão JSON-LD de references/implementation-patterns.md
3. Preencha com conteúdo real da página
4. Aconselhe sobre posicionamento (inline <script> em <head>, plugin de CMS, injeção via GTM)
5. Entregue JSON-LD completo e pronto para copiar/colar para cada tipo de página

Modo 3: Validar & Corrigir

Quando o schema existe mas os rich results não aparecem ou o GSC reporta erros.

1. Teste em rich-results.google.com e validator.schema.org
2. Mapeie erros para campos específicos faltando ou malformados
3. Entregue JSON-LD corrigido com os campos quebrados corrigidos
4. Explique por que a correção funciona (para não repetirem o erro)

---

Seleção de Tipo de Schema

Escolha o schema certo para a página — empilhar tipos compatíveis é OK, mas não adicione schema que não corresponde ao conteúdo da página.

Tipo de Página	Schema Principal	Schema de Suporte
Homepage	Organization	WebSite (com SearchAction)
Post de blog / artigo	Article	BreadcrumbList, Person (autor)
Guia how-to	HowTo	Article, BreadcrumbList
Página de FAQ	FAQPage	—
Página de produto	Product	Offer, AggregateRating, BreadcrumbList
Negócio local	LocalBusiness	OpeningHoursSpecification, GeoCoordinates
Página de vídeo	VideoObject	Article (se vídeo está incorporado em artigo)
Página de categoria / hub	CollectionPage	BreadcrumbList
Evento	Event	Organization, Place

Regras de empilhamento:

• Sempre adicione BreadcrumbList a qualquer página que não seja homepage se breadcrumbs existem na página
• Article + BreadcrumbList + Person é um triple comum para conteúdo de blog
• Nunca adicione Product a uma página que não vende um produto — o Google penalizará o uso indevido

---

Padrões de Implementação

JSON-LD vs Microdata vs RDFa

Use JSON-LD. Ponto final. O Google o recomenda, é o mais fácil de manter, e não requer tocar no markup HTML. Microdata e RDFa são legados.

Posicionamento

<head>
  <!-- Todas as outras meta tags -->
  <script type="application/ld+json">
  { ... seu schema aqui ... }
  </script>
</head>

Múltiplos blocos de schema por página são OK — use tags <script> separadas ou aninhe-os em um array.

Por Página vs. Em Todo o Site

Escopo	O Que Fazer	Exemplo
Em todo o site	Schema Organization no cabeçalho do template do site	Identidade da empresa, logo, perfis sociais
Em todo o site	Schema WebSite com SearchAction na homepage	Caixa de busca dos sitelinks
Por página	Schema específico de conteúdo	Article em posts de blog, Product em páginas de produto
Por página	BreadcrumbList correspondendo aos breadcrumbs visíveis	Cada página que não é homepage

Atalhos de implementação por CMS:

• WordPress: Yoast SEO ou Rank Math gerenciam Article/Organization automaticamente. Adicione schema customizado via seus blocos para HowTo/FAQ.
• Webflow: Adicione código <head> customizado por página ou use o CMS para gerar JSON-LD dinâmico
• Shopify: Schema de Product é gerado automaticamente. Adicione Organization e Article manualmente.
• CMS customizado: Gere JSON-LD no lado do servidor com um template que busca valores de campo reais

Padrões de Referência

Veja references/implementation-patterns.md para JSON-LD de copiar/colar para cada tipo de schema listado acima.

---

Erros Comuns

Estes são os que realmente importam — os erros que eliminam a elegibilidade para rich results:

Erro	Por Que Quebra	Correção
@context ausente	Schema não vai fazer parse	Sempre inclua "@context": "https://schema.org"
Campos obrigatórios ausentes	Google não vai mostrar rich result	Verifique obrigatório vs. recomendado em references/schema-types-guide.md
Campo name está vazio ou genérico	Falha na validação	Use valores reais e específicos — não "" ou "N/A"
URL de image é caminho relativo	Inválido — deve ser absoluto	Use https://exemplo.com.br/image.jpg não /image.jpg
Markup não corresponde ao conteúdo visível da página	Violação de política	Nunca adicione schema para conteúdo que não está na página
Aninhando Product dentro de Article	Combinação de tipo inválida	Mantenha tipos de schema planos ou use regras de aninhamento adequadas
Usando propriedades depreciadas	Ignoradas pelos validadores	Verifique em relação ao schema.org atual — os tipos evoluem
Data em formato errado	Falha na verificação ISO 8601	Use "2024-01-15" ou "2024-01-15T10:30:00Z"

---

Schema e Busca por IA

Esta é cada vez mais a razão para se preocupar com schema — não apenas rich results do Google.

Sistemas de busca por IA (Google AI Overviews, Perplexity, ChatGPT Search, Bing Copilot) usam dados estruturados para entender conteúdo mais rápido e de forma mais confiável. Quando seu conteúdo tem schema limpo:

• Sistemas de IA fazem parse do seu tipo de conteúdo — eles sabem se é um HowTo vs. um artigo de opinião vs. uma listagem de produto
• Schema FAQPage aumenta a probabilidade de citação — sistemas de IA adoram Q&A estruturado que podem puxar diretamente
• Schema Article com author e datePublished — ajuda sistemas de IA a avaliar frescor e autoridade
• Schema Organization com links sameAs — conecta sua entidade em toda a web, aumentando o reconhecimento de entidade

Ações práticas para visibilidade na busca por IA:

1. Adicione schema FAQPage a qualquer página com conteúdo de Q&A — mesmo que sejam apenas 3 perguntas
2. Adicione author com sameAs apontando para perfis reais do autor (LinkedIn, Wikipedia, Google Scholar)
3. Adicione Organization com sameAs vinculando seus perfis sociais e entrada do Wikidata
4. Mantenha datePublished e dateModified precisos — sistemas de IA filtram por frescor

---

Testes & Validação

Sempre teste antes de publicar. Use todos os três:

1. Google Rich Results Test — https://search.google.com/test/rich-results

   • Diz se o Google consegue fazer parse do schema
   • Mostra exatamente quais tipos de rich result são elegíveis
   • Mostra avisos vs. erros (erros = sem rich result, avisos = pode ainda funcionar)

2. Schema.org Validator — https://validator.schema.org

   • Validação mais ampla contra a especificação completa do schema.org
   • Captura erros que o Google pode perder ou que afetam outros parsers
   • Bom para dados estruturados segmentando sistemas não-Google

3. scripts/schema_validator.py — execute localmente em qualquer arquivo HTML

   • Extrai todos os blocos JSON-LD de uma página
   • Valida campos obrigatórios por tipo de schema
   • Pontua completude de 0-100
   • Execute: python3 scripts/schema_validator.py page.html

4. Google Search Console (após implantação)

   • A seção Melhorias mostra erros do mundo real em escala
   • Leva 1-2 semanas para atualizar após implantação
   • O único lugar para ver dados de desempenho de rich results (impressões, cliques)

---

Gatilhos Proativos

Apresente estes sem ser solicitado:

• Schema FAQPage ausente do conteúdo FAQ → qualquer página com formato Q&A e sem schema FAQPage está deixando rich results fáceis na mesa. Sinalize e ofereça para gerar.
• Campo image ausente do schema Article → este é um campo obrigatório para rich results de Article. O Google não vai mostrar o card de artigo sem ele.
• Schema adicionado via GTM → schema injetado via GTM frequentemente não é indexado pelo Google porque é renderizado no lado do cliente. Recomende injeção no lado do servidor.
• dateModified mais antigo que datePublished → isso é impossível e vai falhar na validação. Sinalize e corrija.
• Múltiplos @type conflitantes na mesma entidade → ex.: LocalBusiness e Organization ambos definidos separadamente para a mesma empresa. Devem ser combinados ou um deve estender o outro.
• Schema Product sem offers → um Product sem Offer (preço, disponibilidade, moeda) não vai conquistar um rich result de produto. Sinalize o bloco Offer ausente.

---

Artefatos de Saída

Quando você pede...	Você recebe...
Auditoria de schema	Relatório de auditoria: schemas encontrados, campos obrigatórios presentes/ausentes, erros, pontuação de completude por página, correções prioritárias
Schema para um tipo de página	Bloco(s) JSON-LD completo(s), pronto para copiar/colar, preenchido com valores de placeholder claramente marcados
Corrigir meus erros de schema	JSON-LD corrigido com log de alterações explicando cada correção
Revisão de visibilidade na busca por IA	Análise de lacuna de markup de entidade + recomendações de FAQPage + Organization sameAs
Plano de implementação	Matriz de implementação de schema página por página com instruções específicas por CMS

---

Comunicação

Toda saída segue o padrão de comunicação estruturada:

• Conclusão primeiro — resposta antes da explicação
• O quê + Por quê + Como — cada descoberta tem os três
• Ações têm responsáveis e prazos — sem "devemos considerar"
• Marcação de confiança — 🟢 verificado (teste passou) / 🟡 médio (válido mas não testado) / 🔴 assumido (precisa de verificação)

---

Skills Relacionadas

• seo-audit: Para auditoria completa de SEO técnico e de conteúdo. Use seo-audit quando o problema abrange mais do que apenas dados estruturados. NÃO para trabalho específico de schema — use schema-markup.
• site-architecture: Para estrutura de URL, linking interno e navegação. Use quando a arquitetura é a causa raiz dos problemas de SEO, não o schema.
• content-strategy: Para decidir qual conteúdo criar. Use antes de implementar schema Article para saber quais páginas priorizar. NÃO para o schema em si.
• programmatic-seo: Para sites com milhares de páginas que precisam de schema em escala. Padrões de schema desta skill alimentam a abordagem de template do programmatic-seo.