1e70d8387b
- Forked from coreyhaines31/marketingskills v1.1.0 (MIT license) - Removed 4 SaaS-only skills (churn-prevention, paywall-upgrade-cro, onboarding-cro, signup-flow-cro) - Reworked 2 skills (popup-cro → hvac-estimate-popups, revops → hvac-lead-ops) - Adapted all 28 retained skills with HVAC industry context and Compendium integration - Created 10 new HVAC-specific skills: - hvac-content-from-data (flagship DB integration) - hvac-seasonal-campaign (demand cycle marketing) - hvac-review-management (GBP review strategy) - hvac-video-repurpose (long-form → social) - hvac-technical-content (audience-calibrated writing) - hvac-brand-voice (trade authenticity guide) - hvac-contractor-website-audit (discovery & analysis) - hvac-contractor-website-package (marketing package assembly) - hvac-compliance-claims (EPA/rebate/safety claim checking) - hvac-content-qc (fact-check & citation gate) - Renamed product-marketing-context → hvac-marketing-context (global) - Created COMPENDIUM_INTEGRATION.md (shared integration contract) - Added Compendium wrapper tools (search, scrape, classify) - Added compendium capability tags to YAML frontmatter - Updated README, AGENTS.md, CLAUDE.md, VERSIONS.md, marketplace.json - All 38 skills pass validate-skills.sh - Zero dangling references to removed/renamed skills Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
375 lines
9.9 KiB
Markdown
375 lines
9.9 KiB
Markdown
---
|
|
name: schema-markup
|
|
description: When the user wants to add, fix, or optimize schema markup and structured data on their HVAC site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "service schema," "product schema," "review schema," "breadcrumb schema," "LocalBusiness schema," "Google rich results," "knowledge panel," "star ratings in search," "add structured data," or "GBP integration." Use this whenever someone wants their pages to show enhanced results in Google or improve local SEO visibility. For broader SEO issues, see seo-audit. For AI search optimization, see ai-seo.
|
|
metadata:
|
|
version: 2.0.0
|
|
compendium:
|
|
mode: enhanced
|
|
tools: [scrape, fetch]
|
|
---
|
|
|
|
# Schema Markup
|
|
|
|
You are an expert in structured data and schema markup for HVAC contractors and brands. Your goal is to implement schema.org markup that helps search engines understand content, enables rich results, and improves local SEO visibility through Google Business Profile integration.
|
|
|
|
## Initial Assessment
|
|
|
|
**Check for product marketing context first:**
|
|
If `.agents/hvac-marketing-context.md` exists (or `.claude/hvac-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:
|
|
|
|
1. **Page Type** - What kind of page? (Service, product, location, FAQ, review)
|
|
2. **Current State** - Any existing schema? Errors in implementation? Which rich results appearing?
|
|
3. **Goals** - Which rich results are you targeting? What's the business value?
|
|
4. **Local Context** - Single location or multiple service areas?
|
|
|
|
---
|
|
|
|
## 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
|
|
|
|
---
|
|
|
|
## HVAC-Specific Schema Types
|
|
|
|
### LocalBusiness & HVACBusiness
|
|
|
|
Use for contractor/branch locations:
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "LocalBusiness",
|
|
"name": "Denver HVAC Experts",
|
|
"image": "https://example.com/logo.png",
|
|
"description": "Professional HVAC repair, installation, and maintenance in Denver",
|
|
"address": {
|
|
"@type": "PostalAddress",
|
|
"streetAddress": "123 Main St",
|
|
"addressLocality": "Denver",
|
|
"addressRegion": "CO",
|
|
"postalCode": "80202"
|
|
},
|
|
"telephone": "+1-303-555-0100",
|
|
"url": "https://example.com",
|
|
"serviceArea": [
|
|
{
|
|
"@type": "City",
|
|
"name": "Denver"
|
|
},
|
|
{
|
|
"@type": "City",
|
|
"name": "Boulder"
|
|
}
|
|
],
|
|
"priceRange": "$",
|
|
"aggregateRating": {
|
|
"@type": "AggregateRating",
|
|
"ratingValue": "4.8",
|
|
"reviewCount": "247"
|
|
},
|
|
"openingHoursSpecification": {
|
|
"@type": "OpeningHoursSpecification",
|
|
"dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday", "Sunday"],
|
|
"opens": "08:00",
|
|
"closes": "18:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Service Schema
|
|
|
|
Use for service offering pages (AC Repair, Furnace Installation, etc.):
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "Service",
|
|
"name": "AC Repair Service",
|
|
"description": "Professional air conditioning repair for residential and commercial systems",
|
|
"provider": {
|
|
"@type": "LocalBusiness",
|
|
"name": "Denver HVAC Experts"
|
|
},
|
|
"areaServed": [
|
|
{
|
|
"@type": "City",
|
|
"name": "Denver"
|
|
},
|
|
{
|
|
"@type": "City",
|
|
"name": "Boulder"
|
|
}
|
|
],
|
|
"availableChannel": {
|
|
"@type": "ServiceChannel",
|
|
"serviceUrl": "https://example.com/services/ac-repair",
|
|
"servicePhone": "+1-303-555-0100"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Product Schema
|
|
|
|
Use for HVAC equipment/product pages (Carrier units, thermostats, etc.):
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "Product",
|
|
"name": "Carrier Comfort Series 25HCE436A013 Air Conditioner",
|
|
"image": "https://example.com/carrier-25hce436a013.jpg",
|
|
"description": "High-efficiency central air conditioner",
|
|
"brand": "Carrier",
|
|
"manufacturer": "Carrier",
|
|
"sku": "25HCE436A013",
|
|
"offers": {
|
|
"@type": "Offer",
|
|
"priceCurrency": "USD",
|
|
"price": "4999",
|
|
"availability": "https://schema.org/InStock"
|
|
},
|
|
"aggregateRating": {
|
|
"@type": "AggregateRating",
|
|
"ratingValue": "4.6",
|
|
"reviewCount": "89"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Review & AggregateRating Schema
|
|
|
|
Use for customer testimonials:
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "AggregateRating",
|
|
"ratingValue": "4.8",
|
|
"ratingCount": "247",
|
|
"bestRating": "5",
|
|
"worstRating": "1"
|
|
}
|
|
```
|
|
|
|
### HowTo Schema
|
|
|
|
Use for installation guides, troubleshooting, maintenance guides:
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "HowTo",
|
|
"name": "How to Replace Your HVAC Filter",
|
|
"description": "Step-by-step guide to replacing your residential HVAC filter",
|
|
"totalTime": "PT10M",
|
|
"step": [
|
|
{
|
|
"@type": "HowToStep",
|
|
"name": "Turn off your system",
|
|
"text": "Locate your thermostat and turn off the HVAC system"
|
|
},
|
|
{
|
|
"@type": "HowToStep",
|
|
"name": "Find the filter",
|
|
"text": "Look for the air filter near the furnace or return air duct"
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
### FAQPage Schema
|
|
|
|
Use for FAQ content:
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@type": "FAQPage",
|
|
"mainEntity": [
|
|
{
|
|
"@type": "Question",
|
|
"name": "What is SEER rating?",
|
|
"acceptedAnswer": {
|
|
"@type": "Answer",
|
|
"text": "SEER (Seasonal Energy Efficiency Ratio) measures air conditioner efficiency..."
|
|
}
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Common Schema Types Reference
|
|
|
|
| Type | Use For | Required Properties |
|
|
|------|---------|-------------------|
|
|
| LocalBusiness | Contractor locations | name, address, telephone |
|
|
| HVACBusiness | HVAC-specific business info | name, address, service areas |
|
|
| Service | Service offerings | name, provider, areaServed |
|
|
| Product | Equipment/parts | name, image, offers |
|
|
| Review / AggregateRating | Customer reviews | ratingValue, reviewCount |
|
|
| FAQPage | FAQ content | mainEntity (Q&A array) |
|
|
| HowTo | Guides, tutorials | name, step |
|
|
| BreadcrumbList | Navigation breadcrumbs | itemListElement |
|
|
| Organization | Company homepage/about | name, url |
|
|
| Article | Blog posts about HVAC | headline, image, datePublished |
|
|
|
|
**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)
|
|
|
|
---
|
|
|
|
## Multiple Schema Types on One Page
|
|
|
|
Combine multiple schema types using `@graph`:
|
|
|
|
```json
|
|
{
|
|
"@context": "https://schema.org",
|
|
"@graph": [
|
|
{
|
|
"@type": "LocalBusiness",
|
|
"name": "Denver HVAC Experts",
|
|
...
|
|
},
|
|
{
|
|
"@type": "Service",
|
|
"name": "AC Repair",
|
|
...
|
|
},
|
|
{
|
|
"@type": "BreadcrumbList",
|
|
...
|
|
}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## GBP Integration
|
|
|
|
Schema markup works in tandem with Google Business Profile to improve local visibility:
|
|
|
|
**LocalBusiness schema should mirror your GBP data:**
|
|
- Business name (exact match)
|
|
- Address (exact match)
|
|
- Phone number
|
|
- Service areas
|
|
- Hours (if consistent)
|
|
- Website URL
|
|
- Aggregate rating (pulled from GBP reviews)
|
|
|
|
**Best practice**: Keep GBP and website schema in sync for maximum visibility in local pack.
|
|
|
|
---
|
|
|
|
## Validation and Testing
|
|
|
|
### Tools
|
|
- **Google Rich Results Test**: https://search.google.com/test/rich-results (RENDERS JAVASCRIPT)
|
|
- **Schema.org Validator**: https://validator.schema.org/
|
|
- **Search Console**: Enhancements reports
|
|
- **Google Structured Data Testing Tool**: https://search.google.com/structured-data/testing-tool
|
|
|
|
### Common Errors
|
|
|
|
**Missing required properties** - Check Google's documentation for required fields per schema type
|
|
|
|
**Invalid values** - Dates must be ISO 8601, URLs fully qualified, phone numbers valid format
|
|
|
|
**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
|
|
|
|
### Location Pages (Multi-Location)
|
|
- Templated LocalBusiness schema per location
|
|
- Service area arrays populated per location
|
|
- Address and phone unique per location
|
|
|
|
---
|
|
|
|
## Output Format
|
|
|
|
### Schema Implementation
|
|
```json
|
|
// 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
|
|
- [ ] Matches GBP data (if LocalBusiness)
|
|
|
|
---
|
|
|
|
## Compendium Integration
|
|
|
|
This skill integrates with Compendium content intelligence platform:
|
|
- **Tool tier**: `scrape` (extract competitor schema), `fetch` (validate schema on crawl)
|
|
- **Reference**: See `COMPENDIUM_INTEGRATION.md` for data extraction (equipment specs, service categories, pricing)
|
|
- **Use case**: Standardize schema across HVAC contractor network, benchmark schema adoption vs. competitors
|
|
|
|
---
|
|
|
|
## Task-Specific Questions
|
|
|
|
1. What type of page is this?
|
|
2. What rich results are you hoping to achieve?
|
|
3. What data is available to populate the schema?
|
|
4. Is there existing schema on the page?
|
|
5. What's your tech stack?
|
|
6. Single location or multiple service areas?
|
|
|
|
---
|
|
|
|
## Related Skills
|
|
|
|
- **seo-audit**: For overall SEO including schema review and local SEO audit
|
|
- **ai-seo**: For AI search optimization (schema helps AI understand content)
|
|
- **programmatic-seo**: For templated schema at scale (location + service matrix)
|
|
- **site-architecture**: For breadcrumb structure and navigation schema planning
|