implementacao-schema

Habilidade de codificação. O usuário deseja implementar dados estruturados schema.org em um site. Abrange o fluxo de trabalho completo, desde a análise do tipo de página até a criação de tickets prontos para o desenvolvedor (JIRA, Wrike ou outras ferramentas de gerenciamento de projetos). Os gatilhos incluem qualquer menção a "schema.org", "dados estruturados", "rich results", "JSON-LD", "tickets JIRA para schema", "tarefas Wrike para schema" ou solicitações para analisar páginas da web para marcação SEO.

O que é implementacao-schema?

Esta skill fornece uma metodologia completa e agnóstica para implementar dados estruturados schema.org em sites, desde a descoberta inicial de tipos de página até a entrega de tickets prontos para desenvolvedores em ferramentas como JIRA e Wrike. Ela é composta por seis fases sequenciais: Configuração (Fase 0), Descoberta de Tipos de Página (Fase 1), Design do Schema (Fase 2), Criação de Tickets (Fase 3), Regeneração Final e Entrega (Fase 4) e, após a implantação, Verificação Pós-Implantação (Fase 5) e Medição de Impacto (Fase 6). A skill é especialmente útil para sites multilíngues e multirregionais, onde a consistência e a cobertura completa de schema são críticas. Ela suporta fluxos de trabalho com e sem navegador, priorizando a eficiência com acesso ao navegador para análise autônoma, mas oferecendo um método manual robusto como alternativa. O resultado são tickets detalhados que especificam tipos de schema, propriedades, cross-references via @id e regras técnicas universais, garantindo uma implementação precisa e de alta qualidade para SEO.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/rebelytics/schema-implementation/tree/HEAD

Installed? Explore more Programação e Desenvolvimento skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Implementação de Structured Data Schema.org — Skill de Fluxo de Trabalho Completo

Esta skill fornece uma metodologia de ponta a ponta para analisar sites, projetar marcação schema.org e produzir tickets prontos para desenvolvedores. Ela foi refinada por meio de projetos reais implementando dados estruturados em sites multilíngues e multirregionais.

A metodologia é independente do cliente. Funciona para qualquer site onde o objetivo é uma cobertura abrangente de schema.org com transferência para o desenvolvedor por meio de uma ferramenta de gerenciamento de projetos (JIRA, Wrike ou similar).

Licença: Esta skill é disponibilizada sob a licença Creative Commons Atribuição 4.0 Internacional (CC BY 4.0) . Você é livre para compartilhar e adaptar esta skill para qualquer finalidade, desde que atribua o crédito apropriado ao autor original.

Auditorias relacionadas: A Fase 5 desta skill verifica a saída ao vivo em relação à especificação projetada na Fase 2. Quando a tarefa é, em vez disso, verificar uma correção relatada entre localidades ("corrigido para todos os idiomas", "implantado em todos os lugares"), execute uma auditoria de validação JSON-LD, com as disciplinas de verificação de reivindicações que esta skill não possui: a barreira de cache, a enumeração da população a partir do índice do sitemap / conjunto hreflang ativo e o controle positivo. A parte de auditoria do trabalho de breadcrumb é uma auditoria de navegação breadcrumb; esta skill lida com sua parte de ticket.


Como Esta Skill Funciona

Esta é uma skill de projeto, normalmente concluída em 1–3 horas ao longo de 1–2 sessões para a maioria dos sites. Sites multilíngues complexos com muitos tipos de página podem levar mais tempo. A skill define cinco fases de entrega sequenciais: Fase 0 (Configuração), Fase 1 (Descoberta), Fase 2 (Design do Schema), Fase 3 (Criação de Tickets) e Fase 4 (Regeneração e Entrega) — seguidas por duas fases pós-implantação que são executadas depois que o desenvolvedor enviou: Fase 5 (Verificação Pós-Implantação) e Fase 6 (Medição de Impacto). Claude deve identificar em qual fase o usuário está e orientá-lo através dela.

O usuário fornece: Contexto do projeto, feedback sobre análise e rascunhos de tickets, regras específicas do projeto, resolução de perguntas em aberto. Claude fornece: Descoberta de tipo de página, análise de HTML, design de schema, rascunhos de tickets (pai + filho) e um conjunto final regenerado de tickets.

Nota de terminologia: Esta skill usa "ticket" como um termo genérico para o entregável voltado para o desenvolvedor. O formato real depende da plataforma de gerenciamento de projetos escolhida na Fase 0 (tickets JIRA, tarefas Wrike, etc.).


Arquivos de referência — carregar sob demanda

As Fases 1 a 6 residem em arquivos de referência, um arquivo por fase. Cada ponteiro nomeia seu gatilho. Esses carregamentos são etapas obrigatórias: quando uma fase começa, carregue seu arquivo antes de realizar o trabalho — nunca improvise uma fase a partir deste arquivo principal. Se você notar que uma fase foi tratada sem seu arquivo carregado, diga isso, carregue-o e verifique novamente o trabalho realizado até agora em relação a ele.

  • references/discovery.md — Fase 1: catálogo de tipos de página, triagem, verificação de orientação do Google, análise por tipo de página (schema existente em todos os três formatos, triagem condicional de schema, entrega de localidade), salvando dados reais, consolidação, classificação. Carregue antes de construir o catálogo de tipos de página e antes de analisar o HTML de qualquer tipo de página.
  • references/schema-design.md — Fase 2, seções 2.1–2.7: schema global e específico da página, referências cruzadas @id, depreciação vs. remoção, disposições de migração de formato, regras de seleção de propriedades, valores de propriedades multilíngues, verificação de suposições, regras do projeto. Carregue antes de escolher tipos de schema ou propriedades para qualquer tipo de página.
  • references/ticket-writing.md — Fase 3: pré-voo, o modelo de ticket, diretrizes do subagente, as regras numeradas de escrita de tickets (1–46), o ticket pai, a lista de verificação pré-entrega, o fluxo de trabalho de feedback e Decisões Comuns de Schema (§3.7). Carregue antes de redigir, revisar ou verificar qualquer ticket, antes de instruir um subagente sobre tickets e quando uma decisão §3.7 surgir no design.
  • references/delivery.md — Fase 4: plano de regeneração, formatação específica da plataforma (Wrike, JIRA, editores de rich text, ferramentas protegidas por WAF), a árvore de decisão do formato de entrega, passagem editorial, verificações de consistência entre tickets, empacotamento, Wrike XLS + HTML paste. Carregue antes da regeneração final e antes de formatar tickets para a ferramenta de destino.
  • references/post-deployment-verification.md — Fase 5: os gatilhos de varredura da população completa, a lista de verificação pré-voo da Fase 5, técnicas de verificação e busca entre idiomas, as quatro categorias de descoberta e o esqueleto do relatório, comentários de acompanhamento, verificação de URL e valor de origem, reconciliação e diagnóstico de erros do GSC, falsos positivos de busca única, auditorias de cobertura a partir de exportações de rastreamento. Carregue antes de verificar qualquer schema implantado, antes de confirmar um ticket como concluído, antes de responder a uma discrepância relatada pelo cliente e antes de diagnosticar um erro de dados estruturados no Search Console.
  • references/measuring-impact.md — Fase 6: a análise da aparência na pesquisa, a declaração de expectativa, os canais mensuráveis, a retenção de dados. Carregue quando o cliente perguntar o que os dados estruturados alcançaram, antes de qualquer número de impacto ser extraído.

Os números de seção (§1.2, §5.4) e os números de regra (Regra 35, antipadrão 21) são os mesmos em todos os arquivos, portanto, uma referência cruzada é resolvida por meio deste mapa.


Fase 0: Configuração e Ferramentas

Objetivo: Avaliar as ferramentas e o acesso disponíveis, configurar o fluxo de trabalho mais eficiente e coletar preferências de nível de projeto antes de iniciar o trabalho de conteúdo.

0.1 Avaliar Ferramentas Disponíveis

Antes de qualquer análise começar, determine quais capacidades estão disponíveis:

  • Acesso ao navegador (ex., Claude na extensão Chrome, ferramentas de navegador Cowork) — Permite que Claude navegue pelas páginas diretamente, capture HTML renderizado, extraia dados e verifique fatos de forma autônoma. Este é o fluxo de trabalho mais eficiente.
  • Pesquisa na web — Permite que Claude mapeie a estrutura do site, encontre sitemaps e descubra tipos de página sem acesso ao navegador.
  • Acesso ao sistema de arquivos — Permite salvar documentos de análise e rascunhos de tickets incrementalmente.
  • Acesso direto ao site — Alguns sites bloqueiam o acesso automatizado (erros 403). Se a busca na web falhar, o acesso ao navegador ou o upload manual de HTML são alternativas.

0.2 Orientar o Usuário para o Acesso ao Navegador

A análise assistida por navegador é o fluxo de trabalho primário recomendado para esta skill. Ela permite que Claude:

  • Descubra e mapeie tipos de página de forma autônoma
  • Capture HTML renderizado de qualquer página sem copiar e colar manualmente
  • Extraia sinais de detecção, fontes de dados e estruturas de modelo em minutos
  • Verifique fatos (padrões de URL, variantes de idioma, disponibilidade de campo) antes de escrever tickets

Se o acesso ao navegador ainda não estiver disponível, explique os benefícios e oriente o usuário na configuração. A função do usuário passa de "coletor de HTML" (tedioso, de baixo valor) para "revisor e tomador de decisões" (alto valor, onde sua experiência de domínio é importante).

Se o acesso ao navegador estiver indisponível ou o site bloquear totalmente a navegação automatizada, recorra ao fluxo de trabalho manual descrito na Fase 1.2.

Conscientização de custos: O acesso ao navegador permite a análise mais completa, mas é significativamente mais caro em uso de tokens — as chamadas de ferramentas do Chrome retornam cargas úteis grandes que se agravam quadraticamente à medida que a conversa cresce. Reserve os fluxos de trabalho do navegador para as fases de descoberta inicial e verificação onde a inspeção de página em tempo real agrega valor real. Para tarefas onde o inventário de tipos de página já está estabelecido (ex., escrever tickets a partir de uma auditoria concluída), os fluxos de trabalho sem navegador são igualmente eficazes e muito mais baratos. Quando o navegador for usado, prefira chamadas direcionadas (get_page_text, find, javascript_tool para extração cirúrgica) em vez de chamadas pesadas (read_page para DOM completo, read_network_requests para tráfego completo).

0.3 Coletar Preferências do Projeto

Antes de iniciar o trabalho de conteúdo, pergunte ao usuário:

  1. Plataforma de gerenciamento de projetos — "Em qual sistema esses tickets serão criados? (JIRA, Wrike, Asana, etc.)" Isso determina a terminologia (tickets vs tarefas vs itens), as restrições de formatação (ex., Wrike não renderiza blocos de código aninhados dentro de itens de lista — veja §4.4 Passagem de Formatação Específica da Plataforma em references/delivery.md) e a convenção de nomenclatura para arquivos entregáveis.
  2. Estrutura do ticket — "Sua organização tem uma estrutura de ticket ou modelo estabelecido para tarefas de desenvolvedor? Em caso afirmativo, compartilhe um modelo ou diretrizes de criação de tickets. Adaptarei os tickets de schema para corresponder às convenções da sua equipe." Se nenhum modelo existir, use a estrutura padrão da skill.
  3. Saudação e tom — ex., "Olá equipe," com tom entre pares, ou formal.
  4. Regras específicas do projeto — Restrições de privacidade, terminologia, regras de marca, etc. (Isso também pode ser coletado durante a Fase 2.)

Fase 1: Descoberta e Catálogo de Tipos de Página

Objetivo: Construir um inventário completo de todos os tipos de página no site, com sinais de detecção, cobertura de schema existente e dados reais salvos para exemplos de código de ticket.

Carregue references/discovery.md antes de iniciar esta fase. Ela contém toda a fase:

  • 1.1 Reunir a Lista de Tipos de Página
  • 1.1b Avaliação de Prioridade / Triagem
  • 1.1c Verificar a Orientação Atual do Google
  • 1.2 Analisar Cada Tipo de Página
  • 1.3 Salvar Dados Reais para Exemplos de Código de Ticket
  • 1.4 Documentar Descobertas
  • 1.5 Identificar Oportunidades de Consolidação
  • 1.6 Classificar Cada Tipo de Página

Fase 2: Design do Schema

Objetivo: Decidir quais tipos de schema e propriedades usar para cada tipo de página e como os schemas se relacionam entre si em todo o site.

Carregue references/schema-design.md antes de escolher tipos de schema ou propriedades. Ela contém as seções 2.1–2.7:

  • 2.1 Projetar o Schema Global/Compartilhado
  • 2.2 Projetar Schemas Específicos da Página
  • 2.3 Projetar Referências Cruzadas
  • 2.4 Depreciação vs Remoção
  • 2.4b Tickets de Migração de Formato — Disposição do Formato Existente
  • 2.5 Aplicar Regras de Seleção de Propriedades
  • 2.5b Valores de Propriedades Multilíngues
  • 2.6 Verificar Suposições Antes de Finalizar
  • 2.7 Regras Específicas do Projeto

A §2.8 permanece neste arquivo principal porque cada ticket e cada verificação a aplica:

2.8 Requisitos Técnicos Universais

Eles se aplicam a todos os projetos:

  • O schema deve ser renderizado no lado do servidor — Presente no HTML inicial retornado do servidor, não injetado dinamicamente por JavaScript. Esta é uma prática recomendada de SEO, não uma preferência específica do projeto.
  • Formato JSON-LD — Sempre implementar como <script type="application/ld+json"> na seção <head>.
  • Tags de script separadas — Cada tipo de schema obtém sua própria tag <script>.
  • Formato @context — Sempre usar https://schema.org (sem barra final). Reforce isso consistentemente em todos os tickets.
  • Emitir por meio de um serializador JSON real — Nunca montar JSON-LD manualmente por concatenação de strings/modelagem de valores CMS. JSON-LD construído manualmente é propenso a toda uma classe de quebras, mais ampla do que apenas caracteres não escapados: aspas não escapadas em valores interpolados, substituição de aspas inteligentes/curvas (U+201C/U+201D/U+201E onde uma aspa reta " pertence), e erros estruturais, como chaves soltas ou duplicadas (ex., um valor @id envolto em um conjunto extra de chaves). Um serializador elimina toda a classe; apenas regras de escape não.
  • Decodificar entidades HTML em valores de texto — Uma propriedade de texto carrega o caractere decodificado (', &), nunca a entidade HTML (&#039;, &amp;) que um campo CMS ou a fonte da página armazena. Quando o campo de origem contém texto codificado, o modelo o decodifica antes de serializar.
  • Datas em ISO 8601, datas-horas com deslocamento de fuso horário — Cada propriedade de data e data-hora (datePublished, dateModified, startDate, validFrom …) usa ISO 8601; uma data-hora carrega seu deslocamento (YYYY-MM-DDThh:mm:ss+hh:mm), nunca uma hora local simples ou um formato de exibição copiado da página.

Fase 3: Criação de Tickets

Objetivo: Produzir tickets prontos para desenvolvedores — um ticket pai para schemas compartilhados, um ticket filho por tipo de página (ou grupo consolidado).

Carregue references/ticket-writing.md antes de redigir, revisar ou verificar qualquer ticket. Ela contém toda a fase:

  • 3.1 Verificação Pré-Voo
  • 3.2 Modelo de Estrutura de Ticket
  • 3.2b Diretrizes de Uso de Subagentes
  • 3.3 Regras de Escrita de Tickets
  • 3.4 Escrevendo o Ticket Pai
  • 3.5 Lista de Verificação Pré-Voo (Antes da Entrega)
  • 3.6 Fluxo de Trabalho de Feedback e Iteração
  • 3.7 Decisões Comuns de Schema

Fase 4: Regeneração Final e Entrega

Objetivo: Regenerar todos os tickets em uma única passagem, aplicando cada regra, decisão e correção acumulada para consistência entre tickets.

Carregue references/delivery.md antes da passagem de regeneração final. Ela contém toda a fase:

  • 4.1 Construir um Plano de Regeneração
  • 4.2 Resolver Todas as Perguntas em Aberto Primeiro
  • 4.3 Regenerar em Sequência
  • 4.4 Passagem de Formatação Específica da Plataforma
  • Árvore de Decisão do Formato de Entrega
  • 4.5 Passagem Editorial
  • 4.6 Verificações de Consistência Entre Tickets
  • 4.7 Empacotar para Entrega
  • 4.8 Entrega Wrike — Esqueleto XLS + HTML Paste

Fase 5: Verificação Pós-Implantação

Objetivo: Depois que o desenvolvedor implantar o schema, confirme se a saída ativa corresponde à especificação — com atenção especial à cobertura multilíngue e à correção do tipo numérico.

Carregue references/post-deployment-verification.md antes de verificar o schema implantado, confirmar um ticket como concluído ou diagnosticar um erro do Search Console. Ela contém toda a fase:

  • Preâmbulo da fase — nota de escopo (verificação de correção relatada vai para uma auditoria de validação JSON-LD), os dois gatilhos para uma varredura de população completa e o inventário de modelo de ticket de todo o site
  • Lista de Verificação Pré-Voo da Fase 5 (Antes de Enviar o Relatório)
  • 5.1 Padrão de Verificação Entre Idiomas
  • 5.2 Categorias de Descoberta de Auditoria
  • 5.3 Quando Reabrir a Especificação
  • 5.4 Verificação de URL — Procedimento Pré-Publicação
  • 5.5 Verificação de Valor de Origem — Auditorias Espelho Não São Suficientes
  • 5.6 Reconciliando Contagens de Erros do GSC com um Rastreamento Ativo
  • 5.7 Falsos Positivos de Busca Única em Campos Renderizados Dinamicamente
  • 5.8 Diagnosticando "Dados Estruturados Não Analisáveis / Tipo de Valor Incorreto" do GSC em URLs do Mesmo Tipo de Página
  • 5.9 Auditoria de Cobertura a Partir de Exportações de Rastreamento

Fase 6: Medição de Impacto

Objetivo: Depois que a implementação estiver ativa por tempo suficiente, meça o impacto nos canais de pesquisa.

Carregue references/measuring-impact.md antes de extrair qualquer número de impacto. Ela contém toda a fase:

  • 6.1 A Linha de Base — Aparência na Pesquisa Antes da Implementação
  • 6.2 A Declaração de Expectativa
  • 6.3 Canais Mensuráveis
  • 6.4 Retenção de Dados

Metodologia e Filosofia Central

Esta skill opera em vários princípios fundamentais:

  1. Precisão em vez de velocidade: Cada ticket deve ser clinicamente preciso. A verificação é uma etapa separada, não uma reflexão tardia.
  2. Pronto para o desenvolvedor: Os tickets devem ser inequívocos. Um desenvolvedor não deve precisar perguntar "O que você quer dizer com isso?"
  3. Agnóstico de plataforma: A metodologia é a mesma, independentemente da ferramenta de gerenciamento de projetos. As diferenças na plataforma são tratadas apenas na formatação final.
  4. Iterativo: Feedback e iteração são esperados e incorporados ao fluxo de trabalho.
  5. Transferência de conhecimento: Os tickets servem como documentação viva. Eles devem ser auto-suficientes o suficiente para que um novo desenvolvedor possa entender a estratégia de schema do site a partir deles.

Padrões de Prompt Recomendados

Iniciando uma Nova Implementação

Vamos implementar dados estruturados schema.org em [site]. Estou começando do zero. Por favor, comece com a Fase 0 (Configuração) para avaliar as ferramentas disponíveis e coletar as preferências do projeto.

Fornecendo Acesso ao Navegador

Tenho acesso ao navegador disponível. Por favor, use-o para descobrir os tipos de página e analisar páginas reais.

Solicitando um Design Específico de Schema

Precisamos adicionar marcação de [Article/Product/LocalBusiness/etc] às páginas de [tipo de página]. O URL da amostra é [URL]. Por favor, carregue references/schema-design.md e projete o schema.

Revisando Tickets

Aqui está o feedback do desenvolvedor sobre os tickets da Fase 3: [feedback]. Por favor, carregue references/ticket-writing.md e aplique este feedback através das regras de ticket e itere.

Verificando a Implantação

O desenvolvedor implantou os schemas. Por favor, carregue references/post-deployment-verification.md e execute a verificação pós-implantação.


Guia de Solução de Problemas

ProblemaCausa ProvávelSolução
Os catálogos de tipos de página estão incompletosO site usa parâmetros de URL ou hash fragments para variantes de conteúdoUse a pesquisa no site (ou um sitemap XML) para enumerar todas as URLs; não confie apenas na navegação
O schema parece correto, mas o Google não o mostraPode ser um novo schema que ainda não foi rastreado, ou o conteúdo pode não ser elegível para rich resultsAguarde 1-2 semanas e verifique o Relatório de Dados Estruturados do GSC; confirme se o tipo de schema suporta rich results
A análise do navegador está em loop ou lentaMuitas guias abertas ou a página de destino tem um grande DOMReabra o navegador com uma nova sessão; use seletores direcionados
Os erros do GSC persistem após a correçãoO problema original pode não ter sido corrigido ou é um falso positivoExecute a verificação de URL manual por meio da ferramenta de inspeção de URL do GSC; carregue references/post-deployment-verification.md

Glossário

  • Ticket pai: O ticket de nível superior que descreve schemas compartilhados em todo o site (Organização, SiteNavigationElement, etc.) e fornece orientação geral de implementação.
  • Ticket filho: Um ticket por tipo de página (ou grupo consolidado) descrevendo o schema específico necessário para esse tipo de página.
  • Dados estruturados: Dados formatados que usam um vocabulário padronizado (schema.org) para descrever o conteúdo de uma página para mecanismos de busca.
  • JSON-LD: Um formato baseado em JSON para serializar dados vinculados. O formato preferido para dados estruturados schema.org.
  • @id: Um identificador único para um item no JSON-LD, permitindo que diferentes schemas façam referência à mesma entidade.
  • Microdados: Um formato HTML para marcação de dados estruturados. Mais antigo e menos preferido que JSON-LD.
  • RDFa: Um formato baseado em atributos para dados estruturados em HTML. Menos comum.
  • GSC (Google Search Console): Uma ferramenta gratuita do Google que ajuda a monitorar e manter a presença de um site nos resultados de pesquisa do Google.
  • Rich result: Um resultado de pesquisa do Google com dados estruturados, como estrelas de avaliação, preço do produto ou imagem.
  • Sitemap XML: Um arquivo que lista todas as páginas importantes de um site para ajudar os mecanismos de busca a descobrir e rastrear o conteúdo.
  • Hreflang: Um atributo HTML que especifica o idioma e a região geográfica de uma página, usado por sinalização de idioma.

Habilidades Relacionadas