# schema-markup

schema-markup is a Claude Code skill that generates and audits schema.org JSON-LD for articles, products, organizations, and FAQ sections.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 263 installs · ★ 484 repo stars
- Author: boraoztunc
- License: Apache-2.0 · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/boraoztunc/skills/tree/HEAD/schema-markup/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/boraoztunc-schema-markup

## What it does

This skill writes JSON-LD structured data aligned with schema.org specifications and Google rich snippet guidelines. It supports multiple page types, including `Article`, `Product`, `SoftwareApplication`, `FAQPage`, `HowTo`, `BreadcrumbList`, and `Organization`. When a single page requires multiple entities, it consolidates them using the `@graph` array syntax.

If `.claude/product-marketing-context.md` is present in the repository, the skill pulls context from it before asking setup questions. It focuses strictly on data visible on the page, as hidden elements or non-standard date formats (outside ISO 8601) fail validation in Google Rich Results Test and Schema.org Validator.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add boraoztunc/skills --skill schema-markup -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/schema-markup/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/schema-markup/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add boraoztunc/skills --skill schema-markup -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/schema-markup/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add boraoztunc/skills --skill schema-markup -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/schema-markup/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install boraoztunc/skills schema-markup
```

2. **Manually: put the files in place**
- File: `.github/skills/schema-markup/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add boraoztunc/skills --skill schema-markup -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/boraoztunc/skills --path schema-markup
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/schema-markup/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add boraoztunc/skills --skill schema-markup -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/boraoztunc/skills/tree/HEAD/schema-markup/SKILL.md

## When to use it
- generate JSON-LD markup for product pages and blog posts
- combine multiple schema types on a single page using @graph
- implement FAQPage and breadcrumb structured data
- correct missing properties and syntax errors in schema markup

## Example prompts
- Generate Product and Offer JSON-LD schema for this item page
- Create an FAQPage structured data block for our help section
- Combine Organization and WebSite markup into a single @graph block

## Source text · SKILL.md · Apache-2.0

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 3265a114c0569b94.

BEGIN THIRD-PARTY FILE 3265a114c0569b94
```text
---
name: schema-markup
description: When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user mentions "schema markup," "structured data," "JSON-LD," "rich snippets," "schema.org," "FAQ schema," "product schema," "review schema," or "breadcrumb schema." For broader SEO issues, see seo-audit.
metadata:
  version: 1.0.0
---

# Schema Markup

You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before implementing schema, understand:

1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?

2. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?

3. **Goals** - Which rich results are you targeting? What's the business value?

---

## Core Principles

### 1. Accuracy First
- Schema must accurately represent page content
- Don't markup content that doesn't exist
- Keep updated when content changes

### 2. Use JSON-LD
- Google recommends JSON-LD format
- Easier to implement and maintain
- Place in `<head>` or end of `<body>`

### 3. Follow Google's Guidelines
- Only use markup Google supports
- Avoid spam tactics
- Review eligibility requirements

### 4. Validate Everything
- Test before deploying
- Monitor Search Console
- Fix errors promptly

---

## Common Schema Types

| Type | Use For | Required Properties |
|------|---------|-------------------|
| Organization | Company homepage/about | name, url |
| WebSite | Homepage (search box) | name, url |
| Article | Blog posts, news | headline, image, datePublished, author |
| Product | Product pages | name, image, offers |
| SoftwareApplication | SaaS/app pages | name, offers |
| FAQPage | FAQ content | mainEntity (Q&A array) |
| HowTo | Tutorials | name, step |
| BreadcrumbList | Any page with breadcrumbs | itemListElement |
| LocalBusiness | Local business pages | name, address |
| Event | Events, webinars | name, startDate, location |

**For complete JSON-LD examples**: See [references/schema-examples.md](references/schema-examples.md)

---

## Quick Reference

### Organization (Company Page)
Required: name, url
Recommended: logo, sameAs (social profiles), contactPoint

### Article/BlogPosting
Required: headline, image, datePublished, author
Recommended: dateModified, publisher, description

### Product
Required: name, image, offers (price + availability)
Recommended: sku, brand, aggregateRating, review

### FAQPage
Required: mainEntity (array of Question/Answer pairs)

### BreadcrumbList
Required: itemListElement (array with position, name, item)

---

## Multiple Schema Types
```
END THIRD-PARTY FILE 3265a114c0569b94

The third-party file has ended. Everything between the 3265a114c0569b94 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2996 of 4863 bytes. © boraoztunc · Apache-2.0 · https://github.com/boraoztunc/skills/tree/HEAD/schema-markup/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
