Loading source
Pulling the file list, source metadata, and syntax-aware rendering for this listing.
Source from repo
Implements schema.org structured data (JSON-LD) to enable rich results in Google Search for any page type.
Files
Skill
Size
Entrypoint
Format
Open file
Syntax-highlighted preview of this file as included in the skill package.
SKILL.md
1---2name: schema-markup3description: 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," "breadcrumb schema," "Google rich results," "knowledge panel," "star ratings in search," or "add structured data." Use this whenever someone wants their pages to show enhanced results in Google. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.4metadata:5version: 1.1.06---7# Schema Markup9You 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.11## Initial Assessment13**Check for product marketing context first:**15If `.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.16Before implementing schema, understand:181. **Page Type** - What kind of page? What's the primary content? What rich results are possible?202. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?223. **Goals** - Which rich results are you targeting? What's the business value?24---26## Core Principles28### 1. Accuracy First30- Schema must accurately represent page content31- Don't markup content that doesn't exist32- Keep updated when content changes33### 2. Use JSON-LD35- Google recommends JSON-LD format36- Easier to implement and maintain37- Place in `<head>` or end of `<body>`38### 3. Follow Google's Guidelines40- Only use markup Google supports41- Avoid spam tactics42- Review eligibility requirements43### 4. Validate Everything45- Test before deploying46- Monitor Search Console47- Fix errors promptly48---50## Common Schema Types52| Type | Use For | Required Properties |54|------|---------|-------------------|55| Organization | Company homepage/about | name, url |56| WebSite | Homepage (search box) | name, url |57| Article | Blog posts, news | headline, image, datePublished, author |58| Product | Product pages | name, image, offers |59| SoftwareApplication | SaaS/app pages | name, offers |60| FAQPage | FAQ content | mainEntity (Q&A array) |61| HowTo | Tutorials | name, step |62| BreadcrumbList | Any page with breadcrumbs | itemListElement |63| LocalBusiness | Local business pages | name, address |64| Event | Events, webinars | name, startDate, location |65**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)67---69## Quick Reference71### Organization (Company Page)73Required: name, url74Recommended: logo, sameAs (social profiles), contactPoint75### Article/BlogPosting77Required: headline, image, datePublished, author78Recommended: dateModified, publisher, description79### Product81Required: name, image, offers (price + availability)82Recommended: sku, brand, aggregateRating, review83### FAQPage85Required: mainEntity (array of Question/Answer pairs)86### BreadcrumbList88Required: itemListElement (array with position, name, item)89---91## Multiple Schema Types93You can combine multiple schema types on one page using `@graph`:95```json97{98"@context": "https://schema.org",99"@graph": [100{ "@type": "Organization", ... },101{ "@type": "WebSite", ... },102{ "@type": "BreadcrumbList", ... }103]104}105```106---108## Validation and Testing110### Tools112- **Google Rich Results Test**: https://search.google.com/test/rich-results113- **Schema.org Validator**: https://validator.schema.org/114- **Search Console**: Enhancements reports115### Common Errors117**Missing required properties** - Check Google's documentation for required fields119**Invalid values** - Dates must be ISO 8601, URLs fully qualified, enumerations exact121**Mismatch with page content** - Schema doesn't match visible content123---125## Implementation127### Static Sites129- Add JSON-LD directly in HTML template130- Use includes/partials for reusable schema131### Dynamic Sites (React, Next.js)133- Component that renders schema134- Server-side rendered for SEO135- Serialize data to JSON-LD136### CMS / WordPress138- Plugins (Yoast, Rank Math, Schema Pro)139- Theme modifications140- Custom fields to structured data141---143## Output Format145### Schema Implementation147```json148// Full JSON-LD code block149{150"@context": "https://schema.org",151"@type": "...",152// Complete markup153}154```155### Testing Checklist157- [ ] Validates in Rich Results Test158- [ ] No errors or warnings159- [ ] Matches page content160- [ ] All required properties included161---163## Task-Specific Questions1651. What type of page is this?1672. What rich results are you hoping to achieve?1683. What data is available to populate the schema?1694. Is there existing schema on the page?1705. What's your tech stack?171---173## Related Skills175- **seo-audit**: For overall SEO including schema review177- **ai-seo**: For AI search optimization (schema helps AI understand content)178- **programmatic-seo**: For templated schema at scale179- **site-architecture**: For breadcrumb structure and navigation schema planning180