domains / marketing / schema-markup / schema

schema

Skill card

combined

Both copies describe the same task (implementing schema.org/JSON-LD for search), but they contain material, non-overlapping steps and constraints. The coreyhaines31 copy is a focused implementation guide with a specific product-marketing context check, a strict 'check Google feature support first' gate, and explicit retirement dates for FAQPage, HowTo, and WebSite SearchAction. The kostja94 copy adds a multi-engine support matrix (Google vs. Bing vs. AI), a detailed mapping of schema types to SERP features, and a Generative Engine Optimization (GEO) section. Because the first copy lacks the multi-engine/GEO strategy and the second lacks the specific product-context check and the precise 'retired feature' implementation guardrails, crowning one would hide a real alternative approach to the same task.

Repositories

Other copies

Combined skill

---
name: schema
description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Use for JSON-LD, rich snippets, schema.org, FAQ, product, review, breadcrumb, or AI search visibility.
metadata:
  version: 2.1.0
---

# Schema Markup & Structured Data

You are an expert in structured data. Your goal is to implement schema.org markup that helps search engines and AI systems understand content.

## Initial Assessment

1. **Check Context**: If `.agents/product-marketing.md` (or legacy equivalents) exists, read it first. Use that context to avoid redundant questions.
2. **Page Type & Goals**: Identify the page type, current schema state, and target rich results or AI visibility goals.
3. **Engine Support Check**: 
   - **Google**: Check the [Google Search Gallery](https://developers.google.com/search/docs/appearance/structured-data/search-gallery) for current eligibility.
   - **Bing/AI**: Note that Bing and AI engines (Perplexity, etc.) may use Schema.org types even if Google does not display rich results for them.

## Core Principles

- **Accuracy First**: Schema must match visible content. Do not markup non-existent content.
- **JSON-LD Preferred**: Use JSON-LD in `<head>` or end of `<body>`.
- **Feature Eligibility**: Schema.org validity does not equal Google rich result eligibility. 
  - **Retired Google Features**: HowTo (retired Sep 2023), FAQPage (retired/restricted May 2026), and WebSite SearchAction (retired Nov 2024). Do not recommend these for Google rich results, but they may still be useful for Bing or AI understanding.

## Implementation Guide

### Common Types & Requirements
| Type | Required Properties | Notes |
|------|---------------------|-------|
| Organization | name, url | Use for Knowledge Panels |
| Article | headline, image, datePublished, author | ISO 8601 dates |
| Product | name, image, offers | Include price and availability |
| BreadcrumbList | itemListElement | Use for path display |
| FAQPage | mainEntity | Use for AI visibility; check Google eligibility first |

### Multi-Engine & GEO Strategy
- **GEO**: Use Organization, Person, and Article schema to help AI systems (ChatGPT, Gemini) cite your content.
- **@graph**: Combine multiple types (e.g., Organization + BreadcrumbList) using `@graph`.

## Validation

1. **Google Rich Results Test**: Verify Google-specific eligibility.
2. **Schema.org Validator**: Check for general syntax errors.
3. **Search Console**: Monitor for errors in supported features.

## Implementation by Platform

- **Static**: Add JSON-LD to HTML templates/partials.
- **Dynamic (Next.js/React)**: Use server-side rendering to inject JSON-LD.
- **CMS**: Use plugins like Yoast or Rank Math, but verify they don't inject retired types for Google.