back
loading skill details...
When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured…
Schema Markup
You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.
Initial Assessment
Check for product marketing context first:
If .agents/product-marketing-context.md exists (or .claude/product-marketing-context.md in older setups), read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
Before implementing schema, understand:
Page Type - What kind of page? What's the primary content? What rich results are possible?
Current State - Any existing schema? Errors in implementation? Which rich results already appearing?
Goals - Which rich results are you targeting? What's the business value?
Core Principles
1. Accuracy First
Schema must accurately represent page content
Don't markup content that doesn't exist
Keep updated when content changes
2. Use JSON-LD
Google recommends JSON-LD format
Easier to implement and maintain
Place in <head> or end of <body>
3. Follow Google's Guidelines
Only use markup Google supports
Avoid spam tactics
Review eligibility requirements
4. Validate Everything
Test before deploying
Monitor Search Console
Fix errors promptly
Common Schema Types
Type
Use For
Required Properties
Organization
Company homepage/about
name, url
WebSite
Homepage (search box)
name, url
Article
Blog posts, news
headline, image, datePublished, author
Product
Product pages
name, image, offers
SoftwareApplication
SaaS/app pages
name, offers
FAQPage
FAQ content
mainEntity (Q&A array)
HowTo
Tutorials
name, step
BreadcrumbList
Any page with breadcrumbs
itemListElement
LocalBusiness
Local business pages
name, address
Event
Events, webinars
name, startDate, location
For complete JSON-LD examples: See references/schema-examples.md
Quick Reference
Organization (Company Page)
Required: name, url
Recommended: logo, sameAs (social profiles), contactPoint
Article/BlogPosting
Required: headline, image, datePublished, author
Recommended: dateModified, publisher, description
Product
Required: name, image, offers (price + availability)
Recommended: sku, brand, aggregateRating, review
FAQPage
Required: mainEntity (array of Question/Answer pairs)
BreadcrumbList
Required: itemListElement (array with position, name, item)
Multiple Schema Types
You can combine multiple schema types on one page using @graph:
{
"@context": "https://schema.org",
"@graph": [
{ "@type": "Organization", ... },
{ "@type": "WebSite", ... },
{ "@type": "BreadcrumbList", ... }
]
}
Validation and Testing
Tools
Google Rich Results Test: https://search.google.com/test/rich-results
Schema.org Validator: https://validator.schema.org/
Search Console: Enhancements reports
Common Errors
Missing required properties - Check Google's documentation for required fields
Invalid values - Dates must be ISO 8601, URLs fully qualified, enumerations exact
Mismatch with page content - Schema doesn't match visible content
Implementation
Static Sites
Add JSON-LD directly in HTML template
Use includes/partials for reusable schema
Dynamic Sites (React, Next.js)
Component that renders schema
Server-side rendered for SEO
Serialize data to JSON-LD
CMS / WordPress
Plugins (Yoast, Rank Math, Schema Pro)
Theme modifications
Custom fields to structured data
Output Format
Schema Implementation
// Full JSON-LD code block
{
"@context": "https://schema.org",
"@type": "...",
// Complete markup
}
Testing Checklist
Validates in Rich Results Test
No errors or warnings
Matches page content
All required properties included
Task-Specific Questions
What type of page is this?
What rich results are you hoping to achieve?
What data is available to populate the schema?
Is there existing schema on the page?
What's your tech stack?
Related Skills
seo-audit: For overall SEO including schema review
ai-seo: For AI search optimization (schema helps AI understand content)
programmatic-seo: For templated schema at scale
site-architecture: For breadcrumb structure and navigation schema planningdon't have the plugin yet? install it then click "run inline in claude" again.