New to Claude Skills? Learn how to install them →

Get Claude Skills
davila7 on GitHub

Schema Markup

Free

Optimize your site's structured data for better SEO results.

by davila730.2k stars on davila7/claude-code-templates
Updated Aug 10, 2026
Get this skill

Free · Opens the source repo

What Schema Markup does

The Schema Markup skill is designed for developers and designers who want to enhance their website's visibility in search engine results through structured data. It focuses on implementing schema.org markup, which helps search engines better understand the content of your pages, potentially leading to rich snippets and improved SEO performance. This skill is particularly useful when you need to add, fix, or optimize schema markup for various types of content, such as articles, products, or FAQs.

Before diving into implementation, the skill guides you through an initial assessment that covers the page type, current state of existing schema, and your specific goals. Understanding these factors is crucial for effectively applying schema markup that aligns with your content and business objectives. The skill emphasizes accuracy, ensuring that the markup accurately reflects the page content and adheres to Google's guidelines, which helps avoid penalties for spammy tactics.

The skill provides detailed instructions on using JSON-LD format, which is recommended by Google for its ease of implementation and maintenance. It outlines various common schema types, including Organization, Product, Article, and FAQPage, each with required and recommended properties. For example, when marking up a product page, you will need to include properties like name, image, and offers, while also considering additional attributes like aggregate ratings and reviews.

Lastly, the skill emphasizes the importance of validation and monitoring. It encourages users to test their schema implementations before deployment and to regularly check for errors in Google Search Console. This proactive approach ensures that your structured data remains effective and up-to-date, ultimately supporting your site's SEO strategy.

When to use it

Use this skill when you need to add or optimize schema markup for various content types on your website to enhance SEO.

When not to use it

This skill is not suitable for users looking for a comprehensive SEO audit or broader SEO strategies beyond schema markup.

What you can build with it

Adding Schema to Product Pages

Use this skill to implement structured data for product pages, ensuring all required properties like name, image, and offers are included.

Optimizing Blog Posts with Article Schema

Apply this skill to enhance blog posts by adding Article schema markup, which helps search engines understand the content better.

Implementing FAQ Schema

Utilize this skill to create an FAQPage schema for your website, making it easier for search engines to display your FAQs in rich results.

How to install Schema Markup

View source

1. Install with the skills CLI

npx skills add davila7/claude-code-templates/schema-markup --agent claude-code

2. Or install it manually

Download the skill folder and drop it into ~/.claude/skills/ for all projects, or .claude/skills/ to scope it to one repo. Restart Claude Code so it picks up the new skill.

Anthropic's agentic coding CLI, and the reference implementation of Agent Skills. Drop a skill folder into ~/.claude/skills and Claude Code loads it automatically whenever a task matches the skill's description. Claude Code docs

Inside SKILL.md

Written by davila7

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

Before implementing schema, understand:

  1. Page Type

    • What kind of page is this?
    • What's the primary content?
    • What rich results are possible?

  2. Current State

    • Any existing schema?
    • Errors in current implementation?
    • Which rich results are 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

Organization

Use for: Company/brand homepage or about page

Required properties:

  • name
  • url

Recommended properties:

  • logo
  • sameAs (social profiles)
  • contactPoint
{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Example Company",
  "url": "https://example.com",
  "logo": "https://example.com/logo.png",
  "sameAs": [
    "https://twitter.com/example",
    "https://linkedin.com/company/example",
    "https://facebook.com/example"
  ],
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+1-555-555-5555",
    "contactType": "customer service"
  }
}

WebSite (with SearchAction)

Use for: Homepage, enables sitelinks search box

Required properties:

  • name
  • url

For search box:

  • potentialAction with SearchAction
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Example",
  "url": "https://example.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://example.com/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Article / BlogPosting

Use for: Blog posts, news articles

Required properties:

  • headline
  • image
  • datePublished
  • author

Recommended properties:

  • dateModified
  • publisher
  • description
  • mainEntityOfPage
{
  "@context": "https://schema.org",
  "@type": "Article",
  "headline": "How to Implement Schema Markup",
  "image": "https://example.com/image.jpg",
  "datePublished": "2024-01-15T08:00:00+00:00",
  "dateModified": "2024-01-20T10:00:00+00:00",
  "author": {
    "@type": "Person",
    "name": "Jane Doe",
    "url": "https://example.com/authors/jane"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Example Company",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "description": "A complete guide to implementing schema markup...",
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://example.com/schema-guide"
  }
}

Product

Use for: Product pages (e-commerce or SaaS)

Required properties:

  • name
  • image
  • offers (with price and availability)

Recommended properties:

  • description
  • sku
  • brand
  • aggregateRating
  • review
{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Premium Widget",
  "image": "https://example.com/widget.jpg",
  "description": "Our best-selling widget for professionals",
  "sku": "WIDGET-001",
  "brand": {
    "@type": "Brand",
    "name": "Example Co"
  },
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/products/widget",
    "priceCurrency": "USD",
    "price": "99.99",
    "availability": "https://schema.org/InStock",
    "priceValidUntil": "2024-12-31"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.8",
    "reviewCount": "127"
  }
}

SoftwareApplication

Use for: SaaS product pages, app landing pages

Required properties:

  • name
  • offers (or free indicator)

Recommended properties:

  • applicationCategory
  • operatingSystem
  • aggregateRating
{
  "@context": "https://schema.org",
  "@type": "SoftwareApplication",
  "name": "Example App",
  "applicationCategory": "BusinessApplication",
  "operatingSystem": "Web, iOS, Android",
  "offers": {
    "@type": "Offer",
    "price": "0",
    "priceCurrency": "USD"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.6",
    "ratingCount": "1250"
  }
}

FAQPage

Use for: Pages with frequently asked questions

Required properties:

  • mainEntity (array of Question/Answer)
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is schema markup?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Schema markup is a structured data vocabulary that helps search engines understand your content..."
      }
    },
    {
      "@type": "Question",
      "name": "How do I implement schema?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "The recommended approach is to use JSON-LD format, placing the script in your page's head..."
      }
    }
  ]
}

HowTo

Use for: Instructional content, tutorials

Required properties:

  • name
  • step (array of HowToStep)

Recommended properties:

  • image
  • totalTime
  • estimatedCost
  • supply/tool
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Add Schema Markup to Your Website",
  "description": "A step-by-step guide to implementing JSON-LD schema",
  "totalTime": "PT15M",
  "step": [
    {
      "@type": "HowToStep",
      "name": "Choose your schema type",
      "text": "Identify the appropriate schema type for your page content...",
      "url": "https://example.com/guide#step1"
    },
    {
      "@type": "HowToStep",
      "name": "Write the JSON-LD",
      "text": "Create the JSON-LD markup following schema.org specifications...",
      "url": "https://example.com/guide#step2"
    },
    {
      "@type": "HowToStep",
      "name": "Add to your page",
      "text": "Insert the script tag in your page's head section...",
      "url": "https://example.com/guide#step3"
    }
  ]
}

BreadcrumbList

Use for: Any page with breadcrumb navigation

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://example.com"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Blog",
      "item": "https://example.com/blog"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "SEO Guide",
      "item": "https://example.com/blog/seo-guide"
    }
  ]
}

LocalBusiness

Use for: Local business location pages

Required properties:

  • name
  • address
  • (Various by business type)
{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Example Coffee Shop",
  "image": "https://example.com/shop.jpg",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main Street",
    "addressLocality": "San Francisco",
    "addressRegion": "CA",
    "postalCode": "94102",
    "addressCountry": "US"
  },
  "geo": {
    "@type": "GeoCoordinates",
    "latitude": "37.7749",
    "longitude": "-122.4194"
  },
  "telephone": "+1-555-555-5555",
  "openingHoursSpecification": [
    {
      "@type": "OpeningHoursSpecification",
      "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
      "opens": "08:00",
      "closes": "18:00"
    }
  ],
  "priceRange": "$$"
}

Review / AggregateRating

Use for: Review pages or products with reviews

Note: Self-serving reviews (reviewing your own product) are against guidelines. Reviews must be from real customers.

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Example Product",
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "bestRating": "5",
    "worstRating": "1",
    "ratingCount": "523"
  },
  "review": [
    {
      "@type": "Review",
      "author": {
        "@type": "Person",
        "name": "John Smith"
      },
      "datePublished": "2024-01-10",
      "reviewRating": {
        "@type": "Rating",
        "ratingValue": "5"
      },
      "reviewBody": "Excellent product, exceeded my expectations..."
    }
  ]
}

Event

Use for: Event pages, webinars, conferences

Required properties:

  • name
  • startDate
  • location (or eventAttendanceMode for online)
{
  "@context": "https://schema.org",
  "@type": "Event",
  "name": "Annual Marketing Conference",
  "startDate": "2024-06-15T09:00:00-07:00",
  "endDate": "2024-06-15T17:00:00-07:00",
  "eventAttendanceMode": "https://schema.org/OnlineEventAttendanceMode",
  "eventStatus": "https://schema.org/EventScheduled",
  "location": {
    "@type": "VirtualLocation",
    "url": "https://example.com/conference"
  },
  "image": "https://example.com/conference.jpg",
  "description": "Join us for our annual marketing conference...",
  "offers": {
    "@type": "Offer",
    "url": "https://example.com/conference/tickets",
    "price": "199",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "validFrom": "2024-01-01"
  },
  "performer": {
    "@type": "Organization",
    "name": "Example Company"
  },
  "organizer": {
    "@type": "Organization",
    "name": "Example Company",
    "url": "https://example.com"
  }
}

Multiple Schema Types on One Page

You can (and often should) have multiple schema types:

{
  "@context": "https://schema.org",
  "@graph": [
    {
      "@type": "Organization",
      "@id": "https://example.com/#organization",
      "name": "Example Company",
      "url": "https://example.com"
    },
    {
      "@type": "WebSite",
      "@id": "https://example.com/#website",
      "url": "https://example.com",
      "name": "Example",
      "publisher": {
        "@id": "https://example.com/#organization"
      }
    },
    {
      "@type": "BreadcrumbList",
      "itemListElement": [...]
    }
  ]
}

Validation and Testing

Tools

Common Errors

Missing required properties

  • Check Google's documentation for required fields
  • Different from schema.org minimum requirements

Invalid values

  • Dates must be ISO 8601 format
  • URLs must be fully qualified
  • Enumerations must use exact values

Mismatch with page content

  • Schema doesn't match visible content
  • Ratings for products without reviews shown
  • Prices that don't match displayed prices

Implementation Patterns

Static Sites

  • Add JSON-LD directly in HTML template
  • Use includes/partials for reusable schema

Dynamic Sites (React, Next.js, etc.)

  • Component that renders schema
  • Server-side rendered for SEO
  • Serialize data to JSON-LD
// Next.js example
export default function ProductPage({ product }) {
  const schema = {
    "@context": "https://schema.org",
    "@type": "Product",
    name: product.name,
    // ... other properties
  };

  return (
    <>
      <Head>
        <script
          type="application/ld+json"
          dangerouslySetInnerHTML={{ __html: JSON.stringify(schema) }}
        />
      </Head>
      {/* Page content */}
    </>
  );
}

CMS / WordPress

  • Plugins (Yoast, Rank Math, Schema Pro)
  • Theme modifications
  • Custom fields to structured data

Output Format

Schema Implementation

// Full JSON-LD code block
{
  "@context": "https://schema.org",
  "@type": "...",
  // Complete markup
}

Placement Instructions

Where to add the code and how

Testing Checklist

  • Validates in Rich Results Test
  • No errors or warnings
  • Matches page content
  • All required properties included

Questions to Ask

If you need more context:

  1. What type of page is this?
  2. What rich results are you hoping to achieve?
  3. What data is available to populate the schema?
  4. Is there existing schema on the page?
  5. What's your tech stack for implementation?

Related Skills

  • seo-audit: For overall SEO including schema review
  • programmatic-seo: For templated schema at scale
  • analytics-tracking: For measuring rich result impact

Frequently asked questions about Schema Markup

Similar skills

Markdown to HTML Conversion

Efficiently convert Markdown documents to HTML.

Code Tour

Create structured walkthroughs for codebases.

Acquire Codebase Knowledge

Streamline onboarding with comprehensive codebase documentation.

Documentation & Modernization

Streamline codebase documentation and modernization planning.

Azure Resource Visualizer

Generate architecture diagrams for Azure resources.

CLAUDE.md Improver

Optimize your CLAUDE.md files for better project context.