Kostja Zhang

---
name: branding
description: When the user wants to define, audit, or apply brand strategy—purpose, values, positioning, storytelling, voice, narrative (not only visuals). Also use when the user mentions "brand strategy," "brand story," "brand storytelling," "brand voice," "brand identity," "brand guidelines," "brand purpose," "brand values," "origin story," "brand narrative," "brand personality," "brand archetype," "slide deck branding," "PPT brand colors," or "document style guide." For typography, colors, design tokens, and frontend visuals, use brand-visual-generator.
license: MIT
metadata:
  version: 1.2.0
---

# Strategies: Branding

Guides brand strategy: purpose, values, positioning, storytelling, voice, and visual identity. Companies with consistent branding see 23–33% revenue lift; people remember stories ~22× more than facts alone. Use this skill when defining a new brand, auditing consistency, or aligning messaging across touchpoints.

**Keywords**: brand strategy, brand guidelines, visual identity, storytelling, brand voice, design tokens, slide deck, corporate identity, style guide, positioning

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope

- **Brand strategy**: Purpose, values, positioning, differentiation, target audience
- **Brand storytelling**: Origin story, hero's journey, narrative arc, brand archetypes
- **Brand voice & tone**: Voice, tone, avoid terms, preferred wording
- **Brand visual identity**: Colors, typography, logo rules—strategy layer; implementation in **brand-visual-generator**, **logo-generator**

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read Sections 2 (Positioning), 3 (Value Proposition), 8 (Brand & Voice), 12 (Visual Identity).

Identify:
1. **Scope**: New brand, audit, or alignment
2. **Touchpoints**: Website, social, product UI, directories, content
3. **Existing assets**: Brand guide, logo, style guide

## Brand Strategy Pillars

| Pillar | Purpose |
|--------|---------|
| **Brand purpose** | Why the brand exists beyond profit; one sentence |
| **Brand values** | 4–5 core values; what you stand for; differentiators |
| **Target audience** | Who you serve; ICP; jobs to be done |
| **Positioning** | For [customer] who [need], our [product] is a [category] that [benefit]. Unlike [competitor], we [differentiator] because [reasons] |
| **Differentiation** | Why you, not alternatives; concrete, not vague |

## Brand Storytelling

### Origin Story

- **What**: Journey, founding, milestones, personal experiences that shaped the company
- **Why**: Emotional connection; 58% of customers buy based on company values
- **Elements**: Who founded it; why created; challenges overcome; vision; how it evolved

### Hero's Journey (Customer as Hero)

| Element | Content |
|---------|---------|
| **Hero** | Your customer; their needs, wants, context |
| **Problem** | What they face; how they solve it now |
| **Inciting insight** | Reframing that creates urgency |
| **Brand's role** | Guide, tool, or partner—not hero; how you enable resolution |
| **Transformation** | What better future looks like; proof (case studies, testimonials) |

### Brand Narrative Arc

- **Protagonist**: Customer facing a challenge
- **Stakes**: What happens if nothing changes
- **Proof**: Data, case studies, testimonials
- **CTA**: Place call to action in the story; provoke action

### Brand Archetypes (12 Types)

| Archetype | Tone | Example |
|-----------|------|---------|
| **Creator** | Innovative, imaginative | Adobe |
| **Caregiver** | Nurturing, supportive | Johnson & Johnson |
| **Ruler** | Authoritative, premium | Mercedes-Benz |
| **Innocent** | Simple, optimistic | Coca-Cola |
| **Sage** | Wise, knowledgeable | Google |
| **Explorer** | Adventurous, independent | Patagonia |
| **Outlaw** | Rebellious, disruptive | Harley-Davidson |
| **Magician** | Transformative, visionary | Disney |
| **Hero** | Courageous, determined | Nike |
| **Lover** | Passionate, sensual | Chanel |
| **Jester** | Playful, fun | M&M's |
| **Everyman** | Relatable, down-to-earth | IKEA |

Align archetype to customer personality; strengthens storytelling.

## Brand Voice & Tone

| Element | Definition | Example |
|---------|------------|---------|
| **Voice** | Brand personality; consistent across touchpoints | Professional / Friendly / Technical / Bold |
| **Tone** | How you say it; adapts to context | Confident but not arrogant; helpful; concise |
| **Avoid** | Buzzwords, terms to never use | "streamline," "revolutionize," "synergy" |
| **Preferred** | Terms to use consistently | "audit" not "analysis"; "customer" not "user" |

**Product marketing context Section 8**: Document voice, tone, avoid, preferred terms. See **project-context** template.

## Brand Visual Identity (Strategy Layer)

| Element | Strategy | Implementation |
|---------|----------|-----------------|
| **Colors** | Primary, secondary, CTA; industry mapping | **brand-visual-generator** |
| **Typography** | Display + body; hierarchy; pairing | **brand-visual-generator** |
| **Logo** | Variants, clear space, minimum size | **logo-generator** |
| **Imagery** | Tone, subject matter, visual mood | Brand guidelines |
| **Consistency** | Same identity across web, social, product | All touchpoints |

For full visual specs (fonts, HEX, spacing), see **brand-visual-generator**. For logo placement and implementation, see **logo-generator**.

## Brand Guidelines Structure

Single source of truth. Include:

- **Purpose & values**: Why you exist; what you stand for
- **Positioning**: One-liner; differentiation
- **Story**: Origin story; hero's journey summary
- **Voice & tone**: Voice, tone, avoid, preferred
- **Logo**: Usage rules, clear space, variants (light/dark)
- **Colors**: Primary, secondary, CTA (HEX, RGB, CMYK)
- **Typography**: Font families, hierarchy, sizing
- **Imagery**: Photography tone; iconography style

## Visual Specification Delivery (Design Tokens)

When the user needs **actionable specs** (not only strategy)—for web, slides, or print—produce a **token table** the team can paste into a design system, media kit, or slide master. Align with **brand-visual-generator** for full web/CSS detail.

| Token category | What to document | Example fields |
|----------------|------------------|----------------|
| **Colors** | Named roles + values for light/dark if applicable | Primary `#______`, text primary `#______`, background `#______`, accent 1–3, CTA, border, error/success |
| **Typography** | Family, weight, size scale, line-height | Display / H1–H3 / body / caption; web-safe or system fallbacks |
| **Spacing** | Base unit and scale | e.g. 8px base; section gaps; logo clear space in `em` or `px` |
| **Non-text accents** | Charts, shapes, dividers | Rotate accent colors; avoid arbitrary one-off hues outside palette |

**Applying tokens across surfaces**

- **Web / product**: CSS variables or design tokens; see **brand-visual-generator**.
- **Slides (PowerPoint, Google Slides, Keynote)**: Set slide master background + default title/body fonts from token table; map theme colors to primary/secondary/background/text; reuse one accent per deck section where possible.
- **Documents (Word, Google Docs, PDF)**: Define paragraph styles (Title, Heading 1–3, Normal, Caption) with fonts and colors from tokens; set default page background if brand uses off-white.

If the user **pastes an existing brand PDF or bullet list**, extract and normalize into this token table before suggesting implementation.

## Output Format

- **Brand strategy** (purpose, values, positioning, differentiation)
- **Story** (origin story, hero's journey, narrative arc)
- **Voice & tone** (voice, tone, avoid, preferred)
- **Archetype** (if applicable)
- **Visual** (high-level; defer to brand-visual-generator for web specs)
- **Design token table** (colors, type scale, spacing) when deliverable must be implementation-ready
- **Slide/document notes** (master fonts, theme colors) when touchpoints include decks or docs
- **Context template** for project-context Sections 8, 12

## Related Skills

- **about-page-generator**: About page implements brand story, mission, values
- **homepage-generator**: Homepage implements value prop, differentiation, brand voice
- **logo-generator**: Logo placement, implementation; branding defines logo rules
- **brand-visual-generator**: Typography, colors, spacing; branding defines visual strategy
- **media-kit-page-generator**: Media kit hosts brand guidelines
- **directory-submission**: Directory copy uses brand voice; Section 8 Brand & Voice
- **title-tag, meta-description**: Metadata uses brand voice
- **integrated-marketing**: Brand awareness across PESO
- **domain-selection**: Domain choice (Brand/PMD/EMD, TLD); do before or with branding when choosing domain
- **domain-architecture**: Domain structure implements brand architecture (Branded House vs House of Brands)
- **rebranding-strategy**: Rebrand execution; domain change, 301, announcement

---
name: brand-protection
description: When the user faces brand impersonation, fake websites, phishing sites, or trademark infringement. Also use when the user mentions "fake site," "impersonation," "phishing site," "trademark infringement," "domain squatting," or "brand abuse." For monitoring, use brand-monitoring.
metadata:
  version: 1.0.1
---

# Strategy: Brand Protection

Guides discovery, reporting, and prevention of brand impersonation—fake websites, phishing sites, trademark infringement, and domain squatting. See **domain-selection** for defensive domain registration; **trust-badges** for official site verification signals; **about-page** for identity declaration.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for brand name, official domain, and key assets.

Identify:
1. **Impersonation type**: Fake website, phishing, trademark misuse, domain squatting
2. **Evidence available**: Screenshots, URLs, WHOIS, hosting info
3. **Legal assets**: Registered trademark, copyright ownership
4. **Impact**: Traffic interception (fake site ranks for brand queries)? Payment fraud (users pay on fake site, then contact official support)?

## Evidence Collection Checklist

| Item | Action |
|------|--------|
| **Full URLs** | Document all key pages of the fake site |
| **Screenshots** | Homepage, product pages, logo, layout; include date/time |
| **Comparison** | Side-by-side: official vs fake (layout, logo, copy similarity) |
| **WHOIS** | Use [ICANN Lookup](https://lookup.icann.org/) for registrar, creation date, registrant |
| **Hosting** | IP lookup to identify hosting provider |

## Reporting Channels (Priority Order)

| Channel | Entry | Use Case |
|---------|-------|----------|
| **Domain registrar** | Abuse / Report Misuse on registrar site | Brand impersonation, trademark, fraud |
| **Hosting provider** | Same; submit abuse form | Hosting infringing content |
| **Google Safe Browsing** | [Report Phishing](https://safebrowsing.google.com/safebrowsing/report_phish/) | Phishing / impersonation risk |
| **Google Trademark** | [Trademark Complaint](https://services.google.com/inquiry/aw_tmcomplaint) or [email protected] | Trademark infringement in search; requires registered trademark |
| **Bing Content Removal** | [Content Moderation Platform](https://www.bing.com/webmaster/contentremovalform/showanonymouspage) | Copyright/trademark; content removal from Bing |
| **Payment processors** | PayPal Resolution Center, Stripe support | If fake site accepts payments; report fraud |
| **Social platforms** | X, Facebook, Instagram abuse forms | If fake site is promoted or linked there |
| **Google Ads / Microsoft Ads** | Platform trademark complaint forms | If impersonator runs brand ads |
| **DMCA** | To hosting provider | Copyright infringement; images, copy, design copied |
| **ICANN** | [DNS Abuse complaint](https://www.icann.org/en/system/files/files/submitting-dns-abuse-complaints-icann-guide-17nov25-en.pdf) | If registrar does not respond within reasonable time |

**Report content**: Include full URL, clear description of fraudulent activity, and all evidence (screenshots, logs).

## Reporting Best Practices

**Registrar vs hosting**: Use [ICANN Lookup](https://lookup.icann.org/) for registrar. For hosting, use IP lookup (HostingCheckerOnline, HostingDetector, ipinfo.io) to find origin server—registrar may be Cloudflare while origin host is elsewhere; report to both.

**Cloudflare as registrar**: Use [abuse.cloudflare.com](https://abuse.cloudflare.com/) or [abuse form](https://abuse.cloudflare.com/phishing); select "Phishing & Malware" for impersonation. Email complaints are generally not processed; use the online form. Provide specific URLs of infringing pages.

**Hosting detection**: Sites behind Cloudflare CDN hide origin IP. Use reverse IP lookup or hosting detection tools to identify underlying host; submit abuse to that provider as well.

**Parallel reporting**: Submit to registrar, host, and Google Safe Browsing simultaneously; do not wait for one before others. Google trademark review takes 1–8 weeks.

## Legal Options

| Option | When | Notes |
|--------|------|-------|
| **Cease and desist** | Trademark infringement | Lawyer-drafted; often first step |
| **DMCA takedown** | Copyrighted material copied | Images, copy, design; hosting providers typically comply |
| **Consumer protection** | Scam / fraud | FTC ReportFraud.ftc.gov (US) |
| **Law enforcement** | Financial loss, identity theft | IC3 (FBI) for cybercrime |

## Prevention Measures

### Defensive Registration

- Register brand+ai, brand+app, brand+official, etc. See **domain-selection** for defensive registration.
- Redirect variants to main domain; do not deploy separate sites.

### Official Site Verification

Place "Official website: [domain]" prominently:
- **Homepage** (above fold or hero)
- **Sign-in / Sign-up pages**
- **Pricing / Payment pages**: "Only pay at [official-domain]. Do not enter payment on other domains."
- **Footer**: "© [Brand]. Official site: [domain]"
- **FAQ**: "How do I verify I'm on the official site?" → "The only official URL is [domain]. Any other domain is not affiliated."

Use **trust-badges** for verification signals. See **about-page** for identity declaration.

### Customer Support (Payment Fraud)

When users report "can't use after payment" but no record exists—likely paid on fake site:

1. **Verify source**: Ask which URL they used (request screenshot or URL).
2. **Response template**: Explain that the only official site is [official-domain]; if they paid elsewhere, that site is not affiliated. Recommend: (a) dispute charge with payment provider, (b) use only [official-domain] going forward.
3. **Roll out** template to support team; ensure consistent messaging.

### User Education

- Social media pinned post / announcement: "Only use [official-domain]"
- Email signatures, support replies: link to official domain only

## Traffic Recovery (When Impersonation Intercepts Search)

| Tactic | Purpose |
|--------|---------|
| **Brand search ads** | Run Google Ads and Microsoft Ads on brand terms; ensure official site appears first for brand queries |
| **SEO** | Strengthen official site for branded queries; Organization schema, clear H1, meta tags. See **schema-markup**, **title-tag** |
| **Social** | Pinned post: "Only use [official-domain]. Beware of impersonation." |

## Monitoring (Ongoing)

- Periodic search: brand name + common variants (e.g., brand+ai, brand+app)
- See **brand-monitoring** for monitoring setup, tool selection, and cadence

## Timeline (Typical)

| Phase | Focus |
|-------|-------|
| **Immediate (Days 1–3)** | Support template; site declaration; evidence collection |
| **Short-term (Week 1–2)** | Abuse reports; Google Safe Browsing; DMCA if applicable |
| **Traffic (Week 2+)** | Brand ads; SEO; social announcement |
| **Ongoing** | Monitoring; defensive registration if feasible |

## Implementation Checklist

**Short-term (1–2 weeks)**: Evidence collection; abuse reports to registrar and host; Google Safe Browsing report; DMCA if applicable; add "Official website" on site.

**Medium-term**: Add impersonation guidance to domain-selection; official verification to trust-badges, about-page.

**Long-term**: Periodic search (brand + variants); brand monitoring (BrandShield, Doppel); defensive registration of variants.

## Output Format

- **Evidence package** (checklist, evidence list)
- **Report templates** (registrar, hosting, Google)
- **Timeline** (immediate vs medium vs long-term actions)
- **Prevention** (defensive registration, site verification, user education)

## References

- [How to Report and Take Down a Fake Website - LegalClarity](https://legalclarity.org/how-to-report-and-take-down-a-fake-website/)
- [Website Spoofing: Detection and Take Down - BrandShield](https://www.brandshield.com/blog/website-spoofing-detection-take-down/)
- [ICANN DNS Abuse Complaints Guide](https://www.icann.org/en/system/files/files/submitting-dns-abuse-complaints-icann-guide-17nov25-en.pdf)
- [Google Safe Browsing - Report Phishing](https://safebrowsing.google.com/safebrowsing/report_phish/)
- [Cloudflare Abuse Reporting](https://www.cloudflare.com/trust-safety/reporting-abuse/) — use online form; select Phishing & Malware
- [Google Trademark Complaint](https://services.google.com/inquiry/aw_tmcomplaint)
- [Bing Content Removal](https://www.bing.com/webmaster/contentremovalform/showanonymouspage)

## Related Skills

- **domain-selection**: Defensive domain registration; brand variants
- **rebranding-strategy**: When rebranding, sync brand protection checks
- **brand-monitoring**: Proactive monitoring setup; tool selection; this skill = reactive takedown
- **branding**: Brand asset protection; consistency
- **trust-badges**: Official site verification signals
- **about-page**: Official identity and domain declaration
- **homepage-generator**: "Official website" placement
- **google-ads**, **paid-ads-strategy**: Brand search ads for traffic recovery
- **schema-markup**, **title-tag**: SEO for branded queries

---
name: brand-monitoring
description: When the user wants to monitor brand mentions, detect trademark infringement, or set up brand monitoring. Also use when the user mentions "brand monitoring," "brand watch," "trademark watch," "brand mentions," "impersonation detection," "counterfeit detection," or "brand abuse monitoring." For enforcement, use brand-protection.
metadata:
  version: 1.0.1
---

# Strategies: Brand Monitoring

Guides ongoing brand monitoring—detecting impersonation, trademark infringement, counterfeit products, and brand abuse before they cause harm. Complements **brand-protection** (reactive: report, takedown); this skill covers proactive monitoring setup and tool selection.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read for brand name, official domain, and key assets.

Identify:
1. **Scope**: Domain, social, marketplaces, paid search, dark web
2. **Budget**: Manual vs automated; DIY vs vendor
3. **Risk level**: High-value brand, prior incidents, or preventive

## What to Monitor

| Channel | Threats |
|---------|---------|
| **Domains** | Typosquatting, brand+ai, brand+app, impersonation sites |
| **Social media** | Fake accounts, impersonation, unauthorized use |
| **Marketplaces** | Counterfeit products, unauthorized sellers (Amazon, eBay, Temu) |
| **Paid search** | Competitors bidding on brand terms; impersonator ads |
| **App stores** | Fake apps, trademark misuse |
| **Web** | Phishing sites, spoofed pages |

## Manual Monitoring (Low Cost)

| Method | Frequency |
|--------|-----------|
| **Search** | Brand name + variants (brand+ai, brand+app, brand+official) |
| **Google Alerts** | Brand name, product names |
| **Social search** | X, LinkedIn, Instagram for brand mentions |
| **Marketplace search** | Amazon, eBay for counterfeit listings |

**Tip**: Document findings; escalate to **brand-protection** for takedown when infringement is confirmed.

## Automated Tools (Scale)

| Capability | Description |
|------------|-------------|
| **AI detection** | Machine learning, image recognition, NLP to detect abuse across channels |
| **Multi-channel** | Domains, social, marketplaces, paid search, dark web |
| **Enforcement** | Case management, takedown workflows, platform integrations |
| **Trademark watch** | USPTO, trademark office monitoring; litigation insights |

**Vendor types**: BrandShield, Tracer Protect, CompuMark, CounterFind—evaluate by coverage, enforcement rate, and budget.

## Monitoring Cadence

| Level | Cadence | Use |
|-------|---------|-----|
| **Basic** | Weekly search; Google Alerts | Low-risk; preventive |
| **Standard** | Daily alerts; monthly marketplace check | Moderate risk |
| **Enterprise** | Real-time monitoring; dedicated vendor | High-value brand; prior incidents |

## Output Format

- **Monitoring plan** (channels, cadence, tools)
- **Search queries** (brand + variants for manual check)
- **Alert setup** (Google Alerts, social)
- **Escalation path** (when to use brand-protection for takedown)

## Related Skills

- **brand-protection**: Report, takedown, evidence collection—use when infringement is found
- **domain-selection**: Defensive registration; brand variants
- **branding**: Brand asset consistency; what to protect

---
name: xml-sitemap
description: When the user wants to create, audit, or optimize sitemap.xml. Also use when the user mentions "sitemap," "sitemap.xml," "sitemap index," "lastmod," "changefreq," "priority," "URL discovery," "URL discovery for search engines," "single source of truth," "URL config," "unify sitemap IndexNow," or "reduce duplicate maintenance." For IndexNow, use indexnow.
metadata:
  version: 1.0.1
---

# SEO Technical: Sitemap

Guides sitemap creation, auditing, and optimization for search engine discovery.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Sitemap**: Create XML sitemap; submit to Google Search Console
- **URL discovery**: Help search engines find pages; especially important for large sites or poor internal linking

## Task

Generate an XML Sitemap that complies with the sitemaps.org protocol from the project's page list, and declare it in robots.txt.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL and page structure.

Identify:
1. **Site URL**: Base domain (e.g., `https://example.com`)
2. **URL count**: Total indexable pages (single sitemap vs. sitemap index)
3. **Data source**: Static config, CMS, file system, or hybrid

## 1. Protocol Essentials

| Item | Spec |
|------|------|
| Single sitemap limit | 50,000 URLs, 50MB (uncompressed) |
| Sitemap index | When exceeding limit, split and have main index reference sub-sitemaps |
| Encoding | UTF-8 |
| URL format | Full URL, same host, include `https://` |
| Required tags | `<loc>` |
| Optional tags | `<lastmod>`, `<changefreq>`, `<priority>` |

## 2. Field Requirements

| Field | Description | Recommendation |
|-------|--------------|---------------|
| url | Full URL | `https://example.com/path` |
| lastModified | Page last modified time | Use page metadata, ISO 8601; use `YYYY-MM-DD` or omit when no data |
| changeFrequency | Update frequency | Home `daily`, list pages `weekly`, content pages `monthly` |
| priority | Relative importance | Home 1.0, aggregate pages 0.9, content pages 0.7–0.8, others 0.5–0.6 |

### lastmod (Critical)

- **Must be accurate**: Reflect actual page modification time, not sitemap generation time. Google requires verifiability; Bing reports ~18% of sitemaps ignored due to lastmod errors.
- **Format**: W3C Datetime (`YYYY-MM-DD` or `YYYY-MM-DDTHH:MM:SS+TZD`), e.g. `2025-01-15`, `2025-01-15T14:30:00+08:00`.
- **Avoid**: Using `new Date()` for lastmod—causes all URLs to share the same timestamp; search engines may ignore.
- **Apply when**: Content updates, structured data changes, or important link changes.

### changefreq / priority

- **changefreq**: Hints only; does not directly determine crawl frequency. Values: `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, `never`.
- **priority**: 0.0–1.0; **does not affect ranking**; set higher for important pages; avoid identical values for all.

## 3. Architecture & Split

### Single Sitemap

- When URLs >50,000, generate `/sitemap.xml` directly.

### Sitemap Index (Multiple Sub-sitemaps)

- When exceeding limit, split by type or language; main index references sub-sitemaps.
- Example splits: `/sitemap/posts.xml`, `/sitemap/pages.xml`, `/sitemap/zh.xml`, `/sitemap/en.xml`.
- Main index outputs `/sitemap.xml` or `/sitemap-index.xml`, each entry as `<sitemap><loc>...</loc></sitemap>`.

### Multilingual Sites

- Split by locale: `/sitemap/zh.xml`, `/sitemap/en.xml`.
- Or by content type + language: `/sitemap/zh-posts.xml`, `/sitemap/en-posts.xml`.

### Multi-Language Sitemap (hreflang in Sitemap)

For multilingual sites, add `xhtml:link` hreflang alternates inside each `<url>` entry. **Recommended for large sites** (100+ multilingual pages); centralizes hreflang management.

**Rules**:
- Every language version must link to ALL others, including itself (self-reference).
- Include `x-default` pointing to default locale.
- Use `xmlns:xhtml="http://www.w3.org/1999/xhtml"` namespace.
- `<loc>` typically uses default-locale (clean) URL; `x-default` points there too.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:xhtml="http://www.w3.org/1999/xhtml">
  <url>
    <loc>https://example.com/page</loc>
    <xhtml:link rel="alternate" hreflang="en" href="https://example.com/page" />
    <xhtml:link rel="alternate" hreflang="zh" href="https://example.com/zh/page" />
    <xhtml:link rel="alternate" hreflang="x-default" href="https://example.com/page" />
  </url>
</urlset>
```

List all language sitemaps in sitemap index; include in robots.txt.

## 4. Implementation

| Tech Stack | Implementation |
|------------|-----------------|
| Next.js App Router | `app/sitemap.ts` export `MetadataRoute.Sitemap` or `generateSitemaps` |
| Next.js Pages Router | `pages/sitemap.xml.ts` or `getServerSideProps` return XML |
| Astro | `src/pages/sitemap-index.xml.ts` or `@astrojs/sitemap` |
| Vite / Static build | Build script generates `public/sitemap.xml` |
| Other | Generate static `/sitemap.xml` or return dynamically via API |

### Route Exclusion

- If the project has i18n / middleware redirects, exclude sitemap paths to avoid redirect.
- Example (Next.js matcher): `'/((?!api|_next|sitemap|sitemap-index|.*\\..*).*)'`.

## 5. Page Scope

### Include

- Home: `/`
- Locale/region home pages (e.g. `/zh`, `/en`)
- All indexable content pages, list pages, category pages

### Exclude

- `/api/*`, `/admin/*`, `/_next/*`
- Static assets (images, JS, CSS, etc.). For image discovery, use **image sitemap** extension—see **image-optimization**. For video discovery, use **video sitemap** extension—see **video-optimization**
- Login, admin, drafts, and other pages not intended for indexing

## 6. Data Source & Maintenance (Single Source of Truth)

- **Single source of truth**: Read URL list from config, CMS, or metadata; avoid hardcoding in sitemap.
- **Multiple page types**: Tools, blog, marketing pages can be merged into one array for unified generation.
- **New pages**: Add only to data source; sitemap updates automatically; avoid maintaining multiple places.

### Central Config (Recommended)

Create a config (e.g., `site-pages-config.ts`) that exports:
- Page slugs/paths by section (tools, blog, marketing, etc.)
- Optional: `modifiedDate` per page for accurate lastmod
- Function: `getAllPageUrls(baseUrl)` for sitemap and IndexNow

**Why**: Sitemap, IndexNow, and feed can all import from the same config—no duplicate URL maintenance. IndexNow should use the same URL list; avoid separate hardcoded lists.

## 7. robots.txt

Add to robots.txt:

```
Sitemap: https://example.com/sitemap.xml
```

With multiple sitemaps, only declare the main index.

## 8. Output Format

### Single Sitemap Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://example.com/</loc>
    <lastmod>2025-01-15</lastmod>
    <changefreq>daily</changefreq>
    <priority>1.0</priority>
  </url>
  <url>
    <loc>https://example.com/page</loc>
    <lastmod>2025-01-10</lastmod>
    <changefreq>weekly</changefreq>
    <priority>0.8</priority>
  </url>
</urlset>
```

### Sitemap Index Example

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <sitemap>
    <loc>https://example.com/sitemap/pages.xml</loc>
    <lastmod>2025-01-15</lastmod>
  </sitemap>
  <sitemap>
    <loc>https://example.com/sitemap/posts.xml</loc>
    <lastmod>2025-01-14</lastmod>
  </sitemap>
</sitemapindex>
```

## 9. Common Issues

| Issue | Cause / Fix |
|-------|-------------|
| Sitemap 404 | Build failure, wrong path, incorrect export; check routes and deployment |
| Missing pages | URLs not in data source, filtered or excluded |
| lastmod anomaly | Avoid `new Date()`; use `modifiedDate` from page metadata |
| Google not indexing | Submit sitemap in GSC; check Coverage (google-search-console) and robots |
| EN/ZH URL mismatch | Use unified data source; share same list when generating by locale |

## References

- [sitemaps.org](https://www.sitemaps.org/protocol.html)
- [Google Sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/build-sitemap)

## Related Skills

- **website-structure**: Plan page structure and URL list; sitemap reflects planned/indexable pages
- **google-search-console**: Sitemap status, indexed URL count, Coverage
- **robots-txt**: Reference sitemap in robots.txt
- **indexnow**: Share same URL list from config
- **image-optimization**: Image sitemap extension for image discovery
- **video-optimization**: Video sitemap extension for video discovery

---
name: robots-txt
description: When the user wants to configure, audit, or optimize robots.txt. Also use when the user mentions "robots.txt," "crawler rules," "block crawlers," "AI crawlers," "GPTBot," "allow/disallow," "disallow path," "crawl directives," "user-agent," "block Googlebot," "fix robots.txt," "robots.txt blocking," or "search engine crawling." For indexing, use indexing.
metadata:
  version: 1.1.1
---

# SEO Technical: robots.txt

Guides configuration and auditing of robots.txt for search engine and AI crawler control.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Robots.txt**: Configure Disallow/Allow, Sitemap, Clean-param; audit for accidental blocks
- **Crawler access**: Path-level crawl control; AI crawler allow/block strategy
- **Differentiation**: robots.txt = crawl control (who accesses what paths); noindex = index control (what gets indexed). See **indexing** for page-level exclusions.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL and indexing goals.

Identify:
1. **Site URL**: Base domain (e.g., `https://example.com`)
2. **Indexing scope**: Full site, partial, or specific paths to exclude
3. **AI crawler strategy**: Allow search/indexing vs. block training data crawlers

## Best Practices

### Purpose and Limitations

| Point | Note |
|-------|------|
| **Purpose** | Controls crawler access; does NOT prevent indexing (disallowed URLs may still appear in search without snippet) |
| **Advisory** | Rules are advisory; malicious crawlers may ignore |
| **Public** | robots.txt is publicly readable; use noindex or auth for sensitive content. See **indexing** |

### Crawl vs Index vs Link Equity (Quick Reference)

| Tool | Controls | Prevents indexing? |
|------|----------|-------------------|
| **robots.txt** | Crawl (path-level) | No—blocked URLs may still appear in SERP |
| **noindex** (meta / X-Robots-Tag) | Index (page-level) | Yes. See **indexing** |
| **nofollow** | Link equity only | No—does not control indexing |

### When to Use robots.txt vs noindex

| Use | Tool | Example |
|-----|------|---------|
| **Path-level** (whole directory) | robots.txt | `Disallow: /admin/`, `Disallow: /api/`, `Disallow: /staging/` |
| **Page-level** (specific pages) | noindex meta / X-Robots-Tag | Login, signup, thank-you, 404, legal. See **indexing** for full list |
| **Critical** | Do NOT block in robots.txt | Pages that use noindex—crawlers must access the page to read the directive |

**Paths to block in robots.txt**: /admin/, /api/, /staging/, temp files. **Paths to use noindex** (allow crawl): /login/, /signup/, /thank-you/, etc.—see **indexing**.

### Location and Format

| Item | Requirement |
|------|-------------|
| **Path** | Site root: `https://example.com/robots.txt` |
| **Encoding** | UTF-8 plain text |
| **Standard** | RFC 9309 (Robots Exclusion Protocol) |

### Core Directives

| Directive | Purpose | Example |
|-----------|---------|---------|
| `User-agent:` | Target crawler | `User-agent: Googlebot`, `User-agent: *` |
| `Disallow:` | Block path prefix | `Disallow: /admin/` |
| `Allow:` | Allow path (can override Disallow) | `Allow: /public/` |
| `Sitemap:` | Declare sitemap absolute URL | `Sitemap: https://example.com/sitemap.xml` |
| `Clean-param:` | Strip query params (Yandex) | See below |

### Critical: Do Not Block

| Do not block | Reason |
|--------------|--------|
| CSS, JS, images | Google needs them to render pages; blocking breaks indexing |
| `/_next/` (Next.js) | Breaks CSS/JS loading; static assets in GSC "Crawled - not indexed" is expected. See **indexing** |
| Pages that use noindex | Crawlers must access the page to read the noindex directive; blocking in robots.txt prevents that |

**Only block**: paths that don't need crawling: /admin/, /api/, /staging/, temp files.

### AI Crawler Strategy

robots.txt is effective for all measured AI crawlers ([Vercel/MERJ study](https://vercel.com/blog/the-rise-of-the-ai-crawler), 2024). Set rules per user-agent; check each vendor's docs for current tokens.

| User-agent | Purpose | Typical |
|------------|---------|---------|
| **OAI-SearchBot** | ChatGPT search | Allow |
| **GPTBot** | OpenAI training | Disallow |
| **Claude-SearchBot** | Claude search | Allow |
| **ClaudeBot** | Anthropic training | Disallow |
| **PerplexityBot** | Perplexity search | Allow |
| **Google-Extended** | Gemini training | Disallow |
| **CCBot** | Common Crawl (LLM training) | Disallow |
| **Bytespider** | ByteDance | Disallow |
| **Meta-ExternalAgent** | Meta | Disallow |
| **AppleBot** | Apple (Siri, Spotlight); renders JS | Allow for indexing |

**Allow vs Disallow**: Allow search/indexing bots (OAI-SearchBot, Claude-SearchBot, PerplexityBot); Disallow training-only bots (GPTBot, ClaudeBot, CCBot) if you don't want content used for model training. See **site-crawlability** for AI crawler optimization (SSR, URL management).

### Clean-param (Yandex)

```
Clean-param: utm_source&utm_medium&utm_campaign&utm_term&utm_content&ref&fbclid&gclid
```

## Output Format

- **Current state** (if auditing)
- **Recommended robots.txt** (full file)
- **Compliance checklist**
- **References**: [Google robots.txt](https://developers.google.com/search/docs/crawling-indexing/robots/create-robots-txt)

## Related Skills

- **indexing**: Full noindex page-type list; when to use noindex vs robots.txt; GSC indexing diagnosis
- **page-metadata**: Meta robots (noindex, nofollow) implementation
- **xml-sitemap**: Sitemap URL to reference in robots.txt
- **site-crawlability**: Broader crawl and structure guidance; AI crawler optimization
- **rendering-strategies**: SSR, SSG, CSR; content in initial HTML for crawlers

---
name: rendering-strategies
description: When the user wants to choose or optimize rendering strategy for SEO. Also use when the user mentions "SSR," "SSG," "CSR," "ISR," "static rendering," "dynamic rendering," "server-side rendering," "client-side rendering," "JavaScript rendering," "pre-rendering," "prerender," "content in initial HTML," or "crawler visibility." For crawl issues, use site-crawlability.
metadata:
  version: 1.0.2
---

# SEO Technical: Rendering Strategies

Guides rendering strategy selection and optimization for search engine and AI crawler visibility. **Golden rule**: Page data and metadata must be available on page load without JavaScript execution for optimal SEO.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Static vs dynamic**: SSG, SSR, ISR, CSR; when to use each
- **Crawler behavior**: Googlebot renders JS (with delays); AI crawlers do not
- **Component-level**: Content in initial HTML; tabs, carousels, nav
- **Dynamic rendering**: Prerender for bots when full SSR/SSG is not feasible

## Rendering Methods

| Method | When HTML generated | SEO | Best for |
|--------|---------------------|-----|----------|
| **SSG** (Static Site Generation) | Build time | ✅ Best | Blog, docs, marketing pages; content rarely changes |
| **SSR** (Server-Side Rendering) | Request time | ✅ Good | News, product pages; dynamic, personalized content |
| **ISR** (Incremental Static Regeneration) | Build + revalidate | ✅ Good | Large sites; static with periodic updates |
| **CSR** (Client-Side Rendering) | Browser (after JS) | ❌ Poor | Dashboards, account pages; no SEO needed |
| **Dynamic rendering** | On-demand for bots | ✅ Fallback | SPAs; prerender for crawlers, SPA for users |

### SSG (Static Site Generation)

HTML generated at build time; same HTML for every request. **Best for SEO**: crawlers receive full HTML immediately; optimal performance.

- **Use when**: Blog, docs, marketing pages, content that doesn't change frequently
- **Framework**: Next.js `getStaticProps`, Astro, Gatsby

### SSR (Server-Side Rendering)

HTML generated on each request. **Good for SEO**: crawlers receive complete HTML; supports dynamic, personalized content.

- **Use when**: News, product pages, user-specific content
- **Tradeoff**: Higher server load; slower TTFB than SSG
- **Framework**: Next.js `getServerSideProps`, Remix

### ISR (Incremental Static Regeneration)

Static at build; pages can revalidate after a period. **Good for SEO**: combines static performance with freshness.

- **Use when**: Large sites (millions of pages); content updates periodically
- **Framework**: Next.js `revalidate` in `getStaticProps`

### CSR (Client-Side Rendering)

Server sends minimal HTML shell; content renders in browser after JS loads. **Not for SEO**: crawlers may see empty content; indexing delays or failures.

- **Use when**: Dashboards, account pages, internal tools—no search visibility needed
- **Avoid for**: Public content, marketing pages, blog

### Dynamic Rendering

Serve prerendered HTML to crawlers; serve SPA to users. **Fallback** when full SSR/SSG is not feasible (e.g. legacy SPA migration).

- **How**: Detect crawler user-agent; route to prerender service (e.g. Prerender.io) or headless render
- **When**: JavaScript-heavy sites; migration period; product/docs with CSR
- **Note**: Google permits this; prerendered content should match user experience

## Crawler Behavior

| Crawler | JavaScript | Content in initial HTML |
|---------|------------|-------------------------|
| **Googlebot** | Renders JS (Chrome); may have multi-day queue | Full weight; SSR/SSG preferred |
| **AI crawlers** (GPTBot, ClaudeBot, PerplexityBot) | Do **not** execute JS | **Required**—CSR content invisible |
| **Bingbot** | Renders JS | Same as Googlebot |

**AI crawlers**: ~28% of Googlebot's crawl volume. Critical content (articles, meta, nav) must be in initial HTML. See **site-crawlability** for AI crawler optimization; **generative-engine-optimization** for GEO.

## Component-Level: Content in Initial HTML

Google does **not** simulate user clicks (tabs, carousels, "Load more"). Content loaded via AJAX or on interaction is not discoverable.

| Component | Requirement | Implementation |
|------------|-------------|----------------|
| **Tabs / Accordion** | All tab content in DOM at load | Server-render; use `<details>`/`<summary>` or CSS show/hide |
| **Carousel** | All slides in initial HTML | Server-render; CSS/JS for show/hide only |
| **Hero** | Headline, CTA, LCP image in HTML | No JS-only rendering |
| **Navigation** | All nav links in first paint | No JS-injected menus for critical links |

**Recommendation**: Server-render (SSR/SSG) all critical content; use JS only for interaction (show/hide, animation). Content loaded on click = not indexed.

## Decision Guide

| Content type | Rendering | Reason |
|--------------|-----------|--------|
| Blog, docs, marketing | SSG or ISR | Best SEO; fast; static |
| Product, news, dynamic | SSR | Fresh content; crawler-ready |
| Dashboard, account | CSR | No SEO; auth required |
| Legacy SPA | Dynamic rendering | Bridge until SSR/SSG migration |

## Output Format

- **Current setup**: SSG, SSR, CSR, or hybrid
- **Recommendation**: By page type
- **Component checks**: Tabs, carousel, nav—content in initial HTML?
- **References**: [Next.js Rendering](https://nextjs.org/learn/seo/rendering-strategies), [Vercel SSR vs SSG](https://vercel.com/blog/nextjs-server-side-rendering-vs-static-generation)

## Related Skills

- **site-crawlability**: AI crawler optimization; SSR for critical content; URL management
- **generative-engine-optimization**: GEO; AI crawlers don't execute JS
- **core-web-vitals**: LCP; SSR/SSG for above-fold; client-side hurts LCP
- **mobile-friendly**: Mobile-first indexing; content parity
- **tab-accordion**: Content in DOM at load; server-render tabs
- **carousel**: Content in initial HTML; server-render slides
- **hero-generator**: Hero in initial HTML; avoid JS-only
- **navigation-menu-generator**: Nav in first paint; no JS-only menus

---
name: mobile-friendly
description: When the user wants to optimize for mobile-first indexing or fix mobile usability. Also use when the user mentions "mobile-friendly," "mobile-first indexing," "mobile SEO," "responsive design," "mobile adaptation," "mobile viewport," "viewport meta," "touch targets," "font size mobile," "AMP," or "Accelerated Mobile Pages." For viewport meta, use page-metadata.
metadata:
  version: 1.1.2
---

# SEO Technical: Mobile-Friendly

Guides mobile-first indexing optimization and mobile usability. Google uses the mobile version of pages for indexing and ranking; mobile-friendliness is a ranking factor.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Mobile-first indexing**: Google primarily crawls and indexes mobile version
- **Mobile adaptation**: Responsive design, viewport, breakpoints
- **Content parity**: Mobile and desktop content should match (or mobile preferred)
- **Mobile usability**: Viewport, font size, touch targets, no intrusive interstitials
- **AMP**: Accelerated Mobile Pages—status and when to consider

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL.

Identify:
1. **Site type**: Responsive, separate AMP, dynamic serving
2. **Content parity**: Does mobile show same content as desktop?
3. **Tools**: GSC Mobile Usability report; [Mobile-Friendly Test](https://search.google.com/test/mobile-friendly)

## Mobile-First Indexing Requirements

| Requirement | Action |
|-------------|--------|
| **Content parity** | Mobile version must include same primary content as desktop; avoid hiding key content on mobile |
| **Structured data** | Same schema on mobile and desktop; ensure mobile URLs in schema |
| **Metadata** | Same title, meta description on mobile |
| **Media** | Images should be crawlable; avoid lazy-loading above-fold images |

## Responsive Design & Mobile Adaptation

**Responsive design** = Single HTML; CSS media queries adapt layout to screen size. **Preferred** for SEO: one URL, no duplicate content.

| Principle | Practice |
|-----------|----------|
| **Mobile-first** | Design for mobile first; enhance for desktop |
| **Fluid layout** | Use `%`, `vw`, `flex`, `grid`; avoid fixed pixel widths |
| **Breakpoints** | Common: 320px, 768px, 1024px, 1280px; match device widths |
| **Images** | Responsive images (`srcset`, `sizes`); see **image-optimization** |

## Viewport

The viewport meta tag tells browsers how to scale and size the page on mobile. **Required** for mobile-friendly pages.

```html
<meta name="viewport" content="width=device-width, initial-scale=1">
```

| Attribute | Purpose |
|-----------|---------|
| `width=device-width` | Match viewport to device screen width |
| `initial-scale=1` | 1:1 scale on load; prevents zoom |
| `maximum-scale` | Avoid disabling zoom (accessibility) |
| `user-scalable=no` | **Avoid**—hurts accessibility |

**Without viewport**: Desktop layout shrunk; horizontal scroll; fails Mobile-Friendly Test. See **page-metadata**.

## Mobile Usability Checklist

| Element | Guideline |
|---------|-----------|
| **Viewport** | See above; required for mobile-friendly |
| **Font size** | 16px minimum for body text; avoid zooming to read |
| **Touch targets** | Buttons/links ≥48×48px; adequate spacing between taps |
| **Content width** | No horizontal scrolling; content fits viewport |
| **Intrusive interstitials** | Avoid popups that block main content on mobile |

## Common Issues

| Issue | Fix |
|-------|-----|
| **Content hidden on mobile** | Show critical content; avoid accordion/tabs for primary content |
| **Flash / unsupported** | Replace with HTML5 alternatives |
| **Text too small** | Use base font ≥16px; avoid `font-size` in px <12 |
| **Links too close** | Increase tap target size; add padding |

## Responsive vs. Separate URLs

| Approach | When | Note |
|----------|------|-----|
| **Responsive** | Preferred | Single URL; same HTML, CSS media queries |
| **Dynamic serving** | Same URL, different HTML by user-agent | Ensure mobile content parity |
| **Separate URLs** | m.example.com | Use canonical + hreflang; see **canonical-tag**, **page-metadata** |

## Accelerated Mobile Pages (AMP)

AMP is a web component framework for fast-loading pages. **Status (2024–2025)**: Still supported; no longer required for Top Stories or ranking.

| Aspect | Note |
|--------|------|
| **Ranking** | No ranking advantage over well-optimized responsive pages |
| **Top Stories** | AMP no longer required since 2021; Core Web Vitals suffice |
| **When to consider** | News sites, ad-heavy pages, very slow hosting—but responsive + CWV usually better |
| **Alternative** | Responsive design + **core-web-vitals** optimization; SSR/SSG; see **rendering-strategies** |

**Recommendation**: For most sites, prioritize responsive design and Core Web Vitals over AMP. AMP adds maintenance (separate AMP HTML); modern optimization offers similar performance with more flexibility.

## Output Format

- **Mobile Usability status**: Pass/fail from GSC or Mobile-Friendly Test
- **Responsive / viewport**: Check viewport meta; breakpoints; fluid layout
- **Content parity**: Mobile vs desktop content check
- **AMP**: Only if legacy or specific use case
- **Fixes**: Prioritized by impact

## Related Skills

- **page-metadata**: Viewport meta tag; required for mobile
- **core-web-vitals**: CWV measured on mobile; replaces AMP for Top Stories; LCP, INP, CLS
- **canonical-tag**: Separate mobile URLs; hreflang for mobile
- **image-optimization**: Responsive images; mobile LCP
- **rendering-strategies**: SSR/SSG for fast mobile load
- **google-search-console**: Mobile Usability report

---
name: indexnow
description: When the user wants to implement IndexNow, notify search engines of new/updated URLs, or speed up Bing indexing. Also use when the user mentions "IndexNow," "Bing indexing," "URL notification," "instant indexing," "sitemap IndexNow sync," "share URL list with sitemap," or "IndexNow API." For sitemap SSOT, use xml-sitemap.
metadata:
  version: 1.0.1
---

# SEO Technical: IndexNow

Guides IndexNow protocol integration for faster search engine indexing (primarily Bing).

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **IndexNow**: Submit URLs to Bing/Yandex for faster indexing
- **URL notification**: Notify search engines of new or updated URLs

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL.

Identify:
1. **Site URL**: Base domain
2. **URL source**: Config file, sitemap, CMS, etc.
3. **Deployment**: CI/CD, manual, or both

## Overview

IndexNow notifies search engines (mainly Bing) of new or updated URLs to speed up indexing.

## Implementation Steps

### 1. API Key and Verification

- Generate API key (e.g., UUID)
- Create verification file: `https://example.com/{key}.txt`
- File content: the API key string
- Configure key and URL in your IndexNow client

### 2. Submission Methods

| Method | When to use |
|--------|-------------|
| **Single URL** | New or updated page |
| **Batch** | Many URLs at once (e.g., after deploy) |
| **Relative paths** | Convert to full URLs before submitting |

### 3. Best Practices

| Practice | Note |
|----------|------|
| **When to submit** | New pages, major content updates, meta changes |
| **When not to** | Minor edits; let natural crawling handle |
| **Frequency** | Once per deploy; avoid excessive submissions |
| **Priority** | Submit high-value commercial pages first |

### 4. CI/CD Integration

```bash
npm run build
npm run indexnow:all
```

### 5. Single Source of Truth (URL List)

- **Use same config as sitemap**: Import URL list from central config (e.g., `site-pages-config.ts`) or sitemap generation logic.
- **Avoid**: Separate hardcoded URL lists for IndexNow—leads to inconsistency and missed URLs.
- **Feed**: If you have RSS/feed, it can also consume from the same config to stay in sync.

## Supported Search Engines

- **Bing**: Primary support
- **Yandex**: Supports IndexNow
- **Google**: Does not use IndexNow; use Sitemap + Search Console

## Verification

- Check [Bing Webmaster Tools](https://www.bing.com/webmasters/indexnow) for indexing status
- Monitor submission logs for errors

## Common Issues

| Issue | Fix |
|-------|-----|
| Domain verification fails | Ensure URL uses correct domain |
| API key error | Verify key and verification file match |
| Network errors | Retry; API can be intermittent |

## Output Format

- **Setup steps**: Key generation, verification file
- **Submission flow**: Single vs. batch
- **Integration**: CI/CD or manual script
- **References**: [IndexNow docs](https://www.bing.com/indexnow/getstarted)

## Related Skills

- **xml-sitemap**: Share same URL list from central config
- **indexing**: Broader indexing strategy

---
name: indexing
description: When the user wants to fix indexing issues from Search Console, use noindex, or implement Google Indexing API. Also use when the user mentions "fix indexing," "not indexed," "Crawled - currently not indexed," "discovered - currently not indexed," "index coverage," "noindex," "noindex tag," "pages not indexed," "why not indexed," "request indexing," or "Google Indexing API." For sitemap, use xml-sitemap.
metadata:
  version: 1.0.1
---

# SEO Technical: Indexing

Guides indexing troubleshooting and fix actions. For how to find and diagnose issues in GSC, see **google-search-console**.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Fix actions**: noindex, canonical, content quality, URL Inspection; verify robots.txt does not block (see **robots-txt**)
- **Noindex**: Page-level index control; which pages to exclude and how. Complements **robots-txt** (path-level crawl control) and **google-search-console** (Coverage diagnosis)

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL and indexing goals.

Identify issue from GSC (see **google-search-console** for Coverage report, issue types, diagnosis workflow). Then apply fix below.

## Crawled - Currently Not Indexed

| Cause | Action |
|-------|--------|
| Low quality, duplicate, off-topic | Improve content, fix duplicates, set correct canonical |
| Static assets (CSS/JS) | See below |
| Feed, share URLs with params | Usually OK to ignore; or noindex, canonical to main URL |
| Important content pages | Use URL Inspection, verify canonical/internal links/sitemap, Request indexing |

### Static Assets (Next.js / Vercel)

Vercel adds unique `dpl=` params to static assets per deploy, creating many "Crawled - currently not indexed" URLs.

| Do | Don't |
|----|-------|
| Keep robots.txt allowing `/_next/` | Do not block `/_next/` (breaks CSS/JS loading). See **robots-txt** |
| Accept static assets in GSC as expected | Do not block `/_next/static/css/` or `?dpl=` |
| Use X-Robots-Tag for static assets | CSS/JS should not be indexed; no SEO impact |

Static assets in "Crawled - currently not indexed" is **normal and expected**.

## Other Issue Types (from GSC Coverage)

| Issue | Fix |
|-------|-----|
| Excluded by «noindex» tag | Remove noindex if accidental; keep if intentional |
| Blocked by robots.txt | See **robots-txt**; remove Disallow for important paths |
| Redirect / 404 | Fix URL or add redirect |
| Duplicate / Canonical | Set correct canonical; usually OK |
| **Soft-404** | Page returns 200 but content says "not found" or empty—Google may treat as 404. Fix: return 404 status for truly missing pages; or add real content for 200 pages |

### Soft-404

A soft-404 occurs when a page returns HTTP 200 but the content indicates the page doesn't exist (e.g. "Page not found" message, empty state). Google may treat it as 404 and exclude from index.

| Fix | When |
|-----|------|
| **Return 404** | Page truly doesn't exist; use proper 404 status |
| **Add content** | Page is intentional (e.g. empty search results); ensure substantive content or use noindex |
| **Redirect** | If URL moved, use 301 to correct destination |

## Noindex Usage

- **How**: `metadata.robots = { index: false }` or `<meta name="robots" content="noindex">` or X-Robots-Tag
- **Rationale**: Not all site content should be indexed; noindex is a valid choice for many pages
- **Caution**: Avoid noindex on important content pages
- **With robots.txt**: robots.txt = path-level crawl control; noindex = page-level index control. Do **not** block noindex pages in robots.txt—crawlers must access the page to read the directive. Use both: robots for /admin/, /api/; noindex for /login/, /thank-you/, etc. See **robots-txt** for when to use which.
- **nofollow ≠ noindex**: nofollow controls link equity only; it does **not** prevent indexing. To exclude from search, use noindex. See **page-metadata** for meta robots implementation.

### Page Types That Typically Need Noindex

| Category | Page Types | Typical Meta | Reason |
|----------|------------|--------------|--------|
| **Auth & Account** | Login, Signup, Password reset, Account dashboard | Login: `noindex,nofollow`; Signup: `noindex,follow` | No search value; login indexed = security risk; signup follow allows crawl of Privacy/Terms links |
| **Admin & Private** | Admin, Staging, Test pages, Internal tools | `noindex,nofollow` | Not for public; avoid discovery |
| **Conversion Endpoints** | Thank-you, Confirmation, Checkout success, Download gate | `noindex,follow` | Post-conversion; no SERP value; allow link equity |
| **System & Utility** | 404, Internal search results, Faceted/filter URLs | `noindex,follow` or `noindex,nofollow` | Thin/duplicate; 404 = error state |
| **Legal** | Privacy, Terms, Cookie Policy (optional) | Often `noindex,follow` | Low-value indexed; reduces clutter |
| **Duplicate & Thin** | Printer-friendly, Parameter URLs, Near-duplicate | `noindex,follow` or canonical | Duplicate content; canonical preferred when possible |
| **Low-Value** | Media kit, Feedback board (external), Thin press | `noindex` or index for brand queries | Case-by-case |

**noindex,follow vs noindex,nofollow**: Use `noindex,follow` for most cases—excludes from SERP but allows link equity. Use `noindex,nofollow` only for login (security), staging, or temporary test pages.

## Google Indexing API

| Type | Typical use |
|------|-------------|
| JobPosting | Job boards |
| BroadcastEvent | Live platforms |

**Requirements**: Enable Indexing API, create service account, add owner in Search Console, request quota (default 200 URLs/day).

## Output Format

- **Action items**: Prioritized fixes
- **References**: [Page indexing report](https://support.google.com/webmasters/answer/7440203)

## Related Skills

- **google-search-console**: Find and diagnose indexing issues in GSC
- **robots-txt**: Path-level crawl control; when to use robots.txt vs noindex; do not block /_next/ or noindex pages
- **page-metadata**: Meta robots implementation; noindex vs nofollow
- **xml-sitemap**: Submit and maintain sitemap
- **indexnow**: Faster indexing for Bing
- **canonical-tag**: Resolve duplicate content

---
name: site-crawlability
description: When the user wants to improve crawlability, fix orphan pages, or optimize site structure for search engines. Also use when the user mentions "crawlability," "crawl budget," "orphan pages," "internal links," "site structure," "site crawlability," "infinite scroll," "pagination," "masonry SEO," "AI crawler optimization," "GPTBot crawlability," "ClaudeBot crawlability," or "content not indexed." For internal links, use internal-links.
metadata:
  version: 1.2.1
---

# SEO Technical: Crawlability

Guides crawlability improvements: robots, X-Robots-Tag, site structure, and internal linking.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Redirect chains & loops**: Fix multi-hop redirects; point directly to final URL
- **Broken links (4xx)**: Fix broken internal/external links; 301 or remove
- **Site architecture**: Logical hierarchy; pages within 3–4 clicks from homepage
- **Orphan pages**: Add internal links to pages with no incoming links
- **Pagination**: Prefer pagination over infinite scroll for crawlability
- **Crawl budget**: Reduce waste on duplicates, redirects, low-value URLs (see below)
- **AI crawler optimization**: SSR for critical content; URL management; reduce 404/redirect waste (see below)

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site structure.

Identify:
1. **Site structure**: Flat vs. deep hierarchy
2. **Framework**: Next.js, static, SPA, etc.
3. **Key paths**: Sitemap, robots.txt, API, static assets

## Best Practices

### Redirect Chains & Loops

- Fix multi-hop redirects; point directly to final URL
- Loops: URLs redirecting back to themselves; break the cycle

### Broken Links (4xx)

- Fix broken internal/external links; 301 or remove
- Audit regularly; update or remove broken links

### Site Architecture

| Principle | Guideline |
|-----------|-----------|
| **Depth** | Important pages within 3–4 clicks from homepage |
| **Orphan pages** | Add internal links to pages with no incoming links; see **internal-links** for link strategy |
| **Hierarchy** | Logical structure; hub pages link to content |

### Pagination vs Infinite Scroll

**Problem**: With infinite scroll, crawlers cannot emulate user behavior (scroll, click "Load more"); content loaded after initial page load is not discoverable. Same applies to masonry + infinite scroll, lazy-loaded lists, and similar patterns.

**Solution**: Prefer pagination for key content. If keeping infinite scroll, make it search-friendly per [Google's recommendations](https://developers.google.com/search/blog/2014/02/infinite-scroll-search-friendly):

| Requirement | Practice |
|-------------|----------|
| **Component pages** | Chunk content into paginated pages accessible without JavaScript |
| **Full URLs** | Each page has unique URL (e.g. `?page=1`, `?lastid=567`); avoid `#1` |
| **No overlap** | Each item listed once in series; no duplication across pages |
| **Direct access** | URL works in new tab; no cookie/history dependency |
| **pushState/replaceState** | Update URL as user scrolls; enables back/forward, shareable links |
| **404 for out-of-bounds** | `?page=999` returns 404 when only 998 pages exist |

**Reference**: [Infinite scroll search-friendly recommendations](https://developers.google.com/search/blog/2014/02/infinite-scroll-search-friendly) (Google Search Central, 2014)

### Pagination (Traditional)

- Reference links to next/previous pages; `rel="prev"` / `rel="next"` where applicable
- Avoid dynamic-only loading; ensure links in HTML

### Crawl Budget

Crawl budget is the number of URLs Googlebot will crawl on your site in a given period. Large sites (10,000+ pages) may waste up to 30% of crawl budget on duplicates, redirects, and low-value URLs.

| Waste source | Fix |
|--------------|-----|
| **Duplicate URLs** | Canonical; consolidate; 301 to preferred |
| **Redirect chains** | Point directly to final URL |
| **Parameter proliferation** | Use `rel="canonical"`; consider `Clean-param` (Yandex) |
| **Low-value pages** | noindex for thin/duplicate; see **indexing** |
| **Crawl traps** | Avoid infinite URL generation (e.g. faceted filters) |

**Sitemap**: Include only indexable, canonical URLs. See **xml-sitemap**, **canonical-tag**.

### AI Crawler Optimization

AI crawlers (GPTBot, ClaudeBot, PerplexityBot, etc.) now represent ~28% of Googlebot's crawl volume. Their behavior differs from search engines—optimizing for both improves GEO (AI search visibility). See **generative-engine-optimization** for GEO strategy. [Vercel/MERJ study](https://vercel.com/blog/the-rise-of-the-ai-crawler) (Dec 2024):

| Factor | AI Crawlers (GPTBot, Claude) | Googlebot |
|--------|------------------------------|-----------|
| **JavaScript** | Do not execute JS; cannot read client-side rendered content | Full JS rendering |
| **404 rate** | ~34% of fetches hit 404s | ~8% |
| **Redirects** | ~14% of fetches follow redirects | ~1.5% |
| **Content in initial HTML** | JSON, RSC in initial response can be indexed | Same |

**Recommendations for AI crawlability:**

| Practice | Action |
|----------|--------|
| **Server-side rendering** | Critical content in initial HTML. Use SSR, ISR, or SSG. See **rendering-strategies** for full guide. |
| **URL management** | Keep sitemaps updated; use consistent URL patterns; avoid outdated /static/ assets that cause 404s. AI crawlers frequently hit outdated URLs. |
| **Redirects** | Fix redirect chains; point directly to final URL. AI crawlers waste ~14% of fetches on redirects. |
| **404 handling** | Fix broken links; remove or redirect outdated URLs. High 404 rates suggest AI crawlers may use stale URL lists. |

**Reference**: [The rise of the AI crawler](https://vercel.com/blog/the-rise-of-the-ai-crawler) (Vercel, 2024)

## Common Issues

| Issue | Check |
|-------|-------|
| Redirect chains | Update links to point directly to final URL |
| Broken links | 301 or remove; audit internal and external |
| Orphan pages | Add internal links from hub or navigation; see **internal-links** for strategy |
| Infinite scroll | Provide paginated component pages; or replace with pagination for key content; see above |
| AI crawlers missing content | Ensure critical content in initial HTML; see **rendering-strategies** |

## Output Format

- **Redirect audit**: Chains and loops to fix
- **Broken link audit**: 4xx links to fix
- **Site structure**: Orphan pages, hierarchy
- **Pagination**: Implementation for crawlable content
- **AI crawler**: SSR/URL/redirect checks if GEO or AI visibility is a goal

## Related Skills

- **seo-strategy**: SEO workflow; crawlability is Technical phase (P0)
- **website-structure**: Plan which pages to build, page priority, structure planning; use before or alongside crawlability audit
- **robots-txt**: robots.txt configuration; AI crawler allow/block (GPTBot, ClaudeBot)
- **xml-sitemap**: URL discovery; keep updated to reduce AI crawler 404s
- **google-search-console**: Index status, Coverage report
- **indexing**: Fix indexing issues
- **internal-links**: Internal linking best practices
- **masonry**: Masonry + infinite scroll has same crawl issue; layout skill references this for SEO
- **generative-engine-optimization**: GEO strategy; AI search visibility; crawlability enables AI citation
- **canonical-tag**: Canonical reduces crawl budget waste on duplicates
- **rendering-strategies**: SSR, SSG, CSR; content in initial HTML; crawler visibility

---
name: core-web-vitals
description: When the user wants to optimize Core Web Vitals, fix LCP, INP, or CLS issues. Also use when the user mentions "Core Web Vitals," "CWV," "LCP," "INP," "CLS," "FID," "page speed," "page performance," "Largest Contentful Paint," "Interaction to Next Paint," "Cumulative Layout Shift," or "Page Experience." For GSC CWV, use google-search-console.
metadata:
  version: 1.0.1
---

# SEO Technical: Core Web Vitals

Guides optimization of Core Web Vitals (CWV)—Google's user experience metrics that affect search ranking. CWV are confirmed ranking factors for mobile and desktop.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **LCP** (Largest Contentful Paint): Loading performance; time to render largest content element
- **INP** (Interaction to Next Paint): Responsiveness; replaced FID in March 2024
- **CLS** (Cumulative Layout Shift): Visual stability; unexpected layout shifts

## Target Thresholds (75th percentile, field data)

| Metric | Target | Good | Needs Improvement | Poor |
|--------|--------|------|-------------------|------|
| **LCP** | ≤2.5s | ≤2.5s | 2.5–4.0s | >4.0s |
| **INP** | ≤200ms | ≤200ms | 200–500ms | >500ms |
| **CLS** | <0.1 | ≤0.1 | 0.1–0.25 | >0.25 |

**Source**: [Google Page Experience](https://developers.google.com/search/docs/appearance/page-experience)

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL.

Identify:
1. **Tools**: GSC Core Web Vitals report, PageSpeed Insights, Chrome DevTools
2. **Metrics**: Which metric is failing (LCP, INP, CLS)
3. **Page type**: Hero, article, product, list—LCP candidate differs

## LCP Optimization

LCP measures the time until the largest content element (image, video, or text block) is visible.

| Cause | Fix |
|-------|-----|
| **Slow server response** | Reduce TTFB; use CDN; optimize server |
| **Render-blocking resources** | Defer non-critical CSS/JS; inline critical CSS |
| **Large images** | WebP/AVIF; compress; `width`/`height` to prevent CLS; see **image-optimization** |
| **Client-side rendering** | SSR/SSG for above-fold content; see **rendering-strategies** |
| **Third-party scripts** | Load async; defer non-critical |

**LCP candidates**: Hero image, large text block, video poster. Ensure above-fold images use `loading="eager"` (default); never lazy-load LCP.

## INP Optimization

INP measures responsiveness—time from user interaction to next paint. Replaced FID in March 2024.

| Cause | Fix |
|-------|-----|
| **Long-running JS** | Break tasks >50ms; use `requestIdleCallback`; Web Workers |
| **Heavy event handlers** | Debounce/throttle; defer non-critical work |
| **Main thread blocking** | Reduce third-party scripts; defer non-critical JS |
| **Layout thrashing** | Batch DOM reads/writes; avoid forced reflows |

## CLS Optimization

CLS measures unexpected layout shifts.

| Cause | Fix |
|-------|-----|
| **Images without dimensions** | Always set `width` and `height` attributes |
| **Dynamic content** | Reserve space for ads, embeds; use `min-height` |
| **Web fonts** | `font-display: optional` or `swap`; preload critical fonts |
| **Animations** | Use `transform` instead of `top`/`left`/`width` |

**Reserve space**: For images, ads, embeds—define dimensions before load. Avoid inserting content above existing content without reserved space.

## Tools & Monitoring

| Tool | Use |
|------|-----|
| **GSC** | Core Web Vitals report; URL grouping; field data |
| **PageSpeed Insights** | Lab + field data; mobile + desktop |
| **Chrome DevTools** | Performance panel; LCP element; layout shift overlay |

## Output Format

- **Current state**: Which metrics fail (LCP, INP, CLS)
- **Prioritized fixes**: By impact
- **References**: [Web Vitals](https://web.dev/vitals/), [Page Experience](https://developers.google.com/search/docs/appearance/page-experience)

## Related Skills

- **image-optimization**: LCP image optimization; WebP; lazy loading (below-fold only)
- **google-search-console**: CWV report; field data monitoring
- **mobile-friendly**: Mobile-first indexing; mobile CWV targets
- **rendering-strategies**: SSR/SSG for LCP; content in initial HTML
- **site-crawlability**: Redirect chains waste crawl; fix for performance

---
name: canonical-tag
description: When the user wants to configure canonical URLs, fix duplicate content, or consolidate URL signals. Also use when the user mentions "canonical," "canonical URL," "duplicate content," "duplicate content fix," "preferred URL," or "URL consolidation." For GSC duplicates, use google-search-console.
metadata:
  version: 1.0.1
---

# SEO Technical: Canonical

Guides canonical tag configuration to consolidate duplicate content and declare preferred URLs.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Technical SEO)

- **Duplicate site versions**: HTTPS vs HTTP; www vs non-www; trailing slash (/page vs /page/) — choose one, 301 redirect others
- **Duplicate content**: Canonical tags; consolidate and 301 to preferred URL
- **HTTPS**: SSL/TLS; secure connection; ranking signal since 2014

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site URL and language structure.

Identify:
1. **Site URL**: Base domain
2. **Duplicate scenarios**: Multi-language, query params, pagination, alternate URLs
3. **Framework**: Next.js, React, static, etc.

## Canonicalization Methods (Choose by Scenario)

| Method | When | Strength |
|--------|------|----------|
| **301 redirect** | Preferred; server can redirect | Strongest — permanent redirect |
| **Canonical tag** | Cannot redirect (e.g. params, pagination) | Strong — HTML signal |
| **robots.txt** | Block non-canonical paths | Weak — advisory only |

Use 301 for HTTP→HTTPS, www variants, trailing slash. Use canonical for params, pagination, UTM.

## HTTPS & Security

HTTPS is a ranking signal ([Google, 2014](https://developers.google.com/search/blog/2014/08/https-as-ranking-signal)). Users and crawlers should access only the HTTPS version.

| Requirement | Action |
|-------------|--------|
| **SSL/TLS certificate** | Install valid certificate; use Let's Encrypt for free |
| **301 redirect** | HTTP → HTTPS; all HTTP requests redirect to HTTPS |
| **Mixed content** | No HTTP resources on HTTPS pages; fix mixed content warnings |
| **HSTS** | Optional; `Strict-Transport-Security` header for repeat visitors |

**WWW vs non-WWW**: Choose one preferred version; 301 redirect the other. See canonical rules above.

## When to Use Canonical

- **Multi-language**: Each language version has its own canonical; use **hreflang** with canonical
- **Same content, multiple URLs**: Params, pagination, tracking params, www vs non-www, trailing slash (/page vs /page/)
- **Self-referencing**: Canonical should point to self or the preferred version
- **Avoid chain canonical**: A→B→C is invalid

## Rules

| Rule | Note |
|------|------|
| **Absolute URL** | Include `https://` |
| **Consistency** | Must match current page URL or the chosen preferred version |
| **No chains** | A→B→C is invalid |

## Implementation Patterns

### Next.js (metadata)

```tsx
export const metadata = {
  alternates: {
    canonical: "https://example.com/page-slug",
    languages: {
      zh: "https://example.com/zh/page-slug",
      en: "https://example.com/page-slug",
      "x-default": "https://example.com/page-slug",
    },
  },
};
```

### HTML (generic)

```html
<link rel="canonical" href="https://example.com/page-slug" />
```

### Server Redirects (301)

**Apache (.htaccess)**:
```apache
RewriteEngine On
RewriteCond %{HTTPS} off
RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
```

**Nginx**:
```nginx
return 301 https://$host$request_uri;
```

## Relationship to Other Technical SEO

- **Sitemap**: URLs in sitemap should match canonical
- **IndexNow**: Submit canonical URLs

## Output Format

- **Canonical URL** for each page type
- **Implementation** (metadata or HTML)
- **Multi-language** setup if applicable
- **References**: [Alignify URL optimization](https://alignify.co/zh/seo/url-optimization); [Google Canonical](https://developers.google.com/search/docs/crawling-indexing/consolidate-duplicate-urls)

## Related Skills

- **url-structure**: URL hierarchy and format; canonical handles duplicate variants (HTTPS, www, trailing slash)
- **localization-strategy**: hreflang + canonical for multi-language
- **xml-sitemap**: Sitemap URLs should match canonical
- **indexnow**: Submit canonical URLs
- **google-search-console**: Find duplicate content in Coverage report
- **indexing**: Resolve indexing issues
- **site-crawlability**: Crawl budget; redirect chains; canonical reduces duplicate crawl waste

---
name: programmatic-seo
description: When the user wants to create SEO pages at scale using templates and data—including AI-assisted, grounded copy for per-URL differentiation (vs rigid mail-merge templates). Also use when the user mentions "programmatic SEO," "programmatic SEO pages," "template pages," "scale content," "location pages," "city pages," "comparison pages at scale," "X vs Y pages," "integration pages," "pages from data," "automated landing pages," or "programmatic landing pages." Uses a playbook matrix aligned to skills under skills/pages. For user-facing template galleries or marketplaces (browse → use), use template-page-generator.
metadata:
  version: 1.4.0
---

# SEO: Programmatic SEO

Guides programmatic SEO—creating large numbers of SEO-optimized pages automatically using templates and structured data, rather than writing each page manually. **Classic “mail merge” pSEO** (one rigid template + swapped variables) often produced **low differentiation** and thin-feeling URLs. **With AI used responsibly on top of the same data spine**, you can scale **per-URL customization**—intent-aligned copy, section depth, FAQs, tone, localization—while still following **evidence blocks**, **data tiers**, and **QA** (see **Data strength hierarchy** and **AI-assisted generation** below).

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

**Project context**: If `.claude/project-context.md` or `.cursor/project-context.md` exists, read product/ICP sections before proposing playbooks or page types.

## Definition

**Programmatic SEO** = Building a single template and populating it with data from a database, API, or spreadsheet to generate hundreds or thousands of unique pages. Each page targets a long-tail keyword (e.g., "best SEO tool in [city]," "[App A] + [App B] integration").

**Key differences from traditional SEO**: Technical (SEOs + engineers); long-tail focus; data-driven (data quality = success); automation; built for scale.

## Classic limits vs AI-enhanced differentiation

| Era | What breaks | What helps |
|-----|-------------|------------|
| **Rigid pSEO** | One template, minimal variance → similar titles/bodies, weak **E-E-A-T**, “obvious mail merge” | Still needs **unique evidence per URL** and selective indexation |
| **AI-enhanced pSEO** | Same **structured rows** (facts, SKUs, metrics) drive the page, but models add **per-URL narrative**: intros, FAQ depth, persona angles, localization, internal-link suggestions—**higher differentiation** at scale | **Facts stay in your data layer**; AI shapes **phrasing and structure**, not invented numbers—see **AI-assisted generation** |

**Best-practice stance**: AI is an **accelerator and customizer**, not a substitute for **data defensibility** (Tiers 1–5) or **technical SEO** (URLs, schema, CWV). Used well, it aligns with **quality over quantity**: fewer thin URLs, more **distinct** useful pages.

## Three-Part Framework

| Component | Role |
|-----------|------|
| **Templates** | Reusable page structures: layout, headings, internal links, content blocks; conditional logic for empty fields |
| **Data** | Structured information: locations, products, prices, features—must be accurate, complete, and add genuine value |
| **Automation** | Systems connecting data to templates; pages generated dynamically or published in bulk |
| **AI layer (optional)** | On **grounded inputs** (row JSON + rules), generates **varied copy**, FAQ expansions, and section emphasis **per URL**—reduces “same template” fatigue while staying auditable |

## Page Playbook Matrix (`skills/pages`)

Page types in this library live under `pages/{brand|content|legal|marketing|utility}/`. Use the matrix below to map **search pattern → playbook → which `*-page-generator` skill** to open for structure, copy, and schema—not every folder is a good fit for mass-generated URLs.

| Playbook | Example intent / keyword pattern | Page skill (`name`) | Path (reference) |
|----------|----------------------------------|---------------------|------------------|
| **Alternatives / comparisons** | "[Competitor] alternatives", "X vs Y" | alternatives-page-generator | `pages/marketing/alternatives` |
| **Integrations** | "[Product A] [Product B] integration" | integrations-page-generator | `pages/marketing/integrations` |
| **Category / catalog** | Faceted listings, product grids | category-page-generator, products-page-generator | `pages/marketing/category-pages`, `products` |
| **Glossary / definitions** | "what is [term]", term landings | glossary-page-generator | `pages/content/glossary` |
| **FAQ / Q&A** | Question banks, PAA-style pages | faq-page-generator | `pages/content/faq` |
| **Tools & lead magnets** | "free [x] tool/calculator" | tools-page-generator | `pages/content/tools` |
| **Template gallery** | Browse → detail (your templates) | template-page-generator | `pages/content/template-page` |
| **Resource hub** | Guides, hubs, download centers | resources-page-generator | `pages/content/resources` |
| **Use cases / solutions** | "for [role]", "by industry" | use-cases-page-generator, solutions-page-generator | `pages/marketing/use-cases`, `solutions` |
| **Migration / switching** | "migrate from [X]" | migration-page-generator | `pages/marketing/migration` |
| **Campaign landing** | Paid/segment LPs | landing-page-generator | `pages/marketing/landing-page` |
| **Blog / article** | Long-tail articles at scale | blog-page-generator, article-page-generator | `pages/content/blog`, `article` |
| **Docs / features / API** | Scalable doc sections, feature landings, `/api` marketing | docs-page-generator, features-page-generator, api-page-generator | `pages/content/docs`, `features`, `api` |
| **Social proof** | Logos, case studies, galleries | press-coverage-page-generator, customer-stories-page-generator, showcase-page-generator | `pages/marketing/press-coverage`, `customer-stories`, `showcase` |
| **Programs & offers** | Startups/education, contests, downloads, affiliate, media kit | startups-page-generator, contest-page-generator, download-page-generator, affiliate-page-generator, media-kit-page-generator | `pages/marketing/*` |
| **Pricing / services** | Plans, offerings (use sparingly for pSEO) | pricing-page-generator, services-page-generator | `pages/marketing/pricing`, `services` |

**Usually not mass programmatic** (single primary URL or compliance-heavy): `pages/brand/*` (home, about, contact), `pages/legal/*`, most `pages/utility/*` (404, status, signup-login, etc.)—treat as one-off or policy-driven, not template×data scale.

## Choosing a Playbook

| If you have… | Lean toward… | Open first… |
|----------------|--------------|-------------|
| Competitor list + positioning | Alternatives / comparisons | alternatives-page-generator |
| Integration directory (your + partners') | Integrations matrix | integrations-page-generator |
| Product catalog or SKUs | Category / product grids | category-page-generator, products-page-generator |
| Term / definition database | Glossary | glossary-page-generator |
| Support tickets / PAA mined questions | FAQ scale | faq-page-generator |
| Lead magnets, calculators | Tools hub + per-tool | tools-page-generator |
| **Your own templates** (exports, gallery items) | Template marketplace | template-page-generator |
| ICP × industry matrix | Use cases / solutions | use-cases-page-generator, solutions-page-generator |
| Import paths from competitors | Migration | migration-page-generator |
| Campaign or geo LPs | Landing pages | landing-page-generator |
| Long-form SEO articles | Blog index + single post | blog-page-generator, article-page-generator |

## Template Structure (Recommended)

| Section | Purpose |
|---------|---------|
| **Intro** | Introduction; matches user intent |
| **Evidence block** | Data-driven content unique to each page (tables, lists, verified stats); differentiates from thin content |
| **Decision** | Comparison, recommendation, or next steps |
| **FAQ** | Frequently asked questions |
| **CTA** | Call-to-action |

**Evidence block** = Real, structured data per page (business listings, pricing, reviews, verified stats). Ensures each page delivers genuine value, not recycled boilerplate with swapped variables.

## Data strength hierarchy (defensibility)

**Strongest programmatic pages are fueled by what only your product (or your customers inside your product) can produce**—especially **templates, exports, and generated artifacts**. Third-party or scraped lists alone are the weakest foundation.

| Tier | Source | Examples | Relative risk |
|------|--------|----------|----------------|
| **1 — Product-generated** | Assets created or rendered by your product: page/layout **templates**, email/Notion/code templates, export packs, generated previews, branded snippets, “built with [Product]” examples | Template gallery rows tied to real `.json` / CMS fields; screenshots of exports; unique preview URLs | **Lowest** when each URL shows distinct generated output |
| **2 — Product-derived** | Telemetry and in-product data you own: aggregates, cohorts, benchmarks, feature adoption | “Teams in [industry] median time-to-value” from your warehouse (aggregated) | Low if aggregated / anonymized and policy-compliant |
| **3 — UGC / customer** | Reviews, submissions, showcase items, moderated community content | Showcase grid; verified quotes | Medium—needs moderation + consent |
| **4 — Licensed / partner** | Exclusive feeds, co-marketing datasets | Partner pricing tiers; licensed industry stats | Medium—contract and citation discipline |
| **5 — Public / scraped** | Open web, directories, generic enrichment | Name/address fills; commodity facts | **Highest**—needs editorial layer, fact-checking, and a real **Evidence block** |

**Why Tier 1 (templates & generated content) wins**: Pages built from **your** template system carry proprietary structure, variables, and brand-safe blocks—harder for competitors to copy verbatim and easier to prove uniqueness (embeds, downloads, IDs). Pair with **template-page-generator** when the UX is “browse gallery → use template.”

### Tier 2 — Product-derived (practical)

| What it is | What to watch |
|------------|----------------|
| Metrics from **your** backend, data warehouse, or support/CRM exports: activation rates by segment, integration popularity, error budgets, time-to-value—not generic “industry reports.” | **Privacy & ToS**: Minimum cell sizes; no individual identification; document what was aggregated and over what window. |
| Good fit when you can show **“only we could know this because it runs in our product.”** | **Stale data** hurts trust: pipeline jobs, “as of [date]” labels, automated invalidation. |

**AI here**: Use models to **turn structured aggregates into prose** (intro paragraphs, “what this means for [segment]”)—**input must be verified numbers/tables from your pipeline**, not free-form invention. Keep a **machine-readable table or JSON** on-page or in appendix so claims stay auditable.

### Tier 3 — UGC / customer (practical)

| What it is | What to watch |
|------------|----------------|
| Quotes, reviews, showcase submissions, community templates—**per-user artifacts** with consent. | **Moderation**: spam, PII, competitor attacks; **consent** for name/logo use; **schema** (Review, CreativeWork) only when accurate. |
| Strong when combined with **Tier 1** (e.g. “customer-built template” gallery). | **Volume without quality** → thin pages; cap or score submissions. |

**AI here**: Summarize long reviews into bullets; **generate draft alt text** for images; **cluster** submissions into topic pages—always **human approve** before publish. Do not fabricate testimonials.

### Tier 4 — Licensed / partner (practical)

| What it is | What to watch |
|------------|----------------|
| Partner price lists, co-marketed reports, API-fed **allowed** fields (logos, SKUs). | **Contract scope**: Which fields can appear on which URLs; attribution line; **DMCA / trademark** on logos. |
| Often **one feed → many URLs**; uniqueness must come from **your framing**, comparison logic, or calculator—not the raw feed alone. | **Refresh cadence** tied to partner SLAs. |

**AI here**: Draft **comparison copy** and **FAQs** from a **fixed attribute table** (license + partner rules); never invent SKUs or prices—**pull from feed**, let AI phrase and shorten.

### Tier 5 — Public / scraped (practical)

| What it is | What to watch |
|------------|----------------|
| Open data, directories, Wikipedia-style facts, **enrichment** of public entities. | **Highest** duplicate/thin risk: everyone has the same facts; **you must add** synthesis, editorial angle, or a **unique tool** (calculator, filter) on top. |
| **Entity SEO** and **citations** matter: link to authoritative sources; date-stamp volatile facts. | Plan for **pruning** or **noindex** on low-traffic thin URLs. |

**AI here**: Use models to **structure** messy public text into tables, **outline** sections, **suggest** internal links—then **fact-check** names, numbers, and dates. **Do not** use AI to invent statistics or citations; treat output as **draft** until verified.

### AI-assisted generation (cross-tier)

**Why AI fits modern pSEO**: Early programmatic SEO earned a bad reputation because **templates were frozen** and **copy was interchangeable**—little real differentiation per query. **LLMs**, when **grounded** on each row’s facts and your brand rules, make it practical to **customize** headlines, intros, FAQs, and “why this page matters” **per URL** without hand-writing thousands of pages. That moves execution closer to **best practices** (intent match, helpful content, unique value) **at scale**, provided you **do not** let the model invent data.

| Principle | Why |
|-----------|-----|
| **Ground AI in structured inputs** | Pass JSON/CSV rows (tier, source URL, metrics) into prompts; **forbid** hallucinated numbers in system prompts. |
| **Separate “facts” from “phrasing”** | Data layer = source of truth; AI = tone, shortening, localization, FAQs, **per-segment emphasis**—never the other way around. |
| **Vary structure, not only adjectives** | Ask for different **section order**, FAQ count, or “beginner vs power user” angles **by intent flags** in the row—reduces template sameness. |
| **Human or automated QA** | Spot-check high-traffic URLs; block publish if required fields empty or citation missing. |
| **Disclose when useful** | e.g. “Intro generated with AI; figures from [internal report, Q3 2025].” Builds trust and matches policy trends. |

**When AI generation is a strong lever**: Tiers **2–5**—where raw material is already tabular or repetitive but **needs readable, differentiated copy at scale**. Tier **1** still benefits from AI (drafts from export JSON), but the **differentiator remains** the product artifact itself.

### Operational requirements (all tiers)

| Requirement | Practice |
|-------------|----------|
| **Provenance** | Log data sources; track origin per field |
| **Freshness rules** | e.g., ratings every 90 days, prices every 30 days, template version bumps when layouts change |
| **Prefer 1–2 over 5** | Fill evidence with product-generated or product-derived data before reaching for public scraping |
| **AI governance** | Structured inputs only; no unverified numbers; moderation on UGC; optional disclosure |
| **Clean & merge** | Deduplicate keys; drop rows that produce duplicate intents |

## Ideal Use Cases

For **which page-generator skill to use**, see **Page Playbook Matrix** above. Generic patterns:

| Use case | Example |
|----------|---------|
| **Location-specific pages** | "Plumber in [city]," "Best restaurants in [neighborhood]" with real local data |
| **Product comparison** | "[Product A] vs [Product B]" with structured specs |
| **Alternatives pages** | "[Competitor] alternatives" at scale; 50+ competitors; see **alternatives-page-generator** |
| **Software integration** | "[App A] + [App B]" integration pages (e.g., Zapier 50K+ pages) |
| **Free tools** | "[X] checker," "[Y] calculator," "[Z] generator" — standalone tool pages; toolkit hub; same ICP as main product; lead gen |
| **Travel / destination** | City + attraction combinations with reviews, photos |
| **E-commerce** | Category pages, product variations (size, color, material) |
| **FAQ / Q&A** | Pages powered by user question databases |
| **Salary / pricing** | Comparison pages with structured data |

**Avoid when**: Site structure is weak; page differences are superficial (city/name swaps only); content requires original expertise or UGC participation.

## Real-World Examples

*Examples are illustrative; no endorsement implied.*

| Company | Scale | Pattern |
|---------|-------|---------|
| **Zapier** | 50,000+ pages | "[App A] + [App B]" integration |
| **Airbnb** | — | Location search; destination × property |
| **Review platforms** | — | User reviews + automated comparison pages |
| **Travel sites** | — | Destination, hotel, flight, activity pages |
| **NomadList** | 2,000+ city pages | Cost-of-living, internet speed (dynamic data) |
| **Semrush, Ahrefs** | 50+ free tools | SEO checker, keyword tool, backlink checker; toolkit hub + per-tool pages |

## Content Requirements

| Requirement | Purpose |
|-------------|---------|
| **300+ words per page** | Avoid thin content penalties |
| **Unique, verifiable data** | Each page must add meaningful page-specific content beyond simple data swaps |
| **Evidence block** | Tables, lists, examples with real numbers/attributes on every page |
| **Semantic HTML** | Proper structure; conditional logic to avoid empty or repetitive sections |
| **Internal linking** | Link related programmatic pages; compounds traffic and indexation |

## Technical Considerations

| Topic | Practice |
|-------|----------|
| **Subfolder vs subdomain** | Prefer **subfolders** (`yoursite.com/integration/slack-notion/`) over **subdomains** (`integrations.yoursite.com/...`) so authority consolidates on the primary domain; see **url-structure**, **domain-architecture** if restructuring |
| **Selective indexation** | Don't index all pages; use noindex rules for low-value pages |
| **Sitemap segmentation** | By country, language, division; manage crawl budget |
| **URL structure** | Descriptive URLs; clean hierarchy; see **url-structure** |
| **Schema** | JSON-LD: Product, Place, FAQ, ItemList per page type |
| **Performance** | Caching, static generation; Core Web Vitals |

## Critical Pitfalls

| Pitfall | Consequence |
|---------|-------------|
| **Thin content** | Minimal info beyond keyword; generic copy; placeholder sections → penalties |
| **Duplicate pages** | Same content with only data swaps → thin content penalties |
| **Index bloat** | Generating pages that should never be indexable → crawl budget waste |
| **Large dumps** | Publishing many similar pages at once → spam signals |
| **Filter URLs** | Using filters instead of unique URLs/titles → cannibalization |

Pages with only a title, one paragraph, and swapped city names will not rank and may incur Google penalties.

## Step-by-Step Workflow

1. **Research** — Niche, intent; include low-volume keywords; SEO tools, question databases
2. **Collect data** — Provenance log, freshness rules; first-party/licensed; define template fields
3. **Choose stack** — Next.js + DB, Webflow CMS, WordPress, headless; API + template reuse
4. **Design template** — Intro, Evidence, Decision, FAQ, CTA; schema; conditional logic
5. **Build database** — Map fields to template slots; hide empties
6. **Generate pages** — Descriptive URLs; optimize performance
7. **Deploy & monitor** — Sitemaps; indexation, rankings, CTR, bounce, conversions
8. **Optimize** — Prune weak pages; refresh data; A/B test layout, CTA

## Best Practices

| Practice | Purpose |
|----------|---------|
| **Quality over scale** | Each page must provide genuinely unique, verifiable value |
| **Differentiation over clone** | Prefer **AI-grounded** copy variance + evidence blocks over one static paragraph with `{city}` swaps |
| **Launch in batches** | Small batches you can measure; avoid large dumps |
| **Strong IA** | Internal links to related guides/categories |
| **Visual elements** | Tables, maps, comparisons where relevant |
| **Match intent** | Avoid generic template text; precise user intent |

## Timeline & Expectations

- **Typical time to ranking**: ~6 months
- **Reported gains**: 40%+ traffic increases from well-designed topic clusters
- **AI search**: Structured, data-rich content performs better in AI Overviews and citation layers

## Output Format

- **Template design** (Intro, Evidence, Decision, FAQ, CTA; required data fields)
- **Data requirements** (provenance, freshness, accuracy)
- **Internal linking** (hub-and-spoke, related pages)
- **Indexation strategy** (selective indexation, sitemap segmentation)
- **Checklist** for audit

## Related Skills

- **template-page-generator**: Template structure; aggregation (gallery) + detail pages; **Tier 1 product-generated** template URLs
- **landing-page-generator**: Conversion-focused programmatic pages; LP structure for campaign CTA
- **tools-page-generator**: Free tools pages; toolkit hub; programmatic tool pages; lead gen
- **alternatives-page-generator**: Alternatives/comparison pages at scale; competitor brand traffic
- **category-page-generator**, **products-page-generator**: Category / catalog grids
- **glossary-page-generator**, **faq-page-generator**, **resources-page-generator**: Definitions, Q&A banks, content hubs
- **use-cases-page-generator**, **solutions-page-generator**, **migration-page-generator**: ICP/industry matrix, migration SEO
- **integrations-page-generator**: Integration pair pages at scale
- **blog-page-generator**, **article-page-generator**, **docs-page-generator**, **features-page-generator**, **api-page-generator**: Long-form and product surface scale
- **press-coverage-page-generator**, **customer-stories-page-generator**, **showcase-page-generator**: Proof at scale
- **startups-page-generator**, **contest-page-generator**, **download-page-generator**, **affiliate-page-generator**, **media-kit-page-generator**, **pricing-page-generator**, **services-page-generator**: Programs and offers (use selectively for pSEO)
- **content-strategy**: Content clusters, pillar pages; programmatic pages as cluster nodes
- **website-structure**: Site IA before scaling URL sets
- **url-structure**, **domain-architecture**: Paths, subfolder strategy
- **schema-markup**: Structured data (Product, Place, FAQ, ItemList)
- **internal-links**: Linking programmatic pages
- **xml-sitemap**: Sitemap segmentation for large programmatic sites
- **canonical-tag**: Duplicate/thin content handling
- **seo-strategy**, **seo-audit**: Roadmap and post-launch audits

---
name: parasite-seo
description: When the user wants to choose or execute third-party platform SEO (high-authority sites for rankings or backlinks). Also use when the user mentions "parasite SEO," "parasitic SEO," "barnacle SEO," "hosted content," "third-party publishing," "Medium SEO," "Reddit SEO," "GitHub parasite SEO," "LinkedIn Pulse SEO," "high-authority platforms," "distributed authority," "borrow domain authority," or "rank without own website." For GitHub-specific playbooks, use github. For Medium.com posts, use medium-posts. For Grokipedia, use grokipedia-recommendations. For AI answer-engine visibility (not platform selection), use generative-engine-optimization.
metadata:
  version: 1.1.0
---

# SEO: Parasite SEO

Guides parasite SEO (also "barnacle SEO")—publishing optimized content on high-authority third-party platforms (Medium, Reddit, LinkedIn, Grokipedia, etc.) to leverage their domain strength for rankings and backlinks, bypassing the need to build your own site's authority from scratch.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## What Is Parasite SEO

**Parasite SEO** = Placing content on high-authority platforms to leverage their domain strength for rankings and AI citation. Part of "Distributed Authority Engineering."

Instead of waiting months for your own domain to gain trust, you publish on established platforms that Google already trusts. Content can rank on page one within days rather than months because Google crawls these platforms frequently and inherits their domain trust.

**Best for**: Beginners testing niches; local businesses needing quick leads; demand validation; supplementing traditional SEO.

## Why It Works

| Factor | Effect |
|--------|--------|
| **Domain authority** | Platforms (DA 90+) rank faster than new sites |
| **Crawl frequency** | Google crawls Reddit, Medium, LinkedIn often |
| **AI citation** | ChatGPT, Perplexity cite Reddit, Quora, wikis |
| **UGC preference** | Algorithm updates favor UGC platforms as trustworthy |
| **Technical foundation** | High-authority sites have strong technical SEO, fast load, good UX |

## Platform Tiers

*Platform examples are illustrative only. No endorsement implied.*

| Tier | Platform type | Examples | GEO / AI citation |
|------|---------------|----------|-------------------|
| **Tier 1** | GEO authority | Medium, Reddit, LinkedIn Articles, Quora | Very high |
| **Tier 2** | Technical authority | GitHub, Stack Overflow, Dev.to | High; expertise signals |
| **Tier 3–6** | Controlled / entity / wiki | WordPress.com, Blogger, HN, Grokipedia | Varies |

### Platform Notes

| Platform | Use case | Notes |
|----------|----------|-------|
| **LinkedIn Pulse** | B2B, agencies, professional content | Keywords in headlines; often ranks above corporate blogs |
| **Medium** | How-to, thought leadership | Use canonical link if reposting; storytelling works |
| **Reddit** | Product reviews, alternatives, discussions | Comprehensive guides; upvoted threads rank well |
| **Quora** | Q&A, long-tail informational | Answer industry questions; link to resources naturally |
| **YouTube** | Video search, how-to, reviews | Titles, descriptions, tags; watch time matters |
| **GitHub** | Repos, README, Pages, gists, awesome lists | Tier 2 technical authority; very high AI citation; see **github** |
| **Grokipedia** | AI encyclopedia | See **grokipedia-recommendations** for contribution flow |
| **Free web builders** | WordPress.com, Wix | Indexable content; lower authority than above |

## Keyword & Content Strategy

| Element | Practice |
|---------|----------|
| **Keyword targeting** | Intent-driven; mid-competition and long-tail; clear monetization potential |
| **Content depth** | 1,500+ words for competitive keywords; comprehensive coverage |
| **Keyword placement** | Primary keyword in title and first 100 words; headers, subheadings, body |
| **Semantic relevance** | Natural language; avoid keyword stuffing |
| **Content clustering** | Create clusters around topics; link related articles within platform |

## On-Page Optimization

| Element | Practice |
|---------|----------|
| **Title** | Target keyword; platform + search-optimized |
| **Meta / description** | Where allowed; keyword usage |
| **Internal links** | Link to other parasite content on same platform |
| **Visuals** | Images, infographics, videos improve engagement |
| **CTA** | Strong, relevant call-to-action |

## Link Building Through Parasite SEO

| Tactic | Purpose |
|--------|---------|
| **Tier-2 backlinks** | Build links from Web 2.0s, guest posts pointing to your parasite content |
| **Strategic linking** | Link from parasite content to owned site; natural, not spammed |
| **Cross-platform linking** | Link related content across platforms; network effect |

## Advanced Techniques

| Technique | Use |
|-----------|-----|
| **Content clustering** | Multiple related articles on same platform; topical authority |
| **Cross-platform syndication** | Adapt core content per platform; different keywords; avoid duplicate content |
| **Keyword layering** | Multiple related keywords in one piece; maximize ranking potential |

## Risks & Compliance

| Risk | Mitigation |
|------|------------|
| **Google Site Reputation Abuse (2024)** | Targets manipulative third-party content. Ensure genuinely useful content; not purely for link/mention manipulation. |
| **Platform bans** | Spammy, promotional content gets removed; accounts suspended |
| **Duplicate content** | Use canonical when republishing; avoid thin content |
| **Over-optimization** | Prioritize user value over aggressive optimization |

## Common Mistakes

| Mistake | Avoid |
|---------|-------|
| **Quality neglect** | Low-quality, thin content doesn't sustain; harms SEO |
| **Policy violations** | Check platform guidelines; adhere to policies |
| **Short-term tactics** | Build sustainable relationships; create value consistently |

## Output Format

- **Platform selection** (match to intent and audience)
- **Keyword strategy** (intent, long-tail, placement)
- **Content structure** (depth, clustering, per-platform format)
- **Link strategy** (tier-2, cross-platform, owned property)
- **Related platform skills** (reddit-posts, grokipedia-recommendations, etc.)

## Related Skills

- **github**: GitHub for parasite SEO; repos, README, Pages, gists, awesome lists
- **grokipedia-recommendations**: Add recommendations/links to Grokipedia; parasite SEO + GEO
- **reddit-posts**: Reddit post copy; high-authority community for parasite SEO
- **medium-posts**: Medium publishing; parasite SEO; canonical setup
- **generative-engine-optimization**: GEO strategy; parasite SEO complements AI citation
- **link-building**: Parasite SEO as link acquisition tactic; tier-2 backlinks
- **directory-submission**: Directory and curated list submission; similar placement logic
- **community-forum**: Forum and community promotion; HN, Indie Hacker
- **indie-hacker-strategy**: Indie hacker growth; Indie Hackers, Reddit as channels
- **seo-strategy**: SEO workflow; parasite SEO as alternative strategy

---
name: video-optimization
description: When the user wants to optimize videos for Google Search, video sitemap, VideoObject schema, or video SEO on websites. Also use when the user mentions "video SEO," "video sitemap," "VideoObject," "video thumbnail," "video indexing," "video preview," "key moments," "Clip schema," or "embedded video optimization." For page template, use article-page-generator.
metadata:
  version: 1.0.1
---

# SEO On-Page: Video Optimization

Guides video optimization for Google Search (main results, video mode, Google Images, Discover), video sitemap, VideoObject schema, and indexing. **Note**: Google now prioritizes YouTube video results in search; YouTube + Reddit comprise ~78% of social media citations in AI Overviews. For YouTube-specific optimization, see **youtube-seo**; for GEO distribution via YouTube, see **generative-engine-optimization**. References: [Google Video SEO](https://developers.google.com/search/docs/appearance/video), [Semrush YouTube SEO](https://www.semrush.com/blog/youtube-seo/).

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope

- **Discovery & indexing**: HTML embed elements, video sitemap
- **Metadata**: Title, description, thumbnail; stable URLs
- **Structured data**: VideoObject schema
- **Features**: Video preview, key moments (Clip, SeekToAction), LIVE badge
- **YouTube prioritization**: Google favors YouTube in search; embed or host on YouTube for GEO citation

## YouTube in Google Search (2025+)

**Google prioritizes YouTube video results** across search. YouTube receives 48.6B monthly visits (second to Google.com) and is treated as core search infrastructure for AI-driven discovery. [Search Engine Land](https://searchengineland.com/youtube-seo-ai-overviews-467253)

| Context | Implication |
|---------|-------------|
| **AI Overviews** | YouTube citations surged 25.21% since Jan 2025; instructional (+35.6%), visual demos (+32.5%); long-form dominates (94%) |
| **GEO** | YouTube + Reddit = ~78% of social media citations; Perplexity (38.7%) and Google AI Overviews (36.6%) drive most YouTube citations |
| **Strategy** | Embed YouTube on site pages for dual indexing; or host on YouTube for GEO citation. See **youtube-seo**, **generative-engine-optimization** |

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for brand and page context.

Identify:
1. **Hosting**: Self-hosted vs YouTube/Vimeo embed
2. **Page type**: Dedicated watch page vs supplementary (e.g. blog with embedded video)
3. **Features needed**: Preview, key moments, LIVE badge

---

## 1. Discovery & Indexing

### Use Standard HTML Embed Elements

Google finds videos in `<video>`, `<embed>`, `<iframe>`, or `<object>`. **Do not** use fragment identifiers to load video; avoid requiring user interaction (click, swipe) to load.

| Do | Don't |
|----|-------|
| `<video><source src="...mp4"/></video>` | Fragment-only load; JS-injected without fallback |
| `<iframe src="https://youtube.com/embed/...">` | Hide video behind paywall without paywall structured data |

**JavaScript injection**: If video is injected via JS, ensure it appears in rendered HTML; use URL Inspection in Search Console. If using Media Source API, inject HTML video container even when API fails so Google can find metadata.

### Video Sitemap

Submit a [video sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/video-sitemaps) to help Google discover videos. Use `<video:video>` extension; `<loc>` = watch page URL.

**Structure** (from Google):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:video="http://www.google.com/schemas/sitemap-video/1.1">
  <url>
    <loc>https://example.com/videos/watch-page.html</loc>
    <video:video>
      <video:thumbnail_loc>https://example.com/thumbs/123.jpg</video:thumbnail_loc>
      <video:title>Grilling steaks for summer</video:title>
      <video:description>Bob shows you how to grill steaks perfectly.</video:description>
      <video:player_loc>https://example.com/player?video=123</video:player_loc>
    </video:video>
  </url>
</urlset>
```

See **xml-sitemap** for sitemap index. Video sitemap is an extension; can be standalone or combined.

### Indexing Requirements

- **Watch page** must be indexed and perform well in search
- **Video embedded** on watch page; not hidden behind elements
- **Thumbnail**: Valid, stable URL; ≥60×30 px; ≥80% alpha >250 (no heavy transparency)
- **Supported formats**: 3GP, 3G2, ASF, AVI, DivX, M2V, M3U, M3U8, M4V, MKV, MOV, MP4, MPEG, OGV, WebM, WMV, etc. **Data URLs not supported.**

### Dedicated Watch Page

For video features (main results, video mode, key moments, LIVE badge), create a **dedicated watch page** per video—page whose primary purpose is to display that video. Examples: video landing page, episode player page, news video page. **Not** watch pages: blog with embedded video, product page with 360° video, category page with multiple videos.

---

## 2. Stable URLs

- **Thumbnail**: Stable URL; CDNs with fast-expiring URLs can prevent indexing
- **Content URL**: Stable for video preview and key moments; use `contentUrl` in VideoObject
- **Player URL**: Stable for `embedUrl` / `player_loc`

---

## 3. Thumbnail & Metadata

### Thumbnail Sources (in priority order)

| Source | How |
|--------|-----|
| `<video>` poster | `poster` attribute |
| Video sitemap | `<video:thumbnail_loc>` |
| VideoObject | `thumbnailUrl` |
| OGP | `og:video:image` |

Use **same thumbnail URL** across all metadata sources.

### Thumbnail Specs

| Spec | Requirement |
|------|-------------|
| Formats | BMP, GIF, JPEG, PNG, WebP, SVG, AVIF |
| Size | Min 60×30 px; larger preferred |
| Transparency | ≥80% of pixels with alpha >250 |
| Access | Must be crawlable (no robots.txt block, no login) |

### Unique Metadata per Video

Provide **unique** `thumbnailUrl`, `name`, and `description` for each video in structured data and sitemap. Consistency with visible content is required.

---

## 4. VideoObject Schema

```json
{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "Grilling steaks for summer",
  "description": "Bob shows you how to grill steaks perfectly every time.",
  "thumbnailUrl": "https://example.com/thumbs/123.jpg",
  "uploadDate": "2025-01-15T08:00:00Z",
  "contentUrl": "https://example.com/video/123.mp4",
  "embedUrl": "https://example.com/player?video=123"
}
```

**Required for rich results**: `thumbnailUrl`, `name`, `description`. Add `contentUrl` for video preview and key moments. See **schema-markup** for full VideoObject; **serp-features** for Video SERP feature.

---

## 5. Video Features

### Video Preview

Google selects short clips as dynamic previews. Allow Google to fetch video file; use `max-video-preview` robots meta to limit duration.

### Key Moments (Chapters)

| Method | Use |
|--------|-----|
| **Clip** | Exact start/end + label per segment; all languages |
| **SeekToAction** | Tell Google where timestamps live in URL; auto-detect; supported languages: en, es, pt, it, zh, fr, ja, de, tr, ko, nl, ru |
| **YouTube** | Timestamps in description; see **youtube-seo** |

Disable key moments: `nosnippet` meta.

### LIVE Badge

Use `BroadcastEvent` schema for live streams to show "LIVE" in results.

---

## 6. Allow Google to Fetch Video File

For **video preview** and **key moments**, Google must fetch the actual video bytes. Do not block `contentUrl` with noindex or robots.txt. Use stable URLs; ensure both watch page host and video/CDN host have sufficient capacity for crawling.

---

## 7. Third-Party Embeds (YouTube, Vimeo)

Google may index both your page and the platform's page. For your watch page: still add VideoObject and optionally video sitemap. For more features (preview, key moments), confirm the platform allows Google to fetch video files.

---

## 8. Removal & Restrictions

- **Remove**: 404 on watch page, or `noindex`; or set `expires` in schema / `<video:expiration_date>` in sitemap
- **Geo-restrict**: `regionsAllowed` or `ineligibleRegion` in VideoObject; `<video:restriction>` in sitemap

---

## 9. SafeSearch & Monitoring

- Mark pages appropriately for SafeSearch if content is adult. See [Google SafeSearch](https://developers.google.com/search/docs/appearance/safesearch).
- **Search Console**: Video indexing report; Video rich results report; Performance filtered by "Video" search appearance.

---

## Specs by Context

| Context | Priority | Notes |
|---------|----------|-------|
| **Website video** | VideoObject, sitemap, thumbnail | This skill |
| **YouTube** | Title, description, chapters, thumbnail | See **youtube-seo** |
| **GEO / AI citation** | YouTube distribution; long-form | See **generative-engine-optimization** |
| **Featured Snippet (video)** | Video schema; timestamps | See **featured-snippet** |

---

## Related Skills

- **youtube-seo**: YouTube titles, descriptions, thumbnails, chapters
- **schema-markup**: VideoObject, BroadcastEvent; rich results
- **serp-features**: Video SERP feature; rich results
- **featured-snippet**: Video snippet format
- **xml-sitemap**: Video sitemap extension
- **google-search-console**: Video indexing report; Video rich results

---
name: url-structure
description: When the user wants to optimize URL structure, fix URL issues, or plan URL hierarchy. Also use when the user mentions "URL structure," "URL optimization," "slug," "clean URLs," "URL hierarchy," "URL path," "permalink structure," "URL best practices," "dynamic URLs," or "URL parameters." For per-page slug wording, use url-slug-generator. For canonical consolidation, use canonical-tag.
metadata:
  version: 1.1.0
---

# SEO On-Page: URL Structure

Guides URL structure optimization for SEO: readability, hierarchy, and best practices.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (On-Page SEO)

- **URL hierarchy**: Path structure, categories, depth
- **URL format**: Static vs dynamic; omit file extensions
- **URL slug**: See **url-slug-generator** for slug creation (3–5 words, under 60 chars)
- **Duplicate variants**: See **canonical-tag** for HTTPS, www, trailing slash

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site structure.

Identify:
1. **Site structure**: Categories, subcategories, content types
2. **Current URLs**: Existing patterns and issues
3. **Multi-language**: URL structure for zh/en (e.g., /zh/, /en/ or subdomains)

## Best Practices

### URL Guidelines

| Principle | Guideline |
|-----------|-----------|
| **Readable** | Use words, not IDs; `/blog/seo-guide` not `/p/12345` |
| **Short** | Shorter is generally better; avoid unnecessary depth |
| **Keyword** | Include target keyword when natural |
| **Lowercase** | Use lowercase; avoid mixed case |
| **Hyphens** | Use hyphens to separate words: `seo-guide` |
| **Avoid** | Special chars, query params for core content, session IDs |

### Hierarchy

| Pattern | Example | Use |
|---------|---------|-----|
| **Flat** | `/page-name` | Simple sites |
| **Category** | `/blog/post-name`, `/tools/tool-name` | Content sites |
| **Nested** | `/category/subcategory/page` | Deep hierarchies (keep shallow) |

### Multi-language

| Pattern | Example |
|---------|---------|
| **Path prefix** | `/zh/page`, `/en/page` |
| **Subdomain** | `zh.example.com`, `en.example.com` |
| **ccTLD** | `example.cn`, `example.com` |

### Static vs Dynamic vs Pseudo-Static URLs

| Type | Example | Use |
|------|---------|-----|
| **Static** | `/blog/seo-guide` | Direct file; best SEO; content stable |
| **Dynamic** | `/product?id=123` | Program-generated; avoid for indexable content |
| **Pseudo-static** | `/blog/seo-guide` (rewritten from `.php`) | Combines both; common in CMS |
| **Rule** | Prefer static or pseudo-static; if dynamic, keep params ≤2; use **canonical-tag** and **robots-txt** (Clean-param) |

### File Extensions

- **Omit** `.html`, `.php`, `.aspx` — keeps URLs technology-agnostic, shorter, easier to refactor
- **Example**: `/seo-guide` not `/seo-guide.html`

### URL Parameter Handling

| Scenario | Approach |
|----------|----------|
| **UTM / tracking** | Canonical to base URL; params in query string only |
| **Search results** | Canonical to search page; avoid indexing result URLs |
| **Filters / sort** | Canonical to base; or **robots-txt** Clean-param |
| **Session IDs** | Use cookies; never in indexable URLs |

### Use Cases

| Scenario | Focus |
|----------|-------|
| **New site** | Plan hierarchy upfront; avoid later restructuring |
| **Migration** | 301 mapping; canonical; see **canonical-tag** |
| **Large site** | Dynamic URLs, params, multi-language — canonical + robots |
| **SEO audit** | Check structure, params, canonical consistency |

## Common Issues

| Issue | Fix |
|-------|-----|
| Long URLs | Shorten; remove redundant words |
| Dynamic params | Use canonical; clean params in robots (Yandex Clean-param) |
| Mixed case | Redirect to lowercase |
| Changed URLs | 301 redirect old to new |

## Output Format

- **URL structure** recommendation
- **Slug** conventions
- **Hierarchy** for key content types
- **Redirect** plan if changing URLs
- **References**: [Alignify URL optimization](https://alignify.co/zh/seo/url-optimization); [Google URL guidelines](https://developers.google.com/search/docs/crawling-indexing/url-structure)

## Related Skills

- **website-structure**: Plan structure and URL paths; apply url-structure rules after structure is defined

- **canonical-tag**: HTTPS, www, trailing slash — handles duplicate URL variants
- **url-slug-generator**: Slug creation for content pages; length, keywords, format
- **category-page-generator**: E-commerce category URL hierarchy, faceted URLs
- **products-page-generator**: Product URL hierarchy
- **services-page-generator**: Service URL hierarchy
- **robots-txt**: Clean-param for query params
- **internal-links**: URL structure affects link patterns

---
name: twitter-cards
description: When the user wants to add or optimize Twitter Card metadata for X (Twitter) link previews. Also use when the user mentions "Twitter Card," "twitter:card," "twitter:image," "twitter:title," "X preview," or "tweet preview." For Facebook/LinkedIn previews, use open-graph.
metadata:
  version: 1.1.0
---

# SEO On-Page: Twitter Cards

Guides implementation of Twitter Card meta tags for X (Twitter) link previews. Twitter falls back to Open Graph if Twitter-specific tags are missing; add both for best results.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Social Sharing)

- **Twitter Cards**: X-specific meta tags; control how links appear when shared on X/Twitter

## Card Types

| Type | Use case |
|------|----------|
| **summary** | Small card with thumbnail |
| **summary_large_image** | Large prominent image (recommended; 1200×675px) |
| **app** | Mobile app promotion |
| **player** | Video/audio content |

## Recommended Tags (summary_large_image)

```html
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Your Title">
<meta name="twitter:description" content="Your description">
<meta name="twitter:image" content="https://example.com/image.jpg">
<meta name="twitter:site" content="@yourusername">
<meta name="twitter:creator" content="@authorusername">
<meta name="twitter:image:alt" content="Alt text for image">
```

| Tag | Guideline |
|-----|-----------|
| **twitter:card** | Required; `summary_large_image` for most pages |
| **twitter:title** | Max 70 chars; concise title |
| **twitter:description** | Max 200 chars; summary |
| **twitter:image** | Absolute URL; unique per page |
| **twitter:site** | @username of website |
| **twitter:creator** | @username of content creator |
| **twitter:image:alt** | Alt text; max 420 chars; accessibility |

## Image Requirements

| Item | Guideline |
|------|-----------|
| **Aspect ratio** | 2:1 |
| **Minimum** | 300×157 px |
| **Recommended** | 1200×675 px |
| **Max** | 4096×4096 px |
| **File size** | Under 5MB |
| **Formats** | JPG, PNG, WebP, GIF (first frame only); SVG not supported |

## Common Mistakes

- Missing Twitter Card tags (Twitter won't display images properly without them)
- Using relative image URLs instead of absolute https://
- Images too small or wrong aspect ratio
- Title/description too long (gets truncated)

## Implementation

### Next.js (App Router)

```tsx
export const metadata = {
  twitter: {
    card: 'summary_large_image',
    title: '...',
    description: '...',
    images: ['https://example.com/twitter.jpg'],
    site: '@yourusername',
    creator: '@authorusername',
  },
};
```

### HTML (generic)

```html
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="Your Title">
<meta name="twitter:description" content="Your description">
<meta name="twitter:image" content="https://example.com/image.jpg">
<meta name="twitter:site" content="@yourusername">
<meta name="twitter:image:alt" content="Alt text">
```

## Testing

- **X (Twitter)**: [Card Validator](https://cards-dev.twitter.com/validator)

## Related Skills

- **social-share-generator**: Share buttons use Twitter Cards for X previews when users share; Cards must be set for share buttons to show proper previews
- **open-graph**: OG tags; Twitter falls back to OG if Twitter tags missing
- **title-tag**: Title tag often mirrors twitter:title
- **meta-description**: Meta description often mirrors twitter:description
- **page-metadata**: Hreflang, other meta tags
- **twitter-x-posts**: X post copy and engagement (different from link previews)

---
name: title-tag
description: When the user wants to optimize the title tag, page title, or SERP title. Also use when the user mentions "title tag," "meta title," "page title," "SEO title," "SERP title," "browser tab title," "title optimization," "headline for search," "title too long," "title tag length," "duplicate title tags," or "optimize title for CTR." For meta description, use meta-description. For structured data, use schema-markup.
metadata:
  version: 1.4.0
---

# SEO On-Page: Title Tag

Guides optimization of the HTML title tag for search engines and SERP display.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (On-Page SEO)

- **Title tag**: Primary search snippet; primary keyword near start; unique per page

## Length by Language

Google truncates by **pixel width** (~580–600px desktop), not character count. Character limits are approximate—CJK chars are wider (~2× Latin), so fewer fit in the same pixels.

| Script / Language | Title (chars) | Notes |
|-------------------|---------------|-------|
| **Latin** (English, Spanish, French, etc.) | 50–60 | ~55 recommended |
| **CJK** (Chinese, Japanese, Korean) | 25–35 | Full-width chars; 25–30 desktop; 20–28 mobile; use pixel checker when available |
| **Cyrillic** (Russian, etc.) | 50–55 | Slightly wider than Latin |
| **Arabic, Hebrew** | 30–40 | RTL; variable width |

**Pixel tools**: Use a pixel-accurate checker for CJK—font and locale affect display.

**Multilingual**: Use locale-specific limits; don't translate then truncate. See **localization-strategy**, **translation**.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for brand voice and target keywords.

Identify:
1. **Page type**: Homepage, landing, blog, product, etc.
2. **Primary keyword**: Target search query
3. **Language / script**: Apply length rule above
4. **Brand**: Optional brand append at end

## Best Practices

| Item | Guideline |
|------|-----------|
| **Length** | Per language (see table above); Google truncates beyond ~600px |
| **Front-load** | Main phrase first; branding at end |
| **Keyword** | Include primary keyword near the start |
| **Unique** | One unique title per page |
| **Clarity** | Match search intent; avoid keyword stuffing |
| **Engagement** | Numbers, power words, questions can boost CTR ~36% |
| **H1 alignment** | H1 should align with title; Google may rewrite titles if they mismatch content or intent |

**Example**: Bad: "SEO Tips for Small Business" → Better: "11 SEO Tips That Actually Work (2026)"

## Output Format

- **Recommended title** (with character count for target language)
- **Alternatives** (if A/B testing)

## GSC-Driven Optimization

For pages with low CTR despite good position, use google-search-console to identify opportunities. Compare actual CTR vs expected by position; optimize title for pages with CTR gap.

## Related Skills

- **google-search-console**: CTR analysis, identify low-CTR pages for title optimization
- **meta-description**: Meta description pairs with title in SERP
- **localization-strategy, translation**: Multilingual metadata; locale-specific length
- **serp-features**: SERP features; standard result appearance in context
- **heading-structure**: H1 should align with title tag
- **open-graph**: og:title for social sharing (often mirrors title)
- **schema-markup**: Structured data complements metadata

---
name: serp-features
description: When the user wants to understand or optimize for SERP feature types (PAA, sitelinks, rich results, AI Overviews). Also use when the user mentions "SERP," "SERP features," "search result features," "People Also Ask," "PAA," "sitelinks," "knowledge panel," "local pack," "rich results," "zero-click," "SERP types," "AI Overviews," "Bing Copilot," or "Yandex AI." For JSON-LD and rich result implementation, use schema-markup. For organic strategy and roadmap, use seo-strategy.
metadata:
  version: 1.1.0
---

# SEO On-Page: SERP Features

Guides SERP (Search Engine Results Page) features: types, obtainability, and optimization. ~98.5% of Google's first page includes SERP features; rich results receive ~58% of clicks vs 41% for standard listings. Understanding SERP features helps prioritize keywords and content strategy.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope

- **SERP feature types**: Organic enhancements, universal results, paid, knowledge
- **Obtainability**: Which features are achievable; which require authority/partnerships
- **Optimization**: Content, schema, and structure for each feature type
- **Impact**: CTR, zero-click, traffic implications

## What Is a SERP Feature?

A **SERP feature** is any result on a search results page that is **not** a traditional organic blue link. Features provide quick answers, visual enhancements, or alternative result types (images, local, news, etc.).

## Rich Results vs Featured Snippets

| Dimension | Rich Results | Featured Snippets |
|-----------|--------------|-------------------|
| **Location** | Within standard organic listings; enhance a blue link | Above organic results; "position zero" |
| **Generation** | Structured data (Schema/JSON-LD) added by site owner | Google extracts from page content; no schema required |
| **Display** | Star ratings, prices, images, breadcrumbs, FAQ dropdowns | Extracted text in highlighted box; paragraph, list, table, or video |
| **Ranking** | Do not require high organic rank to appear | Page must rank in top ~10 for the query |
| **Industry** | Often content-specific (recipes, products, events, reviews) | Versatile; most industries |
| **CTR** | Typically increase CTR (up to ~35%); enhanced visibility | Can increase or reduce clicks (zero-click when answer suffices) |

**Rich results** = schema-powered enhancements to regular listings. **Featured snippets** = Google-extracted answer boxes at position zero. Both are SERP features; rich results are a subset driven by structured data. [Onely](https://www.onely.com/blog/difference-between-featured-snippets-and-rich-results-explained/), [Seranking](https://seranking.com/blog/rich-snippets/)

## SERP Features ↔ Schema ↔ Rich Results (Strongly Related)

**SERP features, schema, and rich results are strongly related.** Most achievable SERP enhancements depend on or benefit from Schema.org structured data. Schema makes content machine-readable so search engines can extract and display rich results.

| SERP Feature | Schema Type | Relationship |
|--------------|-------------|--------------|
| **PAA / FAQ dropdown** | FAQPage | Required or strongly recommended; FAQ schema triggers PAA-style display |
| **Breadcrumbs** | BreadcrumbList | Required; no schema = no breadcrumb rich result |
| **Reviews / Stars** | AggregateRating, Review | Required; star display depends on review schema |
| **Featured Snippet** | FAQPage, HowTo, Article | Supporting; schema helps identify extractable blocks; not required |
| **Sitelinks** | WebSite + SearchAction | Supporting; SearchAction can enable sitelinks |
| **Video** | VideoObject | Required; video thumbnail; Google prioritizes YouTube. See **video-optimization** |
| **Product** | Product, Offer | Required; shopping results |
| **Recipe** | Recipe | Required; recipe rich result |
| **Job** | JobPosting | Required; Google Jobs |
| **Event** | Event | Required; event rich result |
| **In-Depth Articles** | Article + author | Supporting; Article schema, authorship |

**Workflow**: When targeting a SERP feature, check **schema-markup** for the schema type; after implementing schema, use **serp-features** to assess display and optimization.

## SERP Feature Categories

### 1. Organic Enhancements (Achievable)

| Feature | Description | Obtainability |
|---------|-------------|----------------|
| **Featured Snippet** | Direct answer above organic results; paragraph, list, or table | Content that answers query in 40–60 words; positions 2–5 often win. See **featured-snippet** |
| **People Also Ask (PAA)** | Expandable question boxes with brief answers | FAQ-style content; FAQ schema; match question phrasing |
| **Sitelinks** | Additional links below main result (brand queries) | Site structure, internal links, SearchAction schema; mainly branded |
| **Reviews / Stars** | Star ratings on product/service results | Review schema (AggregateRating); eligibility varies by vertical |
| **Breadcrumbs** | Path shown in result | BreadcrumbList schema; clear site structure |
| **Video** | Video thumbnail in results | Video schema; **Google prioritizes YouTube**; see **video-optimization** |
| **Image Pack** | Horizontal row of images | Alt, captions, file names, responsive; see **image-optimization** |

### 2. Universal Results

| Feature | Description | Obtainability |
|---------|-------------|----------------|
| **News Box** | Time-sensitive news block | Google News inclusion; publisher eligibility |
| **In-Depth Articles** | Long-form block (broad terms) | Large publishers; 2000–5000 words; authorship, Article schema |
| **Tweet** | Twitter results in SERP | Brand presence; not directly controllable |
| **Shopping** | Product listings with images/price | Paid (PLAs) or Product schema for organic |

### 3. Knowledge / Entity (Limited Obtainability)

| Feature | Description | Obtainability |
|---------|-------------|----------------|
| **Knowledge Panel** | Entity info (brand, person, place) | WikiData, partnerships; see **entity-seo** |
| **Knowledge Card** | Top-of-SERP semantic answer | Same as Knowledge Panel |
| **Local Pack** | 3 local business results + map | Local SEO; GMB, NAP, reviews |
| **Local Teaser** | Hotels, restaurants with map/sort | Local SEO |

### 4. Paid

| Feature | Description |
|---------|-------------|
| **AdWords (Top/Bottom)** | Sponsored results; [Ad] label |
| **Shopping (PLAs)** | Product ads with images |
| **Google Flights** | Flight search in SERP |

### 5. AI Search Summaries (SERP Feature)

AI-generated answer blocks at the top of search results. These are **SERP features**—they occupy prime SERP real estate and replace or supplement traditional blue links. Optimize via **generative-engine-optimization** (GEO).

| Engine | Feature | Description | Availability |
|--------|---------|-------------|--------------|
| **Google** | AI Overviews | Multi-source AI summary at top; Gemini; cites top 10–12 organic results; 2–3 paragraphs or bullets | ~47% US searches; opt-in/experimental in 120+ countries |
| **Bing** | Copilot Search | Curated summaries with cited sources; GPT-4; grouped answers with resources per section; follow-up questions in-search | bing.com/copilotsearch; Edge; standard across Bing |
| **Yandex** | Search with Yandex AI / Neuro | YandexGPT synthesizes from real-time search; cited sources; conversational follow-ups; image upload; Russia-focused | Yandex Browser, Yandex app; Russia location |
| **Perplexity** | — | Standalone AI search; not a SERP feature; 200B+ URL index; live web search | perplexity.ai |
| **ChatGPT** | — | Web search via GPTbot; not a SERP feature; high-authority, LLM-friendly content | chat.openai.com |

**Source selection**: Google pulls from top organic; Bing uses Bing index (9.81% domain overlap with Google); Yandex uses real-time search; Perplexity has independent crawl. AI Overview citations can drive 20–35% higher CTR than equivalent organic positions. [SEJ](https://searchengineland.com/microsoft-officially-launches-copilot-search-in-bing-453958), [Yandex](https://yandex.com/support/search/en/yandex-ai), [Geneo](https://geneo.app/blog/chatgpt-vs-perplexity-vs-google-ai-overview-geo-comparison/)

### 6. Other Newer (2025+)

| Feature | Description |
|---------|-------------|
| **Related Searches** | Alternative queries at bottom |
| **People Also Search For (PASF)** | Related queries after user bounces from result; 6-8 suggestions; different from PAA; comprehensive content reduces bounce. See **faq-page-generator** |

## Optimization by Feature

| Feature | Key Actions |
|---------|-------------|
| **Featured Snippet** | Answer-first (40–60 words); H2/H3; semantic lists/tables. See **featured-snippet** |
| **PAA** | FAQ content; FAQ schema; natural question phrasing; **faq-page-generator** |
| **Sitelinks** | Clear site structure; internal links; SearchAction; **website-structure** |
| **Reviews** | AggregateRating schema; **schema-markup** |
| **Breadcrumbs** | BreadcrumbList schema; **breadcrumb-generator** |
| **Video** | VideoObject schema; **video-optimization**; Google prioritizes YouTube |
| **Image Pack** | Alt, captions, file names, responsive; see **image-optimization** |
| **Local Pack** | Local SEO; GMB; NAP consistency |
| **AI Overview / Copilot / Yandex AI** | GEO; structured content; citable paragraphs; entity signals; see **generative-engine-optimization**, **entity-seo** |

## Zero-Click: SERP Features That Satisfy Intent Without a Click

**Zero-click** = user gets the answer directly on the SERP and does not click through to any website. SERP features are a major driver of zero-click—they answer queries in-place, reducing organic traffic to publishers.

### SERP Features That Cause Zero-Click

| Feature | Zero-Click Risk | Why |
|---------|-----------------|-----|
| **Featured Snippet** | High | Direct answer in position zero; user may not need to visit |
| **People Also Ask (PAA)** | High | Expandable answers; full answer visible without click |
| **AI Overviews** | Very high | ~83% of searches with AI Overview may end without click |
| **Bing Copilot / Yandex AI** | Very high | Full AI summary with sources; answer in-place |
| **Knowledge Panel / Card** | High | Entity info; no click needed for simple facts |
| **Rich results** (reviews, recipe) | Medium | Can reduce clicks when answer is complete (e.g. recipe steps) |

### Implications

- **Traffic**: Expect lower organic clicks when zero-click features dominate the SERP
- **Strategy**: Prioritize **citation** over click—being cited in AI Overview, Featured Snippet, or PAA still delivers brand visibility and trust
- **GEO**: Optimize for citation (see **generative-engine-optimization**) so your content is used even when users don't click
- **Keyword research**: Screen keywords for zero-click SERP features; adjust traffic forecasts and prioritize commercial/transactional queries where clicks matter more

### When Zero-Click Matters Most

- Informational queries ("what is X," "how to Y")—highest zero-click
- Commercial/transactional—users often need to visit (compare, buy)
- Brand queries—sitelinks and Knowledge Panel can still drive clicks to specific pages

## SERP Analysis for Strategy

- **SERP check**: Search target keyword—observe which features appear
- **Intent signals**: Knowledge card → informational; product lists → commercial; brand → navigational
- **Zero-click assessment**: Identify features that satisfy intent without click; factor into traffic expectations
- **Keyword research**: **keyword-research** uses SERP features (Featured Snippet, PAA, zero-click) in screening

## Rich Results: Types & Impact

**Rich results** are enhanced search listings powered by structured data. They appear *within* organic positions (unlike Featured Snippets at position zero). High-impact types: Product, Review snippets, HowTo (desktop), Article/News, Video, Recipe, LocalBusiness, Event, Breadcrumb, Sitelinks searchbox, JobPosting. Limited/context-dependent: HowTo (mobile), FAQ (restricted to government/health for many sites), Education Q&A, Course, SoftwareApplication. [AISO Hub](https://aiso-hub.com/insights/google-rich-results-types/)

Rich results do not directly boost rankings but can increase CTR by up to 35%. They also make content machine-readable for AI Overviews, Gemini, Copilot, and Perplexity. Validate with [Google Rich Results Test](https://search.google.com/test/rich-results).

## CTR Impact

- **Zero-click trade-off**: SERP features can increase CTR (rich results, sitelinks) or reduce it (Featured Snippet, PAA, AI Overviews when answer suffices). See Zero-Click section above.
- Rich results: ~58% of clicks vs 41% for standard listings
- Featured snippets: ~42.9% CTR boost; position zero ~35% of clicks when present
- Review stars: Higher CTR
- Sitelinks: Dominate SERP for brand queries; faster path to target page

## Output Format

- **SERP features** present for target keyword
- **Zero-click** assessment (which features satisfy intent without click)
- **Obtainability** assessment
- **Optimization** priorities (schema, content, structure; citation vs click)
- **Related** skills for each feature

## Related Skills

- **schema-markup**: **Strongly related**—schema type maps to SERP feature; see mapping table above
- **featured-snippet**: Featured Snippet / Position Zero optimization
- **faq-page-generator**: PAA optimization; FAQ format
- **keyword-research**: SERP features in keyword screening
- **website-structure**: Sitelinks; site architecture
- **generative-engine-optimization**: AI Overviews, Bing Copilot, Yandex AI; GEO strategy
- **image-optimization**: Image Pack; alt, captions, file names
- **video-optimization**: Video SEO; VideoObject; YouTube prioritization
- **entity-seo**: Knowledge Panel; Organization, Person schema

---
name: schema-markup
description: When the user wants to add or optimize structured data (Schema.org, JSON-LD). Also use when the user mentions "schema," "structured data," "JSON-LD," "rich results," "rich snippets," "Google rich snippets," "featured snippet schema," "add schema to page," "missing structured data," "schema validation error," "Schema Markup Validator," "Google Rich Results Test," "FAQ schema," "Article schema," "Organization schema," "JobPosting," "HowTo," "Event," "SoftwareApplication," "BreadcrumbList," "WebSite," "Recipe," "Product," or "Dataset." For SERP feature types and zero-click patterns, use serp-features. For AI search visibility strategy (not markup), use generative-engine-optimization.
metadata:
  version: 1.4.0
---

# SEO On-Page: Schema / Structured Data

Guides implementation of Schema.org structured data (JSON-LD) for rich snippets, enhanced search results, and Generative Engine Optimization (GEO).

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (On-Page SEO)

- **Schema markup**: Schema.org types for rich results, AI search visibility, and machine-readable content
- **Schema.org vs. search engines**: Schema.org defines 800+ types; each search engine supports only a subset for rich results

## Schema.org vs. Search Engine Support

**Schema.org and Google Structured Data are not fully aligned.** Schema.org is an open vocabulary (800+ types); Google, Bing, and other engines each support only a curated subset for rich results.

| Engine | Support | Notes |
|--------|---------|-------|
| **Google** | Subset only | Only types in [Google's search gallery](https://developers.google.com/search/docs/guides/search-gallery) generate rich results. Valid Schema.org markup not in Google's list won't produce enhanced snippets—even if technically correct. |
| **Bing** | Subset; different | Supports JSON-LD, Microdata, RDFa, Open Graph. Some types (e.g., Product, Offer) have format-specific support. Check [Bing Webmaster docs](https://www.bing.com/webmasters/help/marking-up-your-site-with-structured-data-3a93e731). |
| **Other engines** | Varies | Yandex, DuckDuckGo, AI search tools (Perplexity, etc.) may use Schema.org for understanding even when they don't display rich results. |

**Practical implication**: Implement Schema.org markup for your content type. If Google doesn't show rich results for that type, Bing or AI systems may still use it. Always verify against [Google's developer docs](https://developers.google.com/search/docs) for Google-specific rich result eligibility.

## Rich Results: Google Support (2025)

**High-impact types**: Product, Review snippets, HowTo (desktop), Article/News, Video, Recipe, LocalBusiness, Event, Breadcrumb, Sitelinks searchbox, JobPosting.

**Limited or context-dependent**: HowTo (mobile), FAQ (government/health sites for many queries), Education Q&A, Course, SoftwareApplication, Speakable (news), DiscussionForumPosting.

**Deprecated**: COVID data panels, some AMP-only formats, data-vocabulary.org.

**Implementation**: JSON-LD preferred; include `@context`, `@type`, stable `@id`; ISO 8601 dates; match structured data to visible content. Validate with [Rich Results Test](https://search.google.com/test/rich-results). Rich results can increase CTR up to ~35% and improve AI citation. [AISO Hub](https://aiso-hub.com/insights/google-rich-results-types/), [Digital Applied](https://www.digitalapplied.com/blog/structured-data-seo-2026-rich-results-guide)

## Schema ↔ SERP Features ↔ Rich Results (Strongly Related)

**Schema, SERP features, and rich results are strongly related.** Schema is the **necessary condition** for most rich results. When targeting a SERP feature, implement the corresponding schema type. See **serp-features** for the full SERP feature list and optimization.

### Rich Results vs Featured Snippets

- **Rich results**: Schema-powered enhancements to standard listings (stars, breadcrumbs, FAQ dropdowns, product info). Appear within organic positions; do not require top-10 rank.
- **Featured snippets**: Google-extracted answer boxes at position zero. No schema required; content structure matters. Schema (FAQPage, HowTo, Article) can support extraction.

| Schema Type | SERP Feature / Rich Result | Notes |
|-------------|----------------------------|-------|
| **FAQPage** | PAA, Featured Snippet | FAQ dropdown; Q&A-style snippet. Eligibility restricted for many sites (e.g. government/health) |
| **BreadcrumbList** | Breadcrumbs | Path display in result |
| **AggregateRating, Review** | Reviews / Stars | Star ratings |
| **HowTo** | Featured Snippet (list) | Step-based snippet; desktop support; mobile may be limited |
| **Article** | In-Depth Articles, Snippet | Article rich result |
| **VideoObject** | Video | Video thumbnail; see **video-optimization** |
| **Product, Offer** | Shopping, Product | Product/shopping results |
| **Recipe** | Recipe | Recipe rich result |
| **JobPosting** | Google Jobs | Job listings |
| **Event** | Event | Event rich result |
| **WebSite + SearchAction** | Sitelinks searchbox | Site links for brand queries |
| **Organization, Person** | Knowledge Panel | Entity info; see **entity-seo** |

**Workflow**: 1) Use **serp-features** to identify target SERP feature; 2) Look up schema type in this table; 3) Implement and validate with Rich Results Test.

## Generative Engine Optimization (GEO)

**GEO** = optimizing content so AI systems (Google AI Overviews, Perplexity, ChatGPT, Gemini) choose, cite, and quote your content in generated answers. Structured data makes content machine-readable; AI engines extract and cite more accurately. Key schema types for GEO: Organization, Person/Author, WebSite, WebPage, FAQPage, HowTo, Article, Product, AggregateRating. See **generative-engine-optimization** for full GEO strategy.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for product type and content.

Identify:
1. **Page type**: Article, Product, FAQ, Organization, JobPosting, Event, etc.
2. **Content**: What entities to describe
3. **Goal**: Rich snippets, AI Overview visibility, Knowledge Panel

## Schema Type Classification

### Core Types (General Use)

| Type | Use case |
|------|----------|
| **Organization** | Site-wide; company info, logo, sameAs; see placement below |
| **WebSite** | Site-wide; search action, site name; pair with Organization on homepage |
| **Article** | Blog posts, news, tool intros |
| **BreadcrumbList** | Breadcrumb navigation |
| **FAQPage** | FAQ sections; triggers PAA-style results |
| **Person** | Author info; pairs with Article |
| **ImageObject** | Image metadata for rich results |
| **HowTo** | Tutorials, step-by-step guides. **Note**: Google may have deprecated HowTo rich results (2023–2024); Schema.org still supports it; Bing/AI may use it |

### Exclusive Types (Specific Scenarios)

| Type | Use case |
|------|----------|
| **JobPosting** | Recruitment sites, AI Job Matching |
| **Product** | E-commerce product pages |
| **Event** | Event pages, ticketing (not general blogs) |
| **SoftwareApplication** | App pages, tool pages |
| **LocalBusiness** | Local business pages |
| **Dataset** | Data platforms, datasets |
| **DiscussionForumPosting** | Forums, community posts |
| **Quiz** | Education, flashcards |
| **MathSolver** | Math tools |
| **CaseStudy** | Case study pages |
| **Recipe** | Recipes, meal plans, cooking instructions |

**Rule**: Use core types for most sites. Use exclusive types only when page content matches (e.g., don't use Event on a blog; don't use JobPosting on a product page).

### Organization & WebSite Schema Placement

| Where | Organization | WebSite | Notes |
|-------|--------------|---------|-------|
| **Homepage** | Minimum | Minimum | Add both Organization and WebSite to homepage at least. Organization describes the entity that owns the site; WebSite enables sitelinks searchbox and site identity. |
| **Root layout / global** | Optimal | Optimal | Place in site-wide layout (e.g. `layout.tsx`, `_document`, global header/footer) so schema appears on every page. Google uses the first instance found; one instance per site is sufficient. |
| **About page** | No | No | About page uses **AboutPage** schema (page-specific: headline, description, author, about). Organization is entity-level, not page-level—do not confine it to About. See **about-page-generator**. |

**Implementation**: JSON-LD in `<head>`; use `@id` (e.g. `https://example.com/#organization`) to link Organization ↔ WebSite ↔ WebPage for entity graph. See **entity-seo** for @id and Knowledge Panel.

## Action: Website/Product Type → Schema Mapping

**Use this table to recommend which exclusive schema types fit a site.** Match the site's content and product type to the most relevant schema. When in doubt, start with core types (Organization, WebSite, Article); add exclusive types only when content clearly matches.

| Website / Product type | Recommended exclusive schema | Why |
|------------------------|------------------------------|-----|
| **AI meal planner, recipe site, food blog, cooking app** | **Recipe** | Ingredients, instructions, cook time, servings—highly relevant for food/meal content. Google supports Recipe rich results. |
| **Job board, recruitment site, careers page** | **JobPosting** | Title, company, location, salary, employment type. Required for Google Jobs. |
| **Event platform, ticketing, webinar, conference** | **Event** | Date, location, price. Use only on actual event pages. |
| **SaaS, app, Chrome extension, tool, software product page** | **SoftwareApplication** | App name, category, rating, price, OS. Fits product/feature pages. |
| **E-commerce product page** | **Product** | Price, availability, brand, reviews. Use with Offer, AggregateRating. |
| **Forum, community, Reddit-style, Q&A** | **DiscussionForumPosting** | Post content, author, comments. For user-generated discussion. |
| **Data platform, dataset repository, Scale AI / Surge AI** | **Dataset** | Dataset name, creator, license, distribution format. For data catalog pages. |
| **Education site, flashcards, Quizlet-style** | **Quiz** | Question-answer pairs. For educational Q&A content. |
| **Math solver, calculator, equation tool** | **MathSolver** | Math problem input, solution output. For math tools. |
| **Restaurant, local service, store locator** | **LocalBusiness** | Address, hours, NAP. For local SEO. |
| **Case study, customer story page** | **CaseStudy** | Client, outcome, methodology. For B2B case studies. |
| **FAQ page, product FAQ, support FAQ** | **FAQPage** | Question + acceptedAnswer pairs. Triggers PAA-style results. |
| **Tutorial, how-to guide, step-by-step** | **HowTo** | Steps, tools, time. Note: Google may have deprecated rich results; Bing/AI may still use. |
| **News article, press release** | **NewsArticle** | Use instead of Article for news. |
| **Video page, podcast episode** | **VideoObject** / **PodcastEpisode** | For video/audio content. See **video-optimization** for VideoObject, thumbnail, key moments. |

**Examples:**
- **AI meal planner** (e.g., generates weekly meal plans with recipes) → Add **Recipe** schema to each recipe/meal page; **Article** or **WebPage** for landing pages
- **AI writing tool** → **SoftwareApplication** on product page; **Article** on blog
- **Recruitment SaaS** → **JobPosting** on job listing pages; **SoftwareApplication** on product page
- **Recipe blog** → **Recipe** on each recipe post; **Article** for non-recipe posts

**Output**: When recommending schema, state: (1) which exclusive types fit the site/product, (2) which page types get which schema, (3) core types to add site-wide (Organization, WebSite, BreadcrumbList).

### Article / BlogPosting / NewsArticle: Type Selection & Implementation

Choose the **most specific** type that matches content:

| Type | Use case |
|------|----------|
| **BlogPosting** | Informal blog posts; individual authors; regularly updated |
| **Article** | Formal, evergreen content; tool intros; encyclopedic |
| **NewsArticle** | Time-sensitive news; recognized publishers |

**Required properties**: headline (max 110 chars), image (min 1200px wide; absolute URL), datePublished (ISO 8601), author (Person or Organization), publisher (Organization with logo).

**Recommended**: dateModified, description, mainEntityOfPage (canonical URL).

**Date display for CTR**: Google recommends showing **only one date** on the page. If both datePublished and dateModified are visible, Google may pick the wrong date for SERP display—Search Engine Land saw ~22% CTR drop. Best practice: show dateModified if it exists, otherwise datePublished. Keep both in JSON-LD; the rule applies to **visible** date only.

**JSON-LD example** (BlogPosting):

```json
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "The Ultimate SEO Checklist for 2025",
  "description": "A complete guide to optimizing blog posts for search and AI.",
  "image": "https://example.com/image.jpg",
  "datePublished": "2025-01-15T09:00:00Z",
  "dateModified": "2025-02-01T14:30:00Z",
  "author": { "@type": "Person", "name": "Jane Doe", "url": "https://example.com/author/jane" },
  "publisher": { "@type": "Organization", "name": "Example", "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" } }
}
```

Place in `<head>` via `<script type="application/ld+json">`. For article pages, use `og:type: article` with og:article:published_time, og:article:modified_time, og:article:author. See **article-page-generator**, **open-graph**.

### BreadcrumbList

For breadcrumb navigation. Schema must match visible breadcrumbs exactly. See **breadcrumb-generator** for UI, placement, and semantic HTML.

| Requirement | Guideline |
|-------------|-----------|
| **Format** | JSON-LD in `<script type="application/ld+json">` |
| **URLs** | Absolute URLs with https:// for each item |
| **Position** | Sequential integers starting from 1 |
| **Match** | Schema must match visible breadcrumbs exactly |

**JSON-LD example**:

```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://example.com/" },
    { "@type": "ListItem", "position": 2, "name": "Category", "item": "https://example.com/category/" },
    { "@type": "ListItem", "position": 3, "name": "Current Page", "item": "https://example.com/category/current-page/" }
  ]
}
```

**Multiple paths**: Google supports multiple BreadcrumbList objects on the same page when a page is reachable via multiple paths (e.g., product in multiple categories). Use an array of BreadcrumbList objects.

## Best Practices

| Principle | Guideline |
|-----------|-----------|
| **Accuracy** | Data must match visible page content; never add invisible or misleading data |
| **Completeness** | Include all required properties per type |
| **Most specific type** | Use NewsArticle over Article when applicable |
| **JSON-LD** | Preferred format; place in `<script type="application/ld+json">` |
| **@id for entities** | Use @id for Organization, Person to enable entity linking; see **entity-seo** |
| **Phased implementation** | Add required properties first; then optional for optimization |
| **Validation** | Test with Rich Results Test and Schema Markup Validator |
| **inLanguage (multilingual)** | Add `"inLanguage": "en-US"` (IETF BCP 47) to match hreflang; localize names, descriptions, FAQs for rich snippets per locale |

### Multilingual Schema (inLanguage)

For multilingual sites, add `inLanguage` to JSON-LD to reinforce language targeting. Align with hreflang values (e.g. `"inLanguage": "zh-CN"` with `hreflang="zh-CN"`).

**Localize schema data**: Translate structured data fields (name, description, FAQ acceptedAnswer, etc.) for each locale to improve rich snippet CTR in that language.

**Types that support inLanguage**: Article, BlogPosting, WebApplication, FAQPage, HowTo, Product, Organization.

## Implementation Workflow

1. **Analyze** page type and content; choose matching Schema type
2. **Select format** — JSON-LD recommended (Google, Bing, AI tools support it)
3. **Write** structured data; start with required properties
4. **Validate** with [Rich Results Test](https://search.google.com/test/rich-results), [Schema Markup Validator](https://validator.schema.org/)
5. **Deploy and monitor** via Search Console enhanced reports

## Common Errors and Fixes

| Error | Fix |
|-------|-----|
| **Data doesn't match visible content** | Schema must describe only what users see |
| **Missing required properties** | Check Google/Schema.org docs for each type |
| **Wrong type for page** | Don't use Event on non-event pages; don't use JobPosting on product pages |
| **Format/syntax errors** | Validate JSON-LD; check quotes, brackets, commas |
| **Over-markup** | Mark only relevant content; avoid stuffing unrelated types |

## Implementation

### Next.js (metadata)

```tsx
export const metadata = {
  other: {
    'script:ld+json': JSON.stringify({
      "@context": "https://schema.org",
      "@type": "Article",
      "headline": "...",
      "description": "...",
      "inLanguage": "en-US",
      "image": "https://example.com/image.jpg",
      "datePublished": "2024-01-01T00:00:00Z",
      "dateModified": "2024-01-15T00:00:00Z",
      "author": { "@type": "Person", "name": "..." },
      "publisher": { "@type": "Organization", "name": "...", "logo": { "@type": "ImageObject", "url": "..." } }
    }),
  },
};
```

### HTML (generic)

```html
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "...",
  "description": "...",
  "inLanguage": "en-US",
  "author": { "@type": "Person", "name": "..." },
  "publisher": { "@type": "Organization", "name": "...", "logo": { "@type": "ImageObject", "url": "..." } }
}
</script>
```

## Validation Tools

| Tool | Purpose |
|------|---------|
| [Google Rich Results Test](https://search.google.com/test/rich-results) | Check if Google can generate rich results |
| [Schema Markup Validator](https://validator.schema.org/) | Validate against Schema.org spec |
| Search Console | Enhanced reports; monitor validity over time |

## Output Format

- **Action first**: Use the Website/Product Type → Schema Mapping table to recommend which exclusive schema fits the site (e.g., AI meal planner → Recipe; SaaS tool → SoftwareApplication)
- **Schema type** recommendation (core vs. exclusive)
- **Page-level mapping**: Which pages get which schema
- **JSON-LD** structure with required properties
- **Validation** steps
- **References**: [Schema.org](https://schema.org/), [Google Structured Data](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data), [Bing Markup](https://www.bing.com/webmasters/help/marking-up-your-site-with-structured-data-3a93e731)

## Related Skills

- **article-page-generator**: Article structure; Article/BlogPosting/NewsArticle schema; date display
- **serp-features**: **Strongly related**—schema maps to SERP features; see mapping table above
- **faq-page-generator**: FAQPage schema; FAQ content structure
- **breadcrumb-generator**: BreadcrumbList schema implementation
- **featured-snippet**: FAQPage, HowTo for snippets
- **video-optimization**: VideoObject, video sitemap, thumbnail, key moments
- **entity-seo**: Organization, Person for entity recognition; @id; Knowledge Panel
- **homepage-generator**: Organization + WebSite schema on homepage or root layout
- **indexing**: Google Indexing API for JobPosting, BroadcastEvent

---
name: open-graph
description: When the user wants to add or optimize Open Graph metadata for social sharing. Also use when the user mentions "Open Graph," "og:tags," "og:title," "og:image," "og:description," "Facebook preview," "LinkedIn preview," or "social share preview." For X (Twitter) link previews, use twitter-cards. For SERP title/description, use title-tag and meta-description.
metadata:
  version: 1.1.0
---

# SEO On-Page: Open Graph

Guides implementation of Open Graph meta tags for social media previews (Facebook, LinkedIn, Slack, Discord, etc.). Pages with proper OG tags get 2–3× more clicks than bare URL links.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (Social Sharing)

- **Open Graph**: Facebook-originated protocol; controls preview card when links are shared on social platforms

## The 4 Essential Tags

Every shareable page requires these minimum tags:

```html
<meta property="og:title" content="Your Page Title">
<meta property="og:description" content="Your description">
<meta property="og:image" content="https://yourdomain.com/image.png">
<meta property="og:url" content="https://yourdomain.com/page">
```

| Tag | Guideline |
|-----|-----------|
| **og:title** | Keep under 60 chars; compelling; match page content |
| **og:description** | 150–200 chars; conversion-focused |
| **og:image** | Absolute URL (https://); 1200×630px recommended |
| **og:url** | Canonical URL; deduplicates shares |

## Recommended Additional Tags

| Tag | Purpose |
|-----|---------|
| **og:type** | Content type: `website`, `article`, `video`, `product` |
| **og:site_name** | Website name; displayed separately from title |
| **og:image:width** / **og:image:height** | Image dimensions (1200×630px) |
| **og:image:alt** | Alt text for accessibility |
| **og:locale** | Language/territory (e.g., `en_US`); for multilingual sites |

## Image Best Practices

| Item | Guideline |
|------|-----------|
| **Size** | 1200×630px (1.91:1 ratio) for Facebook, LinkedIn, WhatsApp |
| **Format** | JPG, PNG, WebP; under 5MB |
| **URL** | Absolute URL with https://; no relative paths |
| **Unique** | One unique image per page when possible |

## Common Mistakes

- Using relative image URLs instead of absolute https://
- Images too small or wrong aspect ratio
- Empty or placeholder values
- Missing og:url (canonical)

## Implementation

### Next.js (App Router)

```tsx
export const metadata = {
  openGraph: {
    title: '...',
    description: '...',
    url: 'https://example.com/page',
    siteName: 'Example',
    images: [{ url: 'https://example.com/og.jpg', width: 1200, height: 630, alt: '...' }],
    locale: 'en_US',
    type: 'website',
  },
};
```

### HTML (generic)

```html
<meta property="og:title" content="Your Title">
<meta property="og:description" content="Your description">
<meta property="og:image" content="https://example.com/og.jpg">
<meta property="og:url" content="https://example.com/page">
<meta property="og:type" content="website">
<meta property="og:site_name" content="Your Site">
<meta property="og:image:width" content="1200">
<meta property="og:image:height" content="630">
<meta property="og:image:alt" content="Alt text">
```

## Testing

- **Facebook**: [Sharing Debugger](https://developers.facebook.com/tools/debug/)
- **LinkedIn**: [Post Inspector](https://www.linkedin.com/post-inspector/)

## Related Skills

- **social-share-generator**: Share buttons use OG tags for rich previews when users share; OG must be set for share buttons to show proper cards
- **article-page-generator**: Use og:type `article` for article/post pages; article-specific tags (published_time, author)
- **page-metadata**: Hreflang, other meta tags
- **title-tag**: Title tag often mirrors og:title
- **meta-description**: Meta description often mirrors og:description
- **twitter-cards**: Twitter uses OG as fallback; add Twitter-specific tags for best results
- **canonical-tag**: og:url should match canonical URL

---
name: page-metadata
description: When the user wants to optimize meta tags other than title, description, Open Graph, or Twitter Cards. Also use when the user mentions "hreflang," "meta robots," "viewport," "charset," "canonical meta," "other meta tags," "meta robots noindex," "meta robots nofollow," "hreflang tags," "viewport meta," or "meta charset." For title tags, use title-tag. For meta descriptions, use meta-description. For Facebook/LinkedIn previews, use open-graph. For X previews, use twitter-cards.
metadata:
  version: 1.2.0
---

# SEO On-Page: Metadata (Other Meta Tags)

Guides optimization of meta tags beyond title, description, Open Graph, and Twitter Cards. Covers hreflang, robots, viewport, charset, and metadata completeness.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (On-Page SEO)

- **Hreflang**: Language/region targeting for multilingual sites
- **Meta robots**: index/noindex, follow/nofollow (page-level)
- **Viewport**: Mobile responsiveness
- **Charset**: Character encoding
- **Metadata completeness**: All pages have title + meta description (see **title-tag**, **meta-description**)

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for language/locale and indexing goals.

Identify:
1. **Multi-language**: zh, en, x-default if applicable
2. **Indexing**: Full index, noindex for specific pages
3. **Tech stack**: Next.js, HTML, etc.

## hreflang (Multi-language)

**Three non-negotiables**: (1) Self-referencing tags (each page links to itself), (2) Symmetric annotations (every version lists ALL others), (3) Valid ISO 639-1 or language-region codes (`en`, `en-US`, `zh-CN`).

**Implementation methods**: HTML `<link>` in head, XML sitemap (`xhtml:link`), or HTTP headers. For SPAs/JS-rendered pages, use sitemap-based hreflang as backup. See **rendering-strategies** for SSR/SSG/CSR.

**Canonical alignment**: Canonical URL must match the same regional version hreflang refers to. Misalignment causes Google to ignore hreflang.

**x-default**: Fallback for users whose language/location doesn't match any version. Point to default locale or language-selector page.

### Next.js (App Router)

```tsx
export const metadata = {
  alternates: {
    languages: {
      'en-US': '/en/page',
      'zh-CN': '/zh/page',
      'x-default': '/en/page',
    },
  },
};
```

### HTML (generic)

```html
<link rel="alternate" hreflang="en" href="https://example.com/en/page" />
<link rel="alternate" hreflang="zh" href="https://example.com/zh/page" />
<link rel="alternate" hreflang="x-default" href="https://example.com/en/page" />
```

### Common Mistakes (Avoid)

- Missing reciprocal references between language versions.
- Canonical tag conflicting with hreflang.
- Relying solely on machine translation without localization (see **translation**).
- Ignoring mobile—hreflang must appear on both desktop and mobile.
- Forgetting to update hreflang when page structure changes.

## Meta Robots (Page-level)

Page-level control for indexing and link following. See **indexing** for which page types typically need noindex.

| Directive | Effect |
|-----------|--------|
| `noindex` | Exclude page from search results |
| `nofollow` | Do not pass link equity through links on the page; **does NOT prevent indexing** |
| `noindex,follow` | Exclude from SERP; allow crawlers to follow links (most common for thank-you, signup, legal) |
| `noindex,nofollow` | Exclude + block link flow (login, staging, test pages) |

**Crawl vs index vs link equity**: robots.txt = crawl control; noindex = index control; nofollow = link equity only. See **robots-txt**, **indexing**.

```html
<meta name="robots" content="noindex, follow">
```

Next.js: `metadata.robots = { index: false, follow: true }`. Default is `index: true, follow: true`.

## Viewport

```html
<meta name="viewport" content="width=device-width, initial-scale=1">
```

Required for mobile-friendly pages; affects Core Web Vitals and mobile search. For full mobile-first indexing and mobile usability requirements, see **mobile-friendly**.

## Charset

```html
<meta charset="UTF-8">
```

Place in `<head>`; first child of `<head>` recommended.

## Output Format

- **hreflang** setup if multi-language
- **Meta robots** if noindex needed
- **Viewport** / **charset** if missing

## Related Skills

- **title-tag, meta-description**: Title and meta description
- **open-graph, twitter-cards**: Social sharing; link previews
- **canonical-tag**: Canonical + hreflang for multi-language
- **indexing**: noindex page-type list; noindex vs nofollow
- **robots-txt**: Crawl vs index; robots.txt vs noindex
- **mobile-friendly**: Mobile-first indexing; viewport required
- **rendering-strategies**: SSR, SSG, CSR; SPAs need sitemap-based hreflang

---
name: internal-links
description: When the user wants to optimize internal linking, fix orphan pages, or improve link structure. Also use when the user mentions "internal links," "internal linking," "anchor text," "link equity," "internal linking strategy," or "orphan pages." For IA, use website-structure.
metadata:
  version: 1.0.1
---

# SEO On-Page: Internal Links

Guides internal linking strategy for SEO: crawlability, link equity distribution, and user navigation.

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope (On-Page SEO)

- **Internal links**: Contextual links; descriptive anchor text; related posts; hub pages
- **Breadcrumbs**: Implement for large sites (e.g. ecommerce); see **breadcrumb-generator**

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for site structure and key pages.

Identify:
1. **Site structure**: Hub pages, pillar content, supporting pages
2. **Orphan pages**: Pages with no or few internal links
3. **Priority pages**: Pages that need more link equity

## Best Practices

### Link Structure

| Principle | Guideline |
|-----------|-----------|
| **Depth** | Important pages within 3 clicks from homepage |
| **Orphan pages** | Avoid; ensure every page has at least one internal link; see **site-crawlability** for technical detection and crawl issues |
| **Hub-to-spoke** | Link from hub/pillar pages to cluster articles; topic cluster structure |
| **Contextual** | Place links in relevant body content, not just footers |

### Anchor Text

| Principle | Guideline |
|-----------|-----------|
| **Descriptive** | Use anchor text that describes the target page |
| **Variation** | Avoid over-optimization; use natural variation |
| **Keyword** | Include target keyword when natural |

### Placement

| Location | Use |
|----------|-----|
| **First paragraph** | Primary link to related content |
| **Body** | Contextual links throughout |
| **Related/Recommended** | End-of-article links |
| **Navigation** | Key site sections |

## Common Issues

| Issue | Fix |
|-------|-----|
| Orphan pages | Add internal links from hub pages or navigation; **site-crawlability** for technical audit |
| Too many links | Focus on most important; avoid link stuffing |
| Generic anchors | Use descriptive "learn more about X" instead of "click here" |
| Broken links | Audit and fix 404s; see **site-crawlability** for technical audit |

## Output Format

- **Internal link audit** (if auditing)
- **Link opportunities** for key pages
- **Anchor text** recommendations
- **Structure** improvements

## Related Skills

- **article-page-generator**: Related posts, contextual links, end-of-article recommendations
- **website-structure**: Plan page structure and hierarchy; informs internal linking
- **site-crawlability**: Internal links enable crawling
- **url-structure**: URL structure affects link patterns
- **content-strategy**: Topic clusters inform link structure; pillar <-> cluster; cluster <-> cluster
- **breadcrumb-generator**: Breadcrumbs are internal links; category hierarchy

---
name: image-optimization
description: When the user wants to optimize images for search engines and performance. Also use when the user mentions "image SEO," "alt text," "image captions," "figcaption," "image optimization," "WebP," "lazy loading," "LCP," "image sitemap," "responsive images," "srcset," "image format," or "hero image optimization." For CWV, use core-web-vitals.
metadata:
  version: 1.2.1
---

# SEO On-Page: Image Optimization

Guides image optimization for Google Search (text results, Image Pack, Google Images, Discover), Core Web Vitals (LCP), and accessibility. Consolidates image-related best practices from components (hero, trust-badges) and pages (landing-page). References: [Google Image SEO](https://developers.google.com/search/docs/appearance/google-images), [Semrush Image SEO](https://www.semrush.com/blog/image-seo/).

**When invoking**: On **first use**, if helpful, open with 1–2 sentences on what this skill covers and why it matters, then provide the main output. On **subsequent use** or when the user asks to skip, go directly to the main output.

## Scope

- **Discovery & indexing**: HTML img elements, image sitemap
- **Format & performance**: WebP, responsive images, lazy loading, LCP; full CWV optimization in **core-web-vitals**
- **Metadata**: Alt text, file names, captions
- **Preferred image**: primaryImageOfPage, og:image; thumbnail next to title/description in search results
- **Structured data**: ImageObject, image in Article/Product/etc.

## Initial Assessment

**Check for project context first:** If `.claude/project-context.md` or `.cursor/project-context.md` exists, read it for brand and page context.

Identify:
1. **Context**: Hero, content page, product, trust badge, social preview
2. **Above vs below fold**: LCP candidate (hero) vs lazy-loadable
3. **Image count**: Single hero vs gallery, programmatic pages

---

## 1. Discovery & Indexing

### Use HTML Image Elements

Google finds images in the `src` attribute of `<img>` (including inside `<picture>`). **CSS background images are not indexed.**

| Do | Don't |
|----|-------|
| `<img src="puppy.jpg" alt="Golden retriever puppy" />` | `<div style="background-image:url(puppy.jpg)">` |

### Image Sitemap

Submit an [image sitemap](https://developers.google.com/search/docs/crawling-indexing/sitemaps/image-sitemaps) to help Google discover images it might otherwise miss. Image sitemaps can include URLs from CDNs (other domains); verify CDN domain in Search Console for crawl error reporting.

**Structure** (from Google):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9"
        xmlns:image="http://www.google.com/schemas/sitemap-image/1.1">
  <url>
    <loc>https://example.com/page</loc>
    <image:image>
      <image:loc>https://example.com/image.jpg</image:loc>
    </image:image>
  </url>
</urlset>
```

See **xml-sitemap** for sitemap index and submission. Image sitemap is an extension; can be standalone or combined with page sitemap.

---

## 2. Format & Performance

### Supported Formats

Google supports: **BMP, GIF, JPEG, PNG, WebP, SVG, AVIF**. Match filename extension to format.

| Format | Best for | Notes |
|--------|----------|-------|
| **WebP** | Photos, graphics | Smaller files, faster load; lossy + lossless; transparency, animation |
| **AVIF** | Modern browsers | Even smaller than WebP; check support |
| **JPEG** | Standard photos | Fallback; widely supported |
| **PNG** | Transparency, detail | Larger; use when needed |
| **SVG** | Icons, logos | Scalable; use `<title>` for inline SVG alt |
| **GIF** | Simple animation | First frame only for preview |

### Responsive Images

Use `<picture>` or `srcset` for different screen sizes. **Always provide fallback `src`**—some crawlers don't understand srcset.

```html
<img
  srcset="image-320w.jpg 320w, image-480w.jpg 480w, image-800w.jpg 800w"
  sizes="(max-width: 320px) 280px, (max-width: 480px) 440px, 800px"
  src="image-800w.jpg"
  alt="Descriptive alt text">
```

**Picture element** (format fallback, e.g. WebP → PNG):

```html
<picture>
  <source type="image/webp" srcset="image.webp">
  <img src="image.png" alt="Descriptive alt text">
</picture>
```

### Data URI (Inline Images)

Base64 data URIs (`data:image/...;base64,...`) reduce HTTP requests but increase HTML size. Use sparingly for small icons; avoid for large images. See [web.dev](https://web.dev/articles/embedding-images-and-video#data_uris).

### Resize & Compress

- **Max width**: Generally ≤2,500px; match container max-width
- **Compression**: WebP preferred; quality 75–85 for lossy; 72dpi for web
- **LCP**: Hero/above-fold images are LCP candidates; optimize aggressively

### Lazy Loading

Use `loading="lazy"` **only for below-fold images**. Above-fold images (hero) must load immediately—lazy loading them hurts LCP.

```html
<img src="hero.jpg" alt="..." loading="eager">
<img src="below-fold.jpg" alt="..." loading="lazy">
```

---

## 3. Alt Text

Alt text improves **accessibility** (screen readers, low bandwidth) and **SEO** (Google uses it with computer vision to understand images). It also serves as anchor text if the image is a link.

### Best Practices

| Do | Don't |
|----|-------|
| Useful, information-rich description | Keyword stuffing |
| Context of page content | "image of" or "photo of" (redundant) |
| Max ~125 characters (some assistive tech truncates) | Empty alt on meaningful images |
| Descriptive for functional images | Alt on purely decorative images (use `alt=""`) |

**Examples** (from Google):

- ❌ Missing: `<img src="puppy.jpg"/>`
- ❌ Stuffing: `alt="puppy dog baby dog pup pups puppies..."`
- ✅ Better: `alt="puppy"`
- ✅ Best: `alt="Dalmatian puppy playing fetch"`

### Captions

Google extracts image context from captions and nearby text. Use `<figcaption>` or descriptive text near the image.

| Use | Purpose |
|-----|---------|
| **Topic relevance** | Caption describes image subject; supports indexing |
| **Featured Snippets** | Images near answers with captions can capture thumbnail slots; see **featured-snippet** |
| **Image Pack** | Alt + caption + file name help Image Pack display; see **serp-features** |

### Inline SVG

Use `<title>` inside SVG for accessibility:

```html
<svg aria-labelledby="svgtitle1">
  <title id="svgtitle1">Descriptive text for the SVG</title>
</svg>
```

---

## 4. File Names

Descriptive filenames give Google light clues about subject matter.

| Do | Don't |
|----|-------|
| `apple-iphone-15-pink-side-view.jpg` | `IMG00353.jpg` |
| Short, hyphen-separated | Generic: `image1.jpg`, `pic.gif` |
| Localize filenames for translated pages | Overly long filenames |

---

## 5. Preferred Image (SERP Thumbnail & Discover)

When users search for keywords, optimized images can appear as **thumbnails next to the page title and description** in search results—enhancing visibility and CTR. Google also uses these images for Google Discover. [Search Engine Land](https://searchengineland.com/google-uses-both-schema-org-markup-and-ogimage-meta-tag-for-thumbnails-in-google-search-and-discover-470598)

Google selects thumbnails automatically from multiple sources. Influence selection via:

### Schema: primaryImageOfPage

```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "url": "https://example.com/page",
  "primaryImageOfPage": "https://example.com/images/cat.png"
}
```

Or attach `image` to main entity (e.g. BlogPosting, Article) via `mainEntity` or `mainEntityOfPage`.

### Open Graph

```html
<meta property="og:image" content="https://example.com/images/cat.png">
```

**Preferred image rules**: Relevant, representative; avoid generic (e.g. logo) or text-heavy images; avoid extreme aspect ratios; high resolution. See **open-graph**, **twitter-cards** for social specs.

**Google Discover** (if targeting Discover): ≥1200px wide; ≥300KB; 16:9 aspect ratio preferred; important content visible in landscape crop.

---

## 6. Page Context

- **Title & meta description**: Google uses page title and meta for image result snippets. See **title-tag**, **meta-description**.
- **Placement**: Put images near relevant text; page subject matter influences image indexing.
- **Same URL**: Reference the same image with the same URL across pages for cache efficiency and crawl budget.

---

## 7. Structured Data

Add structured data for rich results in Google Images (badges, extra info). Image attribute is required for eligibility. See **schema-markup** for ImageObject, Article, Product, Recipe, etc.

---

## 8. Specs by Context

| Context | Priority | Notes |
|---------|----------|-------|
| **Hero** | LCP, alt, no lazy | See **hero-generator**; above-fold, fast load |
| **Article / Blog hero** | 1200–1600px wide; proportional height; 1200×630 for og:image | Same image for Schema, Open Graph, Twitter Cards; under 200 KB; WebP preferred; descriptive alt; set width/height to prevent CLS; use srcset/sizes for responsive; articles with relevant images get ~94% more views |
| **Trust badges** | Alt text | See **trust-badges-generator**; e.g. "Norton Secured" |
| **Landing page** | All above | See **landing-page-generator** Pre-Delivery Checklist |
| **OG / Twitter** | 1200×630, 1200×675 | See **open-graph**, **twitter-cards** |
| **Platforms** | Per-platform | X, LinkedIn, Pinterest—see platform skills |

---

## 9. Opt-Out & SafeSearch

- **Inline linking opt-out**: Prevent full-sized image display in Google Images via HTTP referrer check (200 or 204). See [Google docs](https://developers.google.com/search/docs/appearance/google-images#opt-out).
- **SafeSearch**: Label pages for explicit content if applicable.

---

## Output Format

- **Alt text** suggestions per image
- **Captions** (if applicable; snippet/Image Pack context)
- **File name** recommendations
- **Format** (WebP, fallback)
- **Responsive** (srcset/sizes or picture)
- **Lazy loading** (above-fold vs below-fold)
- **Image sitemap** (if many images)
- **Preferred image** (schema, og:image) for key pages

## Related Skills

- **core-web-vitals**: LCP, INP, CLS; image optimization supports LCP
- **xml-sitemap**: Sitemap structure; image sitemap extension
- **open-graph, twitter-cards**: og:image, twitter:image; social preview
- **schema-markup**: ImageObject, Article/Product image
- **content-optimization**: Multimedia in content; defers image SEO to this skill
- **featured-snippet**: Images near answers + captions; snippet thumbnail
- **serp-features**: Image Pack; alt, captions, file names
- **visual-content**: Visual content for social, infographics; website images use this skill