Use this skill when implementing structured data markup using JSON-LD and Schema.org vocabulary for rich search results. Triggers on adding schema markup for FAQ, HowTo, Product, Article, Breadcrumb, Organization, LocalBusiness, Event, Recipe, or any Schema.org type. Covers JSON-LD implementation, Google Rich Results eligibility, validation testing, and framework integration (Next.js, Nuxt, Astro).
Use this skill when implementing structured data markup using JSON-LD and Schema.org vocabulary for rich search results. Triggers on adding schema markup for FAQ, HowTo, Product, Article, Breadcrumb, Organization, LocalBusiness, Event, Recipe, or any Schema.org type. Covers JSON-LD implementation, Google Rich Results eligibility, validation testing, and framework integration (Next.js, Nuxt, Astro).
When this skill is activated, always start your first response with the 🧢 emoji.
Schema Markup / Structured Data
Schema markup is machine-readable context added to web pages that tells search engines
what your content means, not just what it says. JSON-LD (JavaScript Object Notation
for Linked Data) is Google's recommended implementation format - injected via a
<script type="application/ld+json"> tag rather than woven into the HTML. Implementing
correct structured data makes pages eligible for rich results in Google Search: star
ratings, FAQ dropdowns, breadcrumb trails, recipe cards, event listings, and more.
Rich results increase click-through rates by making listings visually distinct in the SERP.
When to use this skill
Trigger this skill when the user:
Wants to implement structured data or schema markup on a page
Asks about adding FAQ schema, Product schema, Article schema, or any Schema.org type
Needs to add breadcrumb navigation markup
Wants to make a page eligible for Google rich results or rich snippets
Asks to validate or debug structured data errors in Google Search Console
Needs to integrate JSON-LD into a framework (Next.js, Nuxt, Astro, etc.)
Asks which schema type to use for a given content type
Do NOT trigger this skill for:
General on-page SEO (meta tags, title tags, keyword optimization) - use technical-seo-engineering instead
Performance or Core Web Vitals improvements - those are separate concerns
Key principles
Always use JSON-LD format - Google recommends JSON-LD over Microdata and RDFa.
JSON-LD keeps structured data separate from HTML, making it easier to maintain
and less error-prone. Inject it in <head> or <body> via a script tag.
Only mark up content visible on the page - Google's guidelines explicitly prohibit
marking up content that users cannot see. If a product price or FAQ answer is not
rendered on the page, do not include it in the schema.
Structured data earns rich results, it does not boost rankings - JSON-LD does
not directly improve a page's position in search results. It makes the page
eligible for enhanced SERP features (stars, FAQs, breadcrumbs). Eligibility does
not guarantee display - Google decides based on query and content quality.
Validate before every deploy - Invalid schema is silently ignored by Google.
Run the Rich Results Test and Schema.org Validator on every significant change.
See .
references/validation-testing.md
One primary type per page, plus supporting types - Each page should have one
main @type matching its primary content (e.g. Product, Article, FAQPage).
Supplementary types like BreadcrumbList or Organization can be added as
additional top-level objects in the same script tag or a separate one.
Core concepts
Schema.org vocabulary is a collaborative ontology backed by Google, Bing, Yahoo,
and Yandex. Every valid type and property is documented at schema.org. The vocabulary
is hierarchical: LocalBusiness extends Organization which extends Thing. Properties
from parent types are inherited by all child types.
JSON-LD structure revolves around three core fields:
@context: always "https://schema.org" - declares the vocabulary
@type: the Schema.org type (e.g. "Product", "FAQPage", "BreadcrumbList")
@id: optional stable URL identifier for the entity (helps Google's Knowledge Graph)
Nesting allows rich relationships. A Product can nest AggregateRating and
Offer objects directly. A HowTo nests HowToStep items. Nesting is preferred
over flat data when the relationship is semantically meaningful.
Required vs recommended properties - Google's documentation distinguishes between
properties required for eligibility and those that are recommended for better
rich result appearance. Missing required fields causes the rich result to be suppressed.
Missing recommended fields may reduce display richness.
Rich Results eligibility is type-specific. Not every Schema.org type produces
a rich result. Google-supported types include: Article, Breadcrumb, Event, FAQ,
HowTo, JobPosting, LocalBusiness, Product, Recipe, Review, VideoObject, and others.
See references/schema-types-catalog.md for the full list with requirements.
Required fields for Product rich results: name, image, plus at least one of
aggregateRating, offers, or review. Always use https://schema.org/ URLs
for itemCondition and availability values.
Add FAQPage schema
Use FAQPage when the page contains a list of question-and-answer pairs where
the user is seeking answers (not a community Q&A page). Each question must appear
on the page - do not include hidden FAQ items.
<scripttype="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is your return policy?",
"acceptedAnswer": {
"@type": "Answer",
"text": "We accept returns within 30 days of purchase. Items must be in original condition."
}
},
{
"@type": "Question",
"name": "Do you offer free shipping?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Free standard shipping on orders over $50 within the contiguous United States."
}
}
]
}
</script>
Implement BreadcrumbList
Breadcrumbs in schema must match the breadcrumb navigation visible on the page.
Position values must start at 1 and increment sequentially.
Use Article for news and blog content, BlogPosting for blog-specific posts.
Both produce the same rich result treatment; BlogPosting is a subtype of Article.
Place Organization on the homepage or about page. Use LocalBusiness (or a
more specific subtype like Restaurant, MedicalBusiness) for businesses with
a physical location.
Use HowTo for step-by-step instructional content. Each step should have a
name (short step title) and text (detailed description). Steps can include
images for richer display.
<scripttype="application/ld+json">
{
"@context": "https://schema.org",
"@type": "HowTo",
"name": "How to Change a Bicycle Tire",
"description": "Step-by-step guide to replacing a flat bicycle tire at home.",
"totalTime": "PT20M",
"tool": [
{ "@type": "HowToTool", "name": "Tire levers" },
{ "@type": "HowToTool", "name": "Pump" }
],
"step": [
{
"@type": "HowToStep",
"position": 1,
"name": "Remove the wheel",
"text": "Loosen the axle nuts or quick-release lever and pull the wheel free from the dropouts."
},
{
"@type": "HowToStep",
"position": 2,
"name": "Remove the tire",
"text": "Insert tire levers under the tire bead and work them around the rim to pop the tire off."
},
{
"@type": "HowToStep",
"position": 3,
"name": "Install the new tube",
"text": "Place the new inner tube inside the tire, seat the valve through the rim hole, then press the tire back onto the rim."
}
]
}
</script>
Framework integration - Next.js App Router
In Next.js App Router, inject JSON-LD using a script tag inside the page component.
Do not use next/head for this - it is not needed for JSON-LD.
For Nuxt, use useHead() composable with a script entry. For Astro, inject the
script tag directly in the .astro component's <head> slot. Both follow the
same pattern: serialize the object and inject as type="application/ld+json".
Gotchas
Rich Results Test passes but nothing appears in SERPs - Passing validation only confirms syntax correctness. Google still decides whether to display rich results based on content quality, query relevance, and site authority. Schema eligibility is not a guarantee of display.
Product schema with dynamic pricing goes stale - If price or availability are hardcoded in the template rather than dynamically rendered from live data, they drift out of sync. Google issues manual actions for misleading structured data. Always generate these fields server-side from live inventory.
FAQPage on community Q&A pages triggers spam detection - FAQPage is for single-author authoritative Q&A (e.g., a brand's own FAQ). Marking up a community forum or user-generated Q&A as FAQPage violates Google's guidelines and can result in the rich result being suppressed across the entire domain.
Multiple @type blocks for the same entity cause conflicts - Having two separate <script type="application/ld+json"> blocks that both describe the same Product or Organization creates conflicting signals. Combine into one block or use an array at the top level.
Next.js dangerouslySetInnerHTML without JSON sanitization - If any product name or description contains a </script> string (possible in user-generated content), it will break the JSON-LD block. Always sanitize dynamic strings or use a JSON serialization library that escapes special characters.
Anti-patterns / common mistakes
Mistake
Why it's wrong
What to do instead
Marking up hidden content
Google's guidelines prohibit schema for content not rendered to users. Penalizable as spam.
Only include data that is visible and readable on the page
Duplicate @type declarations
Multiple conflicting schema blocks for the same entity confuse parsers and waste crawl budget
Use one block per entity; combine supporting types in the same <script> tag as an array
Using Microdata instead of JSON-LD
Microdata is tightly coupled to HTML structure, harder to maintain, and error-prone when HTML changes
Use JSON-LD exclusively; it is decoupled from HTML markup
Wrong availability / itemCondition values
Using plain strings like "InStock" instead of the full schema.org URL causes validation errors
Use full URLs: "https://schema.org/InStock", "https://schema.org/NewCondition"
Skipping validation before deploy
Invalid schema is silently ignored - no error, no rich result, no feedback loop
Run Rich Results Test at search.google.com/test/rich-results before every deploy
Assuming schema improves rankings
Schema does not directly affect ranking position; misplaced expectations lead to wasted effort
Use schema for rich result eligibility and CTR improvement, not ranking manipulation
Stale price / availability data
Product offers with outdated prices trigger Search Console warnings and damage trust
Keep price and availability dynamically generated from live data; set priceValidUntil
References
For deep detail on specific topics, load the relevant file from references/:
references/schema-types-catalog.md - Full catalog of Google-supported Schema.org types with required/recommended fields and JSON-LD examples. Load when selecting the right type or checking required properties.
references/validation-testing.md - How to validate structured data with Rich Results Test, Search Console, and CI/CD integration. Load when debugging schema errors or setting up automated validation.
Only load a references file if the current task requires detail beyond what is in this SKILL.md.
Companion check
On first activation of this skill in a conversation: check which companion skills are installed by running ls ~/.claude/skills/ ~/.agent/skills/ ~/.agents/skills/ .claude/skills/ .agent/skills/ .agents/skills/ 2>/dev/null. Compare the results against the recommended_skills field in this file's frontmatter. For any that are missing, mention them once and offer to install:
