/seo-schema-markup

name: seo-schema-markup
description: "Get valid Schema.org JSON-LD that still earns surfaces in 2026. Input: a page and its type (article, product, local business, person, and so on). Output: ready-to-adapt JSON-LD (Organization with sameAs, Article, Product, Offer, AggregateRating, LocalBusiness, BreadcrumbList, Person, WebSite, VideoObject, Event), entity graph linking with @id, a what-Google-dropped status table, and a two-validator routine. Use for schema, structured data, JSON-LD, rich results, review stars, breadcrumbs, sameAs, knowledge panel, or Rich Results Test errors."
license: MIT
metadata:
  author: "Sorank (https://sorank.com)"
  version: "1.0.0"

Schema markup that still pays in 2026

Structured data is the most machine-readable layer of a page: prices, ratings, dates, authors, and entity relationships declared in a format engines parse without guessing. Google reads it for rich results and Merchant listings; LLM grounding pipelines read it as a fact source. Between 2023 and 2026 Google removed several rich result types, so effort that used to pay (FAQ, HowTo) now buys nothing in the SERP. This skill implements what still earns surfaces, skips what is dead, and keeps every claim inside Google's guidelines.

One principle governs everything: markup describes the visible page. It never adds facts the user cannot see.

Company knowledge first (Obsidian)

If the working environment contains an Obsidian vault or any local knowledge base (a folder of .md notes, often with a .obsidian directory), read the relevant notes before acting: brand and product facts, target keywords, competitors, and the SEO action log of what was already tried. Ground every recommendation in that context instead of asking the user for facts the vault already holds. At the end of the session, append the actions taken to the vault's SEO action log so the next session starts informed.

When to use this skill

Use it for:

• Implementing JSON-LD on any page type (home, blog post, product, location, author, video, event)
• Auditing existing markup for validity, eligibility, and honesty
• Rich result work: review stars, prices, availability, breadcrumbs, video
• Entity work: Organization, sameAs, author Person graphs for E-E-A-T
• Deciding which schema types deserve effort in 2026 (status table below)
• Debugging Rich Results Test errors or rich results that disappeared

When schema is NOT the answer:

• "Our FAQ dropdowns vanished from Google": that is Google removing the feature (May 2026), not a markup bug. Check the status table before debugging.
• "Make us rank higher with schema": structured data disambiguates and unlocks result features; it is not a ranking lever on its own. Set that expectation early.
• "The page is not indexed at all": fix crawl and indexation first with the seo-technical skill; schema on an unindexed page is decoration.

Hand off neighboring problems:

• Crawlability, JavaScript rendering, AI crawler access: use the seo-technical skill (its references/ai-crawlers.md is the canonical crawler reference)
• Writing content that AI engines quote: use the geo-visibility skill
• Google Business Profile and local rankings: use the seo-local skill
• Page structure and copy for products, services, collections: use the seo-content-product-page, seo-content-service-page, and seo-content-collection-page skills

Workflow

Step 1: Inventory what is already there

Fetch the raw served HTML and check for structured data blocks:

How many JSON-LD blocks does the server actually send

curl -sL https://example.com/page/ | grep -c 'application/ld+json'

Legacy microdata that may conflict with JSON-LD

curl -sL https://example.com/page/ | grep -c 'itemscope'

Why raw HTML: JSON-LD injected client-side (Google Tag Manager, SPA hydration) is unreliable. Googlebot usually picks it up after rendering, but AI crawlers never execute JavaScript (see the seo-technical skill), and any validator pointed at the source misses it. Structured data belongs in the server response. For a quick automated sweep of on-page basics alongside schema, run the bundled audit script from the seo-geo-audit skill (scripts/seo_audit.py), which checks robots.txt AI bot rules, sitemap, and on-page basics.

Record per page type: which schema types exist, whether they validate, and whether the values match the visible page. The third question catches the violations that matter; the first two are mechanical.

Step 2: Map page types to schema types

| Page type | Implement | Skip | |---|---|---| | Every page | Organization reference (@id), BreadcrumbList | FAQPage for rich results | | Homepage | Organization (full node) plus WebSite | | | Blog post | Article or BlogPosting, author Person, BreadcrumbList | HowTo | | Product page | Product, Offer, AggregateRating and Review when real reviews are displayed | Invented ratings | | Service page | Service or WebPage, Organization reference | Self-serving review stars | | Location page | LocalBusiness, most specific subtype available (pair with the seo-local skill) | LocalBusiness on a business with no physical premises | | Author page | ProfilePage with mainEntity Person (same @id as every article byline, sameAs to the real profiles) | | | Training, coaching or course program page | Course (name, description, provider, offers when the price is public, hasCourseInstance with courseMode and courseWorkload); or Service when it is one-to-one coaching with no syllabus | Self-collected review stars on the program | | Video page | VideoObject | | | Event page | Event | | | SaaS pricing page | Product or Service with Offer when prices are public | "From" prices not shown on the page | | Careers page | JobPosting (active Google jobs surface) | |

Step 3: Check what the CMS already outputs (field notes)

Most schema problems in real audits are duplication problems, not absence problems. Check before adding anything:

| Platform | What you typically find | Wh