schema-markup
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 data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit.
What this skill does
# Schema Markup
## Overview
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.
**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.
## Instructions
### Initial Assessment
Before implementing schema, understand:
1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?
2. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?
3. **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](references/schema-examples.md)
### Quick Reference for Key Types
**Organization:** 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).
### Combining Multiple Schema Types
Use `@graph` to combine multiple schema types on one page:
```json
{
"@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, invalid values (dates must be ISO 8601, URLs fully qualified), mismatch between schema and visible page content.
### Implementation by Stack
**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
Provide complete JSON-LD code blocks ready to paste, plus a testing checklist: validates in Rich Results Test, no errors or warnings, matches page content, all required properties included.
## Examples
### Example 1: Product Schema for a Shopify Store Product Page
**User prompt:** "Add schema markup to our product page for the 'CloudWalk Pro Running Shoe' on our Shopify store. It's $149.99, in stock, and has 4.6 stars from 238 reviews."
The agent will generate a complete Product JSON-LD block including:
- Product type with name, description, image, sku, brand
- Offers with price ($149.99), priceCurrency (USD), availability (InStock), url
- AggregateRating with ratingValue (4.6), reviewCount (238)
- BreadcrumbList for the category path (Home > Running > CloudWalk Pro Running Shoe)
- Implementation instructions specific to Shopify's theme.liquid or a schema app
- Validation steps using Google Rich Results Test
### Example 2: FAQ Schema for a SaaS Pricing Page
**User prompt:** "We have 6 FAQ questions on our pricing page at dashmetrics.com/pricing. Add FAQ schema so they show up as rich results in Google."
The agent will generate a complete FAQPage JSON-LD block:
- FAQPage type with mainEntity array containing all 6 Question/Answer pairs
- Each question with acceptedAnswer containing the full answer text
- Combined with BreadcrumbList schema for the pricing page path using @graph
- Reminder that FAQ content in schema must exactly match the visible FAQ content on the page
- Implementation guidance for their stack (Next.js component, WordPress plugin, or raw HTML)
- Note about monitoring Search Console Enhancements report to verify rich results appear within 1-2 weeks
## Guidelines
- Always check `.claude/product-marketing-context.md` before asking discovery questions
- Always use JSON-LD format since Google explicitly recommends it over Microdata or RDFa
- Never add schema markup for content that does not exist on the visible page since Google penalizes mismatches
- Always include all required properties for each schema type before adding recommended properties
- Validate every schema implementation using the Google Rich Results Test before deploying to production
- When combining multiple schema types on a page, use the @graph pattern to keep them organized in a single script block
- Provide copy-paste-ready JSON-LD code blocks, not abstract descriptions of what to implement
- For dynamic sites, recommend server-side rendering of schema since client-rendered JSON-LD may not be reliably crawled
- Monitor Search Console Enhancements reports after deployment to catch validation errors early
Related in Ads & Marketing
ads
IncludedMulti-platform paid advertising audit and optimization skill. Analyzes Google, Meta, YouTube, LinkedIn, TikTok, Microsoft, and Apple Ads. 250+ checks with scoring, parallel agents, industry templates, and AI creative generation.
banana
IncludedAI image generation Creative Director powered by Google Gemini Nano Banana models. Use this skill for ANY request involving image creation, editing, visual asset production, or creative direction. Triggers on: generate an image, create a photo, edit this picture, design a logo, make a banner, visual for my anything, and all /banana commands. Handles text-to-image, image editing, multi-turn creative sessions, batch workflows, and brand presets.
rpg-migration-analyzer
IncludedAnalyzes legacy RPG (Report Program Generator) programs from AS/400 and IBM i systems for migration to modern Java applications. Extracts business logic from RPG III/IV/ILE source code, identifies data structures (D-specs), file operations (F-specs), program dependencies (CALLB/CALLP), and converts RPG constructs to Java equivalents. Generates migration reports, complexity estimates, and Java implementation strategies with POJO classes, JPA entities, and service methods. Use when modernizing AS/400 or IBM i legacy systems, analyzing RPG source files (.rpg, .rpgle, .RPGLE), converting RPG to Java, mapping data specifications to Java classes, planning legacy system migration, or when user mentions RPG analysis, Report Program Generator, RPG III/IV/ILE, AS/400 modernization, IBM i migration, packed decimal conversion, or mainframe application rewrite.
brand-library-architect
IncludedBuild a complete brand library for a product — visual asset render pipeline, brand documentation set (BRAND, COPY, MANIFESTO, BIOS, FAQ, GLOSSARY, TONE, PRICING), open-source convention files (README, CONTRIBUTING, SECURITY, CODE_OF_CONDUCT), and a self-contained press kit. This skill should be used when the user asks to "build a brand library / brand kit / press kit / brand assets" for a product, "set up a brand library workflow," "create a positioning manifesto plus visual identity," or any combination of brand documentation + visual asset pipeline. Apply phase-by-phase or run end-to-end. Templates are product-agnostic and use {{TOKEN}} placeholders the skill prompts the user to fill.
writing-tech-post
IncludedAuthors engineering blog posts end-to-end: launch deep-dives, incident postmortems, architecture migrations, performance case studies, tutorials, AI/agent system writeups, security disclosures, and research-to-product translations. Picks the correct archetype, plans the abstraction ladder, enforces an evidence cadence (diagrams, benchmarks, profiles, traces, code, ablations), tunes voice against publisher house styles (Datadog, Vercel, GitHub, AWS, Meta, Cloudflare, Jane Street), and runs a pre-publish gate for narrative momentum and disclosure ethics. Use when drafting a new engineering post, restructuring a draft that feels flat, deciding which evidence form belongs where, validating that depth and product context are balanced, or preparing a postmortem, migration, or performance narrative for external publication. Do not use for API reference documentation, README authoring, marketing copy, release notes, generic SEO content, ghost-written executive thought leadership, or non-engineering long-form essays.
blog-google
IncludedGoogle API integration for blog performance: PageSpeed Insights, CrUX Core Web Vitals with 25-week history, Search Console performance, URL Inspection, Indexing API, GA4 organic traffic, NLP entity analysis for E-E-A-T, YouTube video search for embedding, and Google Ads Keyword Planner. Progressive feature availability based on credential tier (API key, OAuth/service account, GA4, Ads). Shares config with claude-seo at ~/.config/claude-seo/google-api.json. Use when user says "google data", "page speed", "core web vitals", "search console", "indexation", "GA4", "keyword research", "nlp entities", "blog performance", "youtube search", "google api setup".