Como criar uma Skill do Codex para SEO Schema JSON-LD

Resposta curta: o Schema deve ser uma copia estruturada dos fatos da pagina

Se voce chegou aqui procurando um prompt SKILL.md do Codex para SEO Schema JSON-LD, pode copiar um abaixo. A regra por tras dele e mais importante que o codigo: os dados estruturados devem expressar fatos que o visitante ja consegue verificar na pagina. Nao sao uma oportunidade de criar o objeto JSON mais elaborado possivel.

O Codex e util porque pode inspecionar a pagina, os dados de conteudo e a marcacao existente antes de sugerir um tipo ou escrever JSON-LD. Essa ordem importa. Um pedido vago como "adicione todo o schema que puder" costuma produzir aggregateRating, preco, autor ou data de publicacao inventados. Esses campos podem ser validos sintaticamente e ainda assim representar a pagina de forma incorreta.

O Google recomenda JSON-LD quando a configuracao do site permite, pois geralmente e mais facil de implementar e manter. As diretrizes tambem deixam claro que a marcacao deve descrever a pagina em que esta, refletir o conteudo visivel ao usuario e permanecer correta. Passar no Rich Results Test nao garante um resultado aprimorado.

Escolha o tipo principal da pagina antes de adicionar objetos de apoio

Comece com uma pergunta simples: o que o visitante esta vendo principalmente? A resposta deve determinar o tipo principal do Schema.org. Breadcrumbs, dados da organizacao e video podem apoiar o objeto principal quando descrevem informacoes visiveis na mesma pagina.

O Schema.org tem um vocabulario muito mais amplo que os recursos de resultados aprimorados do Google. Para trabalhos de Pesquisa Google, o guia atual do Google Search Central para o recurso desejado tem mais autoridade que o simples fato de uma propriedade existir no Schema.org.

Comece pelo objetivo da pagina. O tipo segue os fatos visiveis, e nao o contrario.

Um fluxo mais seguro no Codex tem quatro barreiras

1. Inventario de fatos. Extraia apenas do texto visivel da pagina, de campos confiaveis do CMS renderizados nela ou de dados explicitamente confirmados pelo usuario. Marque cada campo candidato como confirmado, ausente ou pendente de confirmacao.
2. Decisao de tipo. Escolha o tipo principal que corresponde ao objetivo central da pagina. Explique alternativas em vez de empilhar todos os tipos plausiveis em uma resposta.
3. Codigo e mapeamento. Produza JSON-LD com uma fonte para cada valor emitido. Omita propriedades desconhecidas em vez de preenche-las com placeholders.
4. Validacao e lancamento. Verifique a sintaxe JSON, os requisitos especificos do recurso, o DOM renderizado, a Inspecao de URL e o relatorio adequado do Search Console.

A Skill abaixo torna essas barreiras explicitas. Ela pede ao Codex que audite primeiro e altere o codigo depois, a forma mais simples de impedir que uma marcacao aparentemente valida se afaste da propria pagina.

Copie esta Skill do Codex para SEO Schema JSON-LD (SKILL.md)

Salve o conteudo a seguir como sua configuracao de Skill. Ele nao contem diretorio da maquina, nome de usuario, token de acesso, valor de variavel de ambiente ou caminho privado. Tambem instrui o Codex a remover contexto sensivel das respostas.

---
name: seo-schema-jsonld
description: Audit visible page facts, recommend accurate Schema.org JSON-LD, implement it safely, and validate it against Google structured-data requirements.
---

# SEO Schema JSON-LD

Use this skill when a user asks to add, repair, review, or validate Schema.org JSON-LD / structured data for a website page, template, CMS entry, or component.

## Primary rule

Treat structured data as a structured representation of the page's user-visible facts. Never use it to invent, hide, exaggerate, or imply information that the page does not support.

## Privacy and output safety

- Never print absolute local paths, home directories, usernames, credentials, tokens, cookies, API keys, environment-variable values, private URLs, or repository-specific secrets.
- Refer to files with short, project-relative labels when needed, such as `src/pages/article.tsx` or `the page template`.
- Do not copy sensitive values into JSON-LD, examples, logs, commit messages, screenshots, or explanations.
- If input contains secrets or private identifiers, omit them and state that sensitive values were excluded.

## Required workflow

### 1. Inspect before generating

Read the relevant page, template, content data, and any existing structured data. Build a fact inventory using only:

- visible page text and user-visible UI;
- trusted CMS fields that are rendered on that page;
- verified product, organization, author, or breadcrumb data supplied by the user.

For every candidate property, label it `confirmed`, `missing`, or `needs human confirmation`. Do not infer missing values from brand names, URLs, conventions, or unrelated pages.

### 2. Choose the narrowest suitable type

Identify the page's primary purpose first. Recommend one primary Schema.org type that truthfully describes it. Add supporting objects only when they also describe user-visible information on the same page.

Explain the recommended primary type, supporting types, why each applies, and types deliberately rejected.

For Google rich-result eligibility, consult the current Google Search Central documentation for the target feature. Schema.org support alone does not establish Google feature support.

### 3. Apply strict data guardrails

Never generate these values unless they are confirmed and visible or otherwise explicitly verified by the user:

- `aggregateRating`, `review`, or review counts;
- price, currency, availability, offer dates, shipping, or return policy;
- author, publisher, logo, address, phone, social profile, or `sameAs`;
- publication dates, modification dates, images, video duration, or interaction counts;
- FAQ questions and answers that are not visibly present;
- event, job, medical, financial, legal, or local-business claims.

Never add misleading `FAQPage`, fake reviews, hidden content, keyword lists, or unrelated types. Prefer fewer complete and accurate properties over many uncertain ones.

### 4. Produce the implementation

Return these sections in order:

1. `Fact inventory` - property, value or status, and visible source.
2. `Schema decision` - primary type, supporting types, assumptions, and exclusions.
3. `JSON-LD` - valid JSON inside one `application/ld+json` script block. Use placeholders only in a clearly labeled illustrative example; never present placeholders as production-ready values.
4. `Implementation note` - the safe insertion point for the site's framework or CMS, without exposing private paths.
5. `Validation checklist` - syntax, rendered-page check, Google Rich Results Test when applicable, Schema Markup Validator, URL Inspection after deployment, and Search Console monitoring.
6. `Open questions` - every field that needs a human decision.

If editing code is requested, make the smallest scoped change. Preserve existing valid markup, avoid duplicate entities, and explain any conflict before replacing it.

## JSON-LD quality checks

Before finalizing, verify all of the following:

- JSON parses and uses `https://schema.org` as `@context`.
- The main type matches the page's main user-visible purpose.
- Every emitted value has a page-level source or explicit user confirmation.
- Required fields for the intended Google feature are present and accurate.
- URLs are canonical, publicly reachable URLs when the property requires a URL.
- Dates use ISO 8601 where required.
- Multiple entities are connected deliberately, not duplicated accidentally.
- The markup remains available to crawlers in the rendered response.
- The result contains no secrets, local paths, private identifiers, or fabricated claims.

## Limitations to state plainly

Valid structured data can help search engines understand a page and make it eligible for certain search appearances. It does not guarantee rich results, rankings, traffic, citations, or inclusion in AI answers.

Use a Skill com uma etapa de aprovacao

Nao pare em "adicione schema a esta pagina". Entregue ao Codex a pagina e os criterios de aceitacao. Este e um bom prompt inicial:

Use the SEO Schema JSON-LD skill to review this article page.

Goal: add accurate Article and BreadcrumbList JSON-LD if the visible content supports them.
First return the fact inventory and schema decision. Do not edit code until I approve the decision.
Do not create ratings, reviews, author details, dates, images, or organization fields that are absent from the page.
After approval, make the smallest implementation change and provide the validation checklist.

Para um template grande, mantenha a barreira "inventario de fatos e decisao primeiro". Ela acrescenta uma etapa curta de revisao, mas pode impedir que uma suposicao ruim se espalhe por milhares de URLs.

Um caminho de 30 minutos da auditoria a implantacao

Apos o lancamento, use a Inspecao de URL para confirmar que o Google consegue buscar e analisar a pagina. Depois, use o relatorio de aprimoramentos relevante no Search Console para encontrar falhas de template, implantacao ou fonte de dados em escala. O primeiro verifica uma URL individual; o segundo e melhor para detectar falhas sistemicas.

Cada camada detecta uma falha diferente. Um objeto sintaticamente valido ainda pode falhar na verificacao dos fatos da pagina ou da implantacao.

Um exemplo deliberadamente minimo para pagina de artigo

Este e um codigo ilustrativo, nao um objeto de producao pronto para colar. Ele mostra o formato de BlogPosting e BreadcrumbList. Use valores reais e confirmados na pagina para titulo, descricao, URL, autor, data e imagem. Se a pagina nao tiver um desses fatos, nao o acrescente apenas para deixar o objeto mais completo.

O exemplo intencionalmente nao inclui avaliacao, autor, data de publicacao, imagem ou publisher. Eles nao sao adornos opcionais de SEO. Sao afirmacoes que precisam de uma fonte confiavel.

Cinco formas de uma marcacao tecnicamente valida ainda dar errado

Analisar JSON nao e testar a veracidade

Um validador JSON informa se a sintaxe pode ser analisada. Ele nao diz se a pagina tem as avaliacoes, o preco ou o autor declarados, nem se um Product e na verdade apenas uma pagina que descreve um servico. O inventario de fatos detecta cedo a maioria dessas falhas.

Mais objetos nao significam marcacao melhor

Uma pagina de receita com video visivel pode incluir legitimamente Recipe, VideoObject e breadcrumbs. Ainda assim, seu objetivo principal deve estar claro. Adicionar Article, Product, FAQPage e HowTo a uma pagina generica de conteudo normalmente cria trabalho de manutencao e risco de inconsistencia.

Visibilidade e atualizacao precisam do mesmo responsavel

As diretrizes gerais do Google exigem que os dados estruturados representem a pagina e que informacoes sensiveis ao tempo permaneçam atuais. Precos, estoque, datas de eventos, vagas e avaliacoes nao devem existir como valores colados uma unica vez. Conecte fatos dinamicos a uma fonte controlada e teste novamente quando o template mudar.

FAQPage nao e uma decoracao generica de perguntas e respostas

Somente perguntas e respostas realmente visiveis ao usuario pertencem a marcacao de FAQ, e os recursos do Google podem ter condicoes adicionais de elegibilidade. Publique primeiro uma FAQ genuina e completa e depois consulte o guia atual do recurso. Nao crie uma lista de perguntas apenas para buscar um tratamento especial no resultado.

Schema nao contorna rastreamento, indexacao ou qualidade da pagina

Uma pagina importante bloqueada por noindex, controles de acesso ou regras de rastreamento nao se torna elegivel para resultados de pesquisa por conter JSON-LD. Schema e uma camada de SEO tecnico. Nao substitui rastreabilidade, conteudo util ou experiencia de pagina. Para uma verificacao mais ampla do site, use o diretorio de ferramentas de SEO da Auspia para escolher o fluxo de auditoria adequado.

Checklist antes de publicar

• [ ] O tipo principal da pagina esta declarado e pode ser justificado em uma frase.
• [ ] Cada valor JSON-LD tem uma fonte visivel na pagina ou uma fonte de dados confiavel e renderizada.
• [ ] Nenhuma avaliacao, review, preco, estoque, autor, data, imagem ou dado de organizacao foi inventado.
• [ ] A alteracao nao duplica entidades ja emitidas por um CMS, plugin ou outro componente.
• [ ] O JSON e valido e a marcacao aparece no DOM renderizado semelhante ao de producao.
• [ ] As propriedades obrigatorias para o recurso desejado do Google foram conferidas na documentacao oficial atual.
• [ ] Foram usados o Rich Results Test, quando relevante, e o Schema Markup Validator.
• [ ] Uma Inspecao de URL e uma revisao no Search Console estao agendadas para depois do lancamento.
• [ ] A equipe entende que uma marcacao valida estabelece elegibilidade e clareza, nao uma promessa de resultado aprimorado ou ranking.

Perguntas frequentes

Um SKILL.md pode decidir qual schema meu site precisa?

Ele pode recomendar com base nos fatos da pagina e identificar incognitas, mas nao deve substituir a confirmacao dos fatos. Precos de produtos, avaliacoes, dados da organizacao, autores e datas de publicacao devem vir de uma fonte confiavel da pagina ou do responsavel pela informacao.

O JSON-LD deve ficar no <head> ou no <body>?

O Google aceita JSON-LD tanto no <head> quanto no <body> do HTML. Use o local estavel que seu framework ou CMS consegue manter sincronizado com a pagina. O teste relevante e se o Google pode rastrear uma marcacao valida que corresponda a pagina renderizada.

Por que nada mudou depois que o Rich Results Test passou?

Um teste bem-sucedido confirma sinais de elegibilidade tecnica; ele nao obriga o Google a exibir um resultado aprimorado. O Google seleciona tratamentos de resultado com muitos sinais, incluindo consulta, dispositivo, localizacao e a propria pagina. Verifique consistencia do conteudo e indexabilidade em vez de adicionar propriedades sem suporte.

O Codex deve preencher todas as propriedades do Schema.org que encontrar?

Nao. A documentacao do Google favorece um conjunto menor de propriedades recomendadas, completas e corretas, em vez de muitas propriedades incompletas ou imprecisas. Essa restricao deve estar na Skill, nao apenas em um prompt pontual.

Referencias oficiais

• Google Search Central: Introduction to structured data markup
• Google Search Central: General structured data guidelines
• Google Rich Results Test
• Schema.org

Autor: Julian Mercer, profissional de SEO tecnico com 14 anos de experiencia na Auspia. Julian escreve sobre rastreabilidade, renderizacao, dados estruturados e sistemas tecnicos que as equipes conseguem operar com confiabilidade.