New to Claude Skills? Learn how to install them →

Get Claude Skills
zubair-trabzada on GitHub

Geo Schema

Free

Optimize structured data for AI discoverability.

by zubair-trabzada9.3k stars on zubair-trabzada/geo-seo-claude
Updated Aug 10, 2026
Get this skill

Free · Opens the source repo

What Geo Schema does

Geo Schema is a specialized tool designed to enhance the visibility of entities through structured data. By leveraging Schema.org standards, this skill assists developers and designers in conducting thorough audits of existing structured data on web pages, ensuring that it is not only valid but also optimized for AI platforms. The skill focuses on generating JSON-LD markup, which is the preferred format for AI systems, enhancing the chances of being recognized and cited by various AI search engines.

The process begins with fetching the HTML of the target page using the provided fetch_page.py script, which accurately captures the necessary structured data elements. It then scans for existing JSON-LD, Microdata, and RDFa formats, validating their compliance with Schema.org specifications. This validation covers crucial aspects such as required properties, URL validity, and proper nesting, ensuring that the structured data is robust and ready for AI interpretation.

Geo Schema is particularly beneficial for businesses, publishers, and e-commerce sites aiming to improve their online presence. By identifying missing recommended schemas based on the type of business, the skill facilitates the generation of complete and accurate JSON-LD code blocks. This not only aids in enhancing the entity's discoverability but also aligns with the latest guidelines from AI platforms regarding structured data.

In summary, Geo Schema serves as an essential tool for anyone looking to optimize their web pages for AI discoverability through structured data. Its focus on JSON-LD and compliance with Schema.org standards makes it a valuable asset for developers and designers aiming to improve their site's visibility and citation potential across AI search platforms.

When to use it

Use this skill when you need to audit and enhance the structured data on your web pages for improved AI recognition.

When not to use it

This skill may not be suitable if you are not working with structured data or do not require AI discoverability enhancements.

What you can build with it

Business Website Optimization

A local business uses Geo Schema to validate and enhance its structured data, ensuring it appears prominently in local AI search results.

Publisher Article Markup

An online magazine employs Geo Schema to generate JSON-LD for its articles, improving their discoverability and E-E-A-T signals across AI platforms.

E-commerce Product Listings

An e-commerce site utilizes Geo Schema to audit and optimize its product schema, leading to better visibility and engagement in AI-driven search results.

How to install Geo Schema

View source

1. Install with the skills CLI

npx skills add zubair-trabzada/geo-seo-claude/geo-schema --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 zubair-trabzada

GEO Schema & Structured Data

Purpose

Structured data is the primary machine-readable signal that tells AI systems what an entity IS, what it does, and how it connects to other entities. While schema markup has traditionally been about earning Google rich results, its role in GEO is fundamentally different: structured data is how AI models understand and trust your entity. A complete entity graph in structured data dramatically increases citation probability across all AI search platforms.

How to Use This Skill

  1. Fetch the target page HTML using fetch_page.py (see note below)
  2. Detect all existing structured data (JSON-LD, Microdata, RDFa)
  3. Validate detected schemas against Schema.org specifications
  4. Identify missing recommended schemas based on business type
  5. Generate ready-to-use JSON-LD code blocks
  6. Output GEO-SCHEMA-REPORT.md

Step 1: Detection

IMPORTANT: WebFetch converts HTML to markdown and strips <head> content, which removes JSON-LD blocks. Use fetch_page.py instead:

python3 ~/.claude/skills/geo/scripts/fetch_page.py <url> page

The output includes a structured_data array with all parsed JSON-LD blocks from the page.

Scan for JSON-LD

Look for <script type="application/ld+json"> blocks in the HTML. Parse each block as JSON. A page may contain multiple JSON-LD blocks — collect all of them.

Scan for Microdata

Look for elements with itemscope, itemtype, and itemprop attributes. Map the hierarchy of nested items. Note: Microdata is harder for AI crawlers to parse than JSON-LD. Flag a recommendation to migrate to JSON-LD if Microdata is the only format found.

Scan for RDFa

Look for elements with typeof, property, and vocab attributes. Similar to Microdata — recommend migration to JSON-LD.

Priority Order

JSON-LD is the strongly recommended format for GEO. Google, Bing, and AI platforms all process JSON-LD most reliably. If the site uses Microdata or RDFa exclusively, flag this as a high-priority migration.

Step 2: Validation

For each detected schema block, validate:

  1. Valid JSON: Is the JSON-LD syntactically valid? Check for trailing commas, unquoted keys, malformed strings.
  2. Valid @type: Does the @type match a recognized Schema.org type? Check against https://schema.org/docs/full.html.
  3. Required Properties: Does the schema include all required properties for its type? (See per-type requirements below.)
  4. Recommended Properties: Does the schema include recommended properties that increase AI discoverability?
  5. sameAs Links: Does the schema include sameAs properties linking to other platform presences?
  6. URL Validity: Do all URLs in the schema resolve (not 404)?
  7. Nesting: Is the schema properly nested (e.g., author inside Article, address inside Organization)?
  8. Rendering Method: Is the JSON-LD in the server-rendered HTML or injected via JavaScript? Per Google's December 2025 guidance, JavaScript-injected structured data may face delayed processing. Flag any schema that requires JS execution.

Step 3: Schema Types for GEO

Organization (CRITICAL — every business site)

Essential for entity recognition across all AI platforms. This is how AI models identify WHAT the business is.

Required properties:

  • @type: "Organization" (or subtype: Corporation, LocalBusiness, etc.)
  • name: Official business name
  • url: Official website URL
  • logo: URL to logo image (ImageObject preferred)

Recommended properties for GEO:

  • sameAs: Array of ALL platform URLs (see sameAs strategy below)
  • description: 1-2 sentence description of the organization
  • foundingDate: ISO 8601 date
  • founder: Person schema
  • address: PostalAddress schema
  • contactPoint: ContactPoint with telephone, email, contactType
  • areaServed: Geographic area
  • numberOfEmployees: QuantitativeValue
  • industry: Text or DefinedTerm
  • award: Array of awards received
  • knowsAbout: Array of topics the organization is expert in (strong GEO signal)

LocalBusiness (for businesses with physical locations)

Extends Organization. Critical for local AI search results and Google Gemini.

Additional required properties:

  • address: Full PostalAddress
  • telephone: Phone number
  • openingHoursSpecification: Operating hours

Recommended for GEO:

  • geo: GeoCoordinates (latitude, longitude)
  • priceRange: Price indicator
  • aggregateRating: AggregateRating schema
  • review: Array of Review schemas
  • hasMap: URL to Google Maps

Article + Author (CRITICAL for publishers)

The Author schema is one of the strongest E-E-A-T signals for AI platforms.

Article required:

  • @type: "Article" (or NewsArticle, BlogPosting, TechArticle)
  • headline: Article title
  • datePublished: ISO 8601
  • dateModified: ISO 8601 (critical for freshness signals)
  • author: Person or Organization schema
  • publisher: Organization schema with logo
  • image: Representative image

Author (Person) required for GEO:

  • name: Full name
  • url: Author page URL on the site
  • sameAs: LinkedIn, Twitter, personal site, Google Scholar, ORCID
  • jobTitle: Professional title
  • worksFor: Organization schema
  • knowsAbout: Array of expertise areas
  • alumniOf: Educational institutions
  • award: Professional awards

Product (for e-commerce)

Required:

  • name, description, image
  • offers: Offer with price, priceCurrency, availability
  • brand: Brand schema
  • sku or gtin/mpn

Recommended for GEO:

  • aggregateRating: AggregateRating
  • review: Array of individual reviews
  • category: Product category
  • material, weight, width, height (where applicable)

FAQPage

Status as of 2024: Google restricts FAQ rich results to government and health sites. However, the FAQPage schema still serves GEO purposes — AI platforms parse FAQ structured data for question-answer extraction. Implement it for AI readability even though rich results may not appear.

Structure:

  • @type: "FAQPage"
  • mainEntity: Array of Question schemas, each with acceptedAnswer containing an Answer schema

SoftwareApplication (for SaaS)

Required:

  • name, description
  • applicationCategory: e.g., "BusinessApplication"
  • operatingSystem: Supported platforms
  • offers: Pricing

Recommended for GEO:

  • aggregateRating: User ratings
  • featureList: Array of features (strong citation signal)
  • screenshot: Screenshots
  • softwareVersion: Current version
  • releaseNotes: Link to changelog

WebSite + SearchAction (for sitelinks search box)

Structure:

{
  "@type": "WebSite",
  "name": "Site Name",
  "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"
  }
}

Person (standalone — for personal brands, authors, thought leaders)

Use as a standalone schema on About/Bio pages. This builds the entity graph for individual expertise.

Required: name, url Recommended for GEO: sameAs, jobTitle, worksFor, knowsAbout, alumniOf, award, description, image

speakable Property (for voice/AI assistants)

The speakable property marks specific sections of content as particularly suitable for voice and AI assistant consumption. Add to Article or WebPage schemas.

{
  "@type": "Article",
  "speakable": {
    "@type": "SpeakableSpecification",
    "cssSelector": [".article-summary", ".key-takeaway"]
  }
}

This signals to AI assistants which passages are the best candidates for citation or reading aloud.

Step 4: Deprecated/Changed Schemas to Flag

SchemaStatusNote
HowToRich results deprecated Aug 2023Still useful for AI parsing, but do not promise rich results
FAQPageRestricted to govt/health Aug 2023Still useful for AI parsing (see above)
SpecialAnnouncementDeprecated 2023Was for COVID; remove if still present
CourseInfoReplaced by Course updates 2024Use updated Course schema properties
VideoObject contentUrlChanged behavior 2024Must point to actual video file, not page URL
Review snippetStricter enforcement 2024Self-serving reviews on product pages may not display

Flag any deprecated schemas found and recommend replacements.

Step 5: sameAs Strategy (CRITICAL for Entity Recognition)

The sameAs property is the single most important structured data property for GEO. It tells AI systems: "This entity on my website is the SAME entity as these profiles elsewhere." This creates the entity graph that AI platforms use to verify, trust, and cite sources.

Recommended sameAs Links (in priority order)

  1. Wikipedia article — highest authority entity link
  2. Wikidata item — machine-readable entity identifier (e.g., https://www.wikidata.org/wiki/Q12345)
  3. LinkedIn — company page or personal profile
  4. YouTube — channel URL
  5. Twitter/X — profile URL
  6. Facebook — page URL
  7. Crunchbase — company profile (for startups/tech)
  8. GitHub — organization or personal profile (for tech)
  9. Google Scholar — author profile (for researchers/academics)
  10. ORCID — researcher identifier (for academics)
  11. Instagram — profile URL
  12. Apple App Store / Google Play — app listings (for software)
  13. BBB — Better Business Bureau listing (for US businesses)
  14. Industry directories — relevant vertical directories

sameAs Audit Process

  1. Collect all known web presences for the entity
  2. Check that each URL resolves (not 404 or redirected)
  3. Verify the Organization/Person schema includes ALL of them
  4. Check that the information on each platform is consistent (name, description, founding date, etc.)
  5. Flag any platforms where the entity should have a presence but does not

Step 6: JSON-LD Generation

Based on the detected business type, generate ready-to-paste JSON-LD blocks. Always generate:

  1. Organization or Person (depending on entity type) — always
  2. WebSite with SearchAction — always for the homepage
  3. Business-type-specific — Article for publishers, Product for e-commerce, LocalBusiness for local, SoftwareApplication for SaaS
  4. BreadcrumbList — for any page deeper than homepage

Generation Rules

  • Use the @graph pattern to include multiple schemas in one JSON-LD block
  • All URLs must be absolute (not relative)
  • Include @id properties for cross-referencing between schemas
  • Use ISO 8601 for all dates
  • Include speakable on Article schemas with CSS selectors pointing to key content sections
  • Place JSON-LD in <head> section — NOT injected via JavaScript

Template: Organization with Full GEO Signals

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "@id": "https://example.com/#organization",
  "name": "Company Name",
  "url": "https://example.com",
  "logo": {
    "@type": "ImageObject",
    "url": "https://example.com/logo.png",
    "width": 600,
    "height": 60
  },
  "description": "Concise description of what the company does.",
  "foundingDate": "2020-01-15",
  "founder": {
    "@type": "Person",
    "name": "Founder Name",
    "sameAs": "https://www.linkedin.com/in/founder"
  },
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "City",
    "addressRegion": "State",
    "postalCode": "12345",
    "addressCountry": "US"
  },
  "contactPoint": {
    "@type": "ContactPoint",
    "telephone": "+1-555-555-5555",
    "contactType": "customer service",
    "email": "support@example.com"
  },
  "sameAs": [
    "https://en.wikipedia.org/wiki/Company_Name",
    "https://www.wikidata.org/wiki/Q12345",
    "https://www.linkedin.com/company/company-name",
    "https://www.youtube.com/@companyname",
    "https://twitter.com/companyname",
    "https://github.com/companyname",
    "https://www.crunchbase.com/organization/company-name"
  ],
  "knowsAbout": [
    "Topic 1",
    "Topic 2",
    "Topic 3"
  ]
}

Scoring Rubric (0-100)

CriterionPointsHow to Score
Organization/Person schema present and complete1515 if full, 10 if basic, 0 if none
sameAs links (5+ platforms)153 per valid sameAs link, max 15
Article schema with author details1010 if full author schema, 5 if name only, 0 if none
Business-type-specific schema present1010 if complete, 5 if partial, 0 if missing
WebSite + SearchAction55 if present, 0 if not
BreadcrumbList on inner pages55 if present, 0 if not
JSON-LD format (not Microdata/RDFa)55 if JSON-LD, 3 if mixed, 0 if only Microdata/RDFa
Server-rendered (not JS-injected)1010 if in HTML source, 5 if JS but in head, 0 if dynamic JS
speakable property on articles55 if present, 0 if not
Valid JSON + valid Schema.org types1010 if no errors, 5 if minor issues, 0 if major errors
knowsAbout property on Organization/Person55 if present with 3+ topics, 0 if missing
No deprecated schemas present55 if clean, 0 if deprecated schemas found

Output Format

Generate GEO-SCHEMA-REPORT.md with:

# GEO Schema & Structured Data Report — [Domain]
Date: [Date]

## Schema Score: XX/100

## Detected Schemas
| Page | Schema Type | Format | Status | Issues |
|---|---|---|---|---|
| / | Organization | JSON-LD | Valid | Missing sameAs |
| /blog/post-1 | Article | JSON-LD | Valid | No author schema |

## Validation Results
[List each schema with pass/fail per property]

## Missing Recommended Schemas
[List schemas that should be present based on business type but are not]

## sameAs Audit
| Platform | URL | Status |
|---|---|---|
| Wikipedia | [URL or "Not found"] | Present/Missing |
| LinkedIn | [URL or "Not found"] | Present/Missing |
[Continue for all recommended platforms]

## Generated JSON-LD Code
[Ready-to-paste JSON-LD blocks for each missing or incomplete schema]

## Implementation Notes
- Where to place each JSON-LD block
- Server-rendering requirements
- Testing with Google Rich Results Test and Schema.org Validator

Frequently asked questions about Geo Schema

Similar skills

WinMD API Search

Easily find and explore Windows desktop APIs.

WebMCPify

Transform any web app into an agent-ready platform.

Phoenix Tracing

Instrument LLM applications with OpenInference tracing.

Foundry Hosted Agent CopilotKit

Guidance for developing agentic web apps on Azure.

Power Automate Foundation

Connect AI agents to Power Automate seamlessly.

Power Automate Flow Builder

Efficiently build and deploy Power Automate flows programmatically.