# schema-markup

> A Claude Code skill that implements schema.org structured data — FAQ, Product, Article, HowTo, Review, Breadcrumb, Organization — to enable rich results in Google and improve AI extractability.

**Use case**: Add structured data that earns rich results

**Canonical URL**: https://agentcookbooks.com/skills/schema-markup/

**Topics**: claude-code, skills, marketing, seo

**Trigger phrases**: "schema markup", "structured data", "JSON-LD", "rich snippets", "FAQ schema"

**Source**: [Corey Haines](https://github.com/coreyhaines31/marketingskills/tree/main/skills/schema-markup)

**License**: MIT

---

## What it does

`schema-markup` is a Claude Code skill from Corey Haines's [marketing-skills repo](https://github.com/coreyhaines31/marketingskills). It turns Claude into a structured-data implementer who picks the right schema type per page (FAQ, Product, Article, HowTo, Review, Breadcrumb, Organization, ItemList for comparisons) and produces JSON-LD that validates against Google's Rich Results Test. The skill activates when you mention "schema markup", "structured data", "JSON-LD", "rich snippets", or "FAQ schema".

The output of a session is a JSON-LD block per page type: validated against schema.org and Rich Results, with required and recommended properties populated, ready to drop into the page head or layout component.

## When to use it

Reach for it when:

- You have FAQs, products, or articles and aren't getting rich results
- You're optimizing for AI Overviews and ChatGPT — schema is a lever there too
- You inherited schema that was wrong or out-of-date

When *not* to reach for it:

- The page itself isn't ranking — schema amplifies, doesn't create rank
- Your CMS injects schema automatically; check before duplicating

## Install

The skill is distributed via Corey Haines's [marketing-skills repo](https://github.com/coreyhaines31/marketingskills). Install via the repo's recommended path — copy the [`schema-markup` SKILL.md](https://github.com/coreyhaines31/marketingskills/tree/main/skills/schema-markup) into your project's `.claude/skills/schema-markup/` directory, or use the repo's plugin install if you've set it up.

Once installed, the skill activates on the trigger phrases above. The first time it runs, it will check for `.agents/product-marketing-context.md` (or `.claude/product-marketing-context.md`) — populating that file with your product context first dramatically improves output quality across all of Haines's marketing skills.

## What a session looks like

A typical session has three phases:

1. **Schema-type selection.** Per page type, the right schema(s). Comparison pages get ItemList, FAQs get FAQPage, products get Product + AggregateRating, blog gets Article + author Person.
2. **JSON-LD generation.** Required and recommended properties populated, no fabricated reviews, no spammy AggregateRating without real data — schema spam is penalized.
3. **Validation step.** A copy-pastable URL to Google's Rich Results Test, plus the warnings and recommendations from validation.

The discipline that makes it work: schema you can defend. Fake reviews and inflated AggregateRating values eventually trigger manual actions; the skill writes only what you can substantiate.

## Receipts

Honest reporting on what `schema-markup` produces and where it has limits:

**Where it works well:**
- The schema-per-page-type matrix saves the "which schema for this page?" decision fatigue
- Validation step catches errors before they ship
- AI extraction (ChatGPT, Perplexity citations) benefits noticeably from clean schema

**Where it backfires:**
- Schema is necessary but not sufficient — bad content with great schema still won't rank
- Some CMS platforms inject conflicting schema; manual audit needed before deploy

**Pattern that works:** start with FAQ and Article schema on existing top-traffic pages. They're the easiest to implement and produce visible rich-result wins fastest.

## Source and attribution

Originally written by [Corey Haines](https://corey.co). The canonical SKILL.md and any supporting files live in the [`schema-markup` folder](https://github.com/coreyhaines31/marketingskills/tree/main/skills/schema-markup) of his [marketing-skills repository](https://github.com/coreyhaines31/marketingskills).

License: MIT. You can install, adapt, and redistribute the skill, with attribution preserved.

This page documents the skill from a practitioner's perspective. For the formal spec and any updates, defer to the source repo.